FrankenPHP + Docker + Custom HTTPS (laravel.test) Setup Guide for Local Development

franken-local-dev.md

FrankenPHP + Docker + Custom HTTPS (laravel.test) Setup Guide

A step‑by‑step guide to run your Laravel app with FrankenPHP in “classic mode” inside Docker, using your own locally‑trusted HTTPS certificates.

---

📋 Prerequisites

• Docker Desktop installed and running
• PowerShell on Windows
• mkcert installed & CA trusted (via choco install mkcert + mkcert -install)
• Your Laravel project checked out at, e.g.:

  C:\Users\<username>\Projects\my-laravel-app
  

• A local domain entry in your hosts file:

  127.0.0.1 laravel.test
  

---

🔐 Generate & Trust a Local Certificate

1. Create a folder to hold your certs:

   md C:\Users\<username>\.certs
   cd C:\Users\<username>\.certs

Note

Replace <username> with your actual Windows username.

2. Generate a cert for laravel.test:

   mkcert -cert-file laravel.test.crt -key-file laravel.test.key laravel.test

3. Verify that Windows trusts the mkcert CA:

   certlm.msc
   # Check under "Trusted Root Certification Authorities → Certificates" for "mkcert development CA"

---

🗂️ Project Structure

my-laravel-app/
├── public/
│   └── index.php
├── .certs/
│   ├── laravel.test.crt
│   └── laravel.test.key
├── Caddyfile
└── …other Laravel files…

Note: You can place .certs/ either in your project root or anywhere on disk—just update the Docker mount accordingly.

---

⚙️ Caddyfile (classic mode)

Create Caddyfile in your project root with:

laravel.test {
    root * /app/public
    php_fastcgi frankenphp
    file_server

    tls /certs/laravel.test.crt /certs/laravel.test.key
}

• root * /app/public → points to Laravel’s web root
• php_fastcgi frankenphp → uses FrankenPHP’s embedded PHP
• tls → points to your mkcert‑generated .crt & .key

---

🐳 Docker Command (PowerShell)

From inside C:\Users\david\Projects\my-laravel-app, run:

docker run --rm `
  -p 80:80 -p 443:443 -p 443:443/udp `
  -v ${PWD}:/app `
  -v "C:\Users\<username>\.certs:/certs" `
  -v ${PWD}/Caddyfile:/etc/frankenphp/Caddyfile `
  dunglas/frankenphp

Note

Replace <username> with your actual Windows username.

• ${PWD}:/app → mounts your app into the container
• C:\Users\<username>\.certs:/certs → mounts certs directory
• ${PWD}/Caddyfile:/etc/frankenphp/Caddyfile → overrides default Caddy config

---

✅ Verify & Troubleshoot

1. Clear browser cache (Edge/Chrome) if you get stale warnings.

2. Visit: https://laravel.test → you should see your app with a secure lock.

3. If you still see “Not secure”:

   • Confirm mkcert development CA is in Local Machine → Trusted Root store

   • Run an interactive shell:

     docker run -it --rm -v ${PWD}:/app -v "C:\Users\<username>\.certs:/certs" -v ${PWD}/Caddyfile:/etc/frankenphp/Caddyfile dunglas/frankenphp sh

     # inside container
     caddy validate --config /etc/frankenphp/Caddyfile

Note

Replace <username> with your actual Windows username.

4. Check logs in your terminal for Caddy/PHP errors.