website/docs/superpowers/specs/2026-04-25-docker-compose-dev-environment-design.md

# Docker Compose Dev Environment — Design Spec

## Overview

Replace the bare-metal `composer run dev` workflow (which assumes host-installed PHP 8.3, Node 24, MariaDB, Valkey/Redis, and Mailpit) with a fully-containerized multi-service stack orchestrated by `docker compose`. Removes the `laravel/sail` dev dependency. The stack runs the existing single Laravel application — including its three subdomains (`marketing`, `account`, `admin`) — across 9 purpose-built services on a single Compose project.

## Goals

- Single command (`docker compose up -d` or `make up`) brings up the entire dev environment from a fresh clone
- All three subdomains reachable in the browser with TLS
- Hot-reloading frontend assets via Vite, Horizon dashboard, scheduled jobs, queue workers, and trapped outgoing mail
- Dev/prod parity: nginx + PHP-FPM (matches likely Kubernetes target), official MariaDB & Valkey images
- No `/etc/hosts` edits, no host-side Node/PHP installs required
- Existing `composer run dev` flow stays usable for anyone who prefers bare-metal — Docker stack reads its own `.env.docker`, doesn't fight `website/.env`

## Non-Goals

- Production Dockerfiles / Helm charts (separate workstream; this Dockerfile is dev-tuned)
- Mocking external provisioning APIs (VirtFusion, SynergyCP, Pterodactyl, Enhance) — those stay external, configured via env
- HTTPS with locally-trusted CA (mkcert) — using Traefik self-signed; revisit if cert warnings become annoying

## Architecture

### Service map (9 services)

| # | Service | Image | Role | Exposed via |
|---|---------|-------|------|-------------|
| 1 | `traefik` | `traefik:v3.6` | Edge proxy + TLS termination + routing | Host ports 80, 443, 8080 |
| 2 | `app` | custom (`docker/app/Dockerfile`) | PHP 8.3-FPM | Internal only |
| 3 | `web` | `nginx:1.30-alpine` | Serves `public/`, proxies PHP to `app:9000` | Traefik → 3 vhosts |
| 4 | `vite` | custom (`docker/vite/Dockerfile`) | `npm run dev` for HMR | Traefik → `vite.ezscale.docker.localhost` |
| 5 | `horizon` | same image as `app` | `php artisan horizon` | Internal |
| 6 | `scheduler` | same image as `app` | `php artisan schedule:work` | Internal |
| 7 | `mariadb` | `mariadb:12` | Primary database (utf8mb4 + utf8mb4_unicode_ci pinned) | Internal |
| 8 | `valkey` | `valkey/valkey:9-alpine` | Sessions, cache, queues | Internal |
| 9 | `mailpit` | `axllent/mailpit:v1.29` | SMTP catcher + UI | Traefik → `mail.ezscale.docker.localhost` |

### Image base decisions

- **PHP container**: `php:8.3-fpm-bookworm` (Debian) — chosen over Alpine because (a) `musl` DNS edge cases are a real risk for an app calling many external APIs (Stripe, PayPal, VirtFusion, SynergyCP, Pterodactyl, MaxMind, Outlook IMAP), (b) extension-install Dockerfile is half as complex on Debian, (c) Forge/Vapor and most public Laravel images on Kubernetes use Debian, (d) the 245MB image-size delta is paid once per node per image SHA. Easy to swap later — Dockerfile is structured so `FROM` swap is the only mechanical change.
- **Other Linux services**: Alpine where official Alpine variants exist (nginx, vite, valkey).
- **MariaDB & Mailpit**: no official Alpine; MariaDB stays Debian, Mailpit is already FROM-scratch single-binary.
- **Traefik**: scratch-based; smaller than Alpine.

### Hostnames (browser-facing)

- `https://ezscale.docker.localhost` — marketing site
- `https://account.ezscale.docker.localhost` — customer dashboard
- `https://admin.ezscale.docker.localhost` — admin panel
- `https://account.ezscale.docker.localhost/horizon` — Horizon dashboard
- `https://mail.ezscale.docker.localhost` — Mailpit UI
- `https://vite.ezscale.docker.localhost` — Vite dev server
- `http://localhost:8080` — Traefik dashboard (insecure, dev-only)

`*.docker.localhost` resolves to `127.0.0.1` natively in modern browsers — no `/etc/hosts` edits.

### TLS strategy

Traefik auto-generates a single wildcard self-signed cert covering `ezscale.docker.localhost` and `*.ezscale.docker.localhost`. Browser shows a warning on first visit; after accepting, all subdomains share the trust decision. Configured in `docker/traefik/dynamic.yml` via `tls.stores.default.defaultGeneratedCert`.

### Subdomain routing

Traefik routes the three Laravel subdomains (marketing/account/admin) to the same `web` (nginx) container. Nginx uses a single catch-all `server_name _;` block. Laravel's existing `Route::domain(config('app.domains.*'))` in `bootstrap/app.php` handles the per-subdomain dispatch internally — no per-subdomain nginx vhost needed.

Vite (port 5173) and Mailpit (port 8025) are routed to their own containers via separate Traefik label rules.

### Service dependency graph

```
mariadb (healthcheck: mariadb-admin ping) ─┐
valkey  (healthcheck: valkey-cli ping)     ─┼──► app ──► web ──► traefik
                                           │      │
                                           │      ├──► horizon
                                           │      └──► scheduler
mailpit (no healthcheck needed)            ─┘
vite ──► traefik (independent of app)
```

`app`, `horizon`, and `scheduler` use `depends_on` with `condition: service_healthy` for `mariadb` and `valkey`. They share the same image and bind-mount the same `website/` source — they differ only in `command:`.

## Directory layout

All Docker artifacts under a new `docker/` sibling of `website/`. Nothing inside `website/` is restructured.

```
/home/andrew/local_projects/website/
├── docker-compose.yml                ← NEW
├── .env.docker.example               ← NEW (committed template)
├── .env.docker                       ← NEW (gitignored, copied from example)
├── Makefile                          ← NEW (ergonomic shortcuts)
├── docker/
│   ├── README.md
│   ├── app/
│   │   ├── Dockerfile
│   │   ├── php.ini
│   │   ├── opcache.ini
│   │   ├── php-fpm.conf
│   │   └── entrypoint.sh
│   ├── nginx/
│   │   ├── Dockerfile
│   │   ├── nginx.conf
│   │   └── conf.d/ezscale.conf
│   ├── traefik/
│   │   ├── traefik.yml
│   │   └── dynamic.yml
│   ├── vite/
│   │   └── Dockerfile
│   └── mariadb/
│       └── init/01-create-test-db.sql
└── website/                          ← unchanged
```

## App container — extensions and config

PHP extensions baked in: `pdo_mysql intl bcmath gd zip pcntl posix exif sockets opcache redis`. That covers Cashier, Horizon (pcntl/posix for signal handling), Inertia, dompdf, webklex/php-imap (which is pure-PHP, doesn't need ext-imap), and phpredis (`REDIS_CLIENT=phpredis`).

Build args: `UID=1000 GID=1000` so the in-container user matches the host user. Files written by `composer install`, `artisan migrate`, etc. land as the host user — no chmod dance.

`opcache.validate_timestamps=1` and `revalidate_freq=0` so file edits show up immediately. Inverse of prod settings.

`entrypoint.sh` waits for MariaDB, copies `.env.docker` → `.env` if `.env` is missing, runs `key:generate` and `migrate --force` (both idempotent), creates the storage symlink, then execs the container's CMD. Same image is used for `app` (CMD `php-fpm`), `horizon` (CMD `php artisan horizon`), and `scheduler` (CMD `php artisan schedule:work`).

## Volumes & persistence

Named volumes (Docker-managed, persist across `docker compose down`):

- `mariadb_data` — `/var/lib/mysql`
- `valkey_data` — `/data` (Valkey AOF/RDB persistence)
- `traefik_certs` — `/etc/traefik/acme` (self-signed cert cache)
- `mailpit_data` — `/data` (mailpit message store)

Bind mounts:

- `./website` → `/var/www/html` in `app`, `horizon`, `scheduler`, `web`, `vite`. Includes `vendor/` and `node_modules/` (visible on host for IDE).
- `./docker/nginx/conf.d` → `/etc/nginx/conf.d` (read-only)
- `./docker/traefik/*.yml` → `/etc/traefik/` (read-only)
- `./docker/mariadb/init` → `/docker-entrypoint-initdb.d` (read-only)

WSL2-native filesystem (`/home/andrew/...` is ext4) makes bind-mounted `vendor/` and `node_modules/` performant. The named-volume overlay trick used on macOS isn't necessary here.

## Environment handling

Two env files coexist:

- **`website/.env`** — used by bare-metal `composer run dev` (untouched by Docker workflow)
- **`.env.docker`** — used by Docker stack via Compose `env_file:`. Gitignored. Created by `cp .env.docker.example .env.docker`.

Docker-specific env values:

```
APP_URL=https://ezscale.docker.localhost
DOMAIN_MARKETING=ezscale.docker.localhost
DOMAIN_ACCOUNT=account.ezscale.docker.localhost
DOMAIN_ADMIN=admin.ezscale.docker.localhost
SESSION_DOMAIN=.ezscale.docker.localhost

DB_HOST=mariadb
DB_PORT=3306
DB_DATABASE=ezscale_billing
DB_USERNAME=ezscale
DB_PASSWORD=ezscale_local

REDIS_HOST=valkey
REDIS_PORT=6379

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025

QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
CACHE_STORE=redis
```

External API keys (Stripe test, PayPal sandbox, VirtFusion, etc.) are placeholders in `.env.docker.example`; developers fill them in their local `.env.docker`.

## Dev workflow (Makefile shortcuts)

```
make up               # docker compose up -d
make down             # docker compose down
make build            # docker compose build --pull
make logs             # docker compose logs -f
make logs SVC=horizon # tails one service
make sh               # shell into app container
make artisan ARGS="..." # runs artisan inside app
make composer ARGS="..." # runs composer inside app
make npm ARGS="..."   # runs npm inside vite
make test             # php artisan test --compact
make pint             # vendor/bin/pint --dirty --format agent
make fresh            # migrate:fresh --seed inside app
make destroy          # docker compose down -v (wipes volumes)
```

## Removals

- **`laravel/sail` removed from `website/composer.json` require-dev**.
- `website/composer.lock` regenerated.
- The Sail binary (`website/vendor/bin/sail`) disappears on next `composer install`.
- No `docker-compose.yml` or `Dockerfile` from Sail to remove — Sail was installed but never published.

## Modifications to existing files

- `website/composer.json` — drop `laravel/sail` line
- `website/composer.lock` — regenerated
- Repo-root `.gitignore` — add `.env.docker`

## Out of scope

- Production Dockerfile (multi-stage, smaller, opcache locked)
- Kubernetes manifests / Helm chart
- mkcert / locally-trusted TLS
- Mocking provisioning APIs
- xdebug (can be added later via build arg)
- Containerized `composer install` / `npm install` orchestration on first boot — user runs these manually once per fresh clone via `make composer ARGS="install"` and `make npm ARGS="install"`

## Risks & mitigations

| Risk | Mitigation |
|------|-----------|
| Self-signed cert warnings annoying users with multiple browsers | Document mkcert as future upgrade path |
| Bind-mounted `vendor/` slow on WSL2 if user clones to `/mnt/c/...` | README explicitly tells users to clone under `/home/$USER/` |
| Horizon dashboard route at `/horizon` requires auth in prod — what about dev? | `App\Providers\HorizonServiceProvider::gate()` controls this; in dev, all admin users have access |
| `entrypoint.sh` auto-migrate could mask broken migrations | Idempotent; failure aborts startup, errors visible in `docker compose logs app` |
| Port 80/443 already used on host (e.g. another nginx) | README documents how to remap Traefik to 8000/8443 if needed |
| MariaDB 12 vs MySQL 8 collation drift on real prod migration | Compose pins `--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci`; same flags applied in prod prevents drift |