feat: docker compose dev environment

Replaces the bare-metal `composer run dev` workflow with a fully containerized 9-service stack orchestrated by docker compose. Single command brings up the full app — three subdomains (marketing / account / admin) reachable via Traefik with TLS, MariaDB + Valkey + Mailpit + Vite HMR + Horizon + scheduler all wired in. Components: - docker-compose.yml: traefik, app (php-fpm), web (nginx), mariadb, valkey, mailpit, vite, horizon, scheduler. - docker/: Dockerfiles, nginx config, entrypoint scripts. - Makefile: convenience targets (up / down / logs / shell / migrate / seed / test / pint / etc). - .env.docker.example: template for Docker-stack environment vars (separate from website/.env so bare-metal devs aren't disrupted). - website/vite.config.ts: server.host / origin / hmr / cors hooks driven by VITE_HOST / VITE_ORIGIN / VITE_HMR_HOST so the same config serves both bare-metal and Docker. - website/bootstrap/app.php: redirectGuestsTo() now uses request()->getScheme() so http: dev hosts don't get force-https redirects. - composer.json: drops laravel/sail (replaced by this stack). - docs/superpowers/specs/2026-04-25-docker-compose-dev-environment-design.md: full design spec. Bare-metal `composer run dev` workflow stays usable for anyone who prefers it — Docker stack reads .env.docker, doesn't fight website/.env. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 22:10:53 -04:00
parent 4b98e52043
commit dfdef3d7f4
21 changed files with 1975 additions and 741 deletions
--- a/.env.docker.example
+++ b/.env.docker.example
@@ -0,0 +1,137 @@
+# ==============================================================================
+# EZSCALE — Docker Compose dev environment
+# Copy to .env.docker and fill in third-party credentials.
+# This file is loaded by app, horizon, and scheduler containers.
+# ==============================================================================
+
+APP_NAME="EZSCALE Billing"
+APP_ENV=local
+# APP_KEY is intentionally NOT set here. The entrypoint runs `php artisan key:generate`
+# which writes the key to website/.env. If APP_KEY were defined here as empty,
+# the empty env var would override the .env file value (env_file beats dotenv).
+APP_DEBUG=true
+APP_URL=http://ezscale.docker.localhost
+
+APP_LOCALE=en
+APP_FALLBACK_LOCALE=en
+APP_FAKER_LOCALE=en_US
+
+APP_MAINTENANCE_DRIVER=file
+
+BCRYPT_ROUNDS=10
+
+LOG_CHANNEL=stack
+LOG_STACK=single
+LOG_DEPRECATIONS_CHANNEL=null
+LOG_LEVEL=debug
+
+# ==============================================================================
+# Database — points at the `mariadb` compose service
+# ==============================================================================
+DB_CONNECTION=mysql
+DB_HOST=mariadb
+DB_PORT=3306
+DB_DATABASE=ezscale_billing
+DB_USERNAME=ezscale
+DB_PASSWORD=ezscale_local
+DB_ROOT_PASSWORD=root
+
+# ==============================================================================
+# Cache / sessions / queues — points at the `valkey` compose service
+# ==============================================================================
+SESSION_DRIVER=redis
+SESSION_LIFETIME=120
+SESSION_ENCRYPT=false
+SESSION_PATH=/
+SESSION_DOMAIN=.ezscale.docker.localhost
+
+BROADCAST_CONNECTION=log
+FILESYSTEM_DISK=local
+QUEUE_CONNECTION=redis
+CACHE_STORE=redis
+
+REDIS_CLIENT=phpredis
+REDIS_HOST=valkey
+REDIS_PASSWORD=null
+REDIS_PORT=6379
+
+# ==============================================================================
+# Subdomain routing
+# ==============================================================================
+DOMAIN_MARKETING=ezscale.docker.localhost
+DOMAIN_ACCOUNT=account.ezscale.docker.localhost
+DOMAIN_ADMIN=admin.ezscale.docker.localhost
+
+# ==============================================================================
+# Mail — points at the `mailpit` compose service
+# ==============================================================================
+MAIL_MAILER=smtp
+MAIL_SCHEME=null
+MAIL_HOST=mailpit
+MAIL_PORT=1025
+MAIL_USERNAME=null
+MAIL_PASSWORD=null
+MAIL_FROM_ADDRESS="noreply@ezscale.cloud"
+MAIL_FROM_NAME="${APP_NAME}"
+
+# ==============================================================================
+# Stripe — fill with your test-mode keys
+# ==============================================================================
+STRIPE_KEY=
+STRIPE_SECRET=
+STRIPE_WEBHOOK_SECRET=
+
+# ==============================================================================
+# PayPal — sandbox credentials
+# ==============================================================================
+PAYPAL_MODE=sandbox
+PAYPAL_SANDBOX_CLIENT_ID=
+PAYPAL_SANDBOX_CLIENT_SECRET=
+
+# ==============================================================================
+# Discord admin alerts (optional)
+# ==============================================================================
+DISCORD_WEBHOOK_URL=
+
+# ==============================================================================
+# Provisioning APIs — external services, fill if you need to test provisioning
+# ==============================================================================
+VIRTFUSION_API_URL=
+VIRTFUSION_API_KEY=
+PTERODACTYL_API_URL=
+PTERODACTYL_API_KEY=
+SYNERGYCP_API_URL=
+SYNERGYCP_API_KEY=
+ENHANCE_API_URL=
+ENHANCE_API_KEY=
+
+# ==============================================================================
+# Screenshot Authentication (Dev/Local Only)
+# ==============================================================================
+SCREENSHOT_AUTH_ENABLED=false
+SCREENSHOT_TOKEN=
+
+# ==============================================================================
+# Support Ticket Email Integration (IMAP) — optional
+# ==============================================================================
+SUPPORT_EMAIL=support@ezscale.cloud
+TICKET_EMAIL_POLLING=false
+IMAP_HOST=outlook.office365.com
+IMAP_PORT=993
+IMAP_ENCRYPTION=ssl
+IMAP_USERNAME=
+IMAP_PASSWORD=
+IMAP_VALIDATE_CERT=true
+IMAP_PROTOCOL=imap
+IMAP_FOLDER=INBOX
+
+# ==============================================================================
+# ServerHunter Integration (optional)
+# ==============================================================================
+SERVERHUNTER_API_KEY=
+
+# ==============================================================================
+# Vite — Laravel Vite plugin reads this
+# ==============================================================================
+VITE_APP_NAME="${APP_NAME}"
+VITE_DEV_SERVER_URL=http://vite.ezscale.docker.localhost
--- a/135
+++ b/135
@@ -0,0 +1,135 @@
+# ==============================================================================
+# EZSCALE — Makefile shortcuts for the docker compose dev stack
+# ==============================================================================
+
+SHELL := /bin/bash
+DC    := docker compose
+EXEC  := $(DC) exec -T app
+RUN   := $(DC) run --rm app
+
+.DEFAULT_GOAL := help
+
+# -------------------------------------------------------------------- lifecycle
+.PHONY: help
+help: ## Show this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+.PHONY: init
+init: ## First-time setup: copy .env.docker, build, install deps, migrate
+	@if [ ! -f .env.docker ]; then cp .env.docker.example .env.docker && echo "[init] created .env.docker"; fi
+	$(DC) build --pull
+	$(DC) up -d mariadb valkey
+	@echo "[init] waiting 10s for mariadb to settle..."
+	@sleep 10
+	$(RUN) composer install
+	$(DC) run --rm vite npm install
+	$(DC) up -d
+	@echo ""
+	@echo "Stack is up. Open https://ezscale.docker.localhost"
+
+.PHONY: up
+up: ## Start all services in the background
+	$(DC) up -d
+
+.PHONY: down
+down: ## Stop all services (volumes preserved)
+	$(DC) down
+
+.PHONY: restart
+restart: ## Restart all services
+	$(DC) restart
+
+.PHONY: build
+build: ## Rebuild all images
+	$(DC) build --pull
+
+.PHONY: rebuild
+rebuild: ## Rebuild from scratch (no cache)
+	$(DC) build --pull --no-cache
+
+.PHONY: destroy
+destroy: ## Stop everything AND wipe data volumes (DB, mail, etc.)
+	$(DC) down -v
+
+.PHONY: ps
+ps: ## Show service status
+	$(DC) ps
+
+# ------------------------------------------------------------------------ logs
+.PHONY: logs
+logs: ## Tail logs (use SVC=name to scope to one service)
+ifdef SVC
+	$(DC) logs -f $(SVC)
+else
+	$(DC) logs -f
+endif
+
+# -------------------------------------------------------------------- shells
+.PHONY: sh
+sh: ## Bash inside the app container
+	$(DC) exec app bash
+
+.PHONY: web-sh
+web-sh: ## Shell inside the nginx container
+	$(DC) exec web sh
+
+.PHONY: db-sh
+db-sh: ## MariaDB CLI
+	$(DC) exec mariadb mariadb -uezscale -pezscale_local ezscale_billing
+
+.PHONY: redis-sh
+redis-sh: ## Valkey CLI
+	$(DC) exec valkey valkey-cli
+
+# ----------------------------------------------------------- artisan / composer
+.PHONY: artisan
+artisan: ## Run an artisan command (use ARGS="migrate")
+	$(EXEC) php artisan $(ARGS)
+
+.PHONY: composer
+composer: ## Run composer (use ARGS="require ...")
+	$(EXEC) composer $(ARGS)
+
+.PHONY: tinker
+tinker: ## Open a tinker shell
+	$(DC) exec app php artisan tinker
+
+# ---------------------------------------------------------------------- frontend
+.PHONY: npm
+npm: ## Run npm in the vite container (use ARGS="install ...")
+	$(DC) exec vite npm $(ARGS)
+
+.PHONY: vite-build
+vite-build: ## One-off production build
+	$(DC) run --rm vite npm run build
+
+# ----------------------------------------------------------------------- testing
+.PHONY: test
+test: ## Run the Pest suite
+	$(EXEC) php artisan test --compact $(ARGS)
+
+.PHONY: pint
+pint: ## Format dirty PHP files
+	$(EXEC) vendor/bin/pint --dirty --format agent
+
+# -------------------------------------------------------------- DB convenience
+.PHONY: migrate
+migrate: ## Run pending migrations
+	$(EXEC) php artisan migrate
+
+.PHONY: fresh
+fresh: ## Drop all tables, re-migrate, seed
+	$(EXEC) php artisan migrate:fresh --seed
+
+.PHONY: seed
+seed: ## Run seeders
+	$(EXEC) php artisan db:seed
+
+# --------------------------------------------------------------- diagnostics
+.PHONY: doctor
+doctor: ## Print key compose info for debugging
+	$(DC) config --services
+	@echo ""
+	$(DC) ps
+	@echo ""
+	$(DC) exec app php -v 2>/dev/null || echo "app not running"
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -0,0 +1,220 @@
+# ==============================================================================
+# EZSCALE — Docker Compose dev environment
+# Spec: docs/superpowers/specs/2026-04-25-docker-compose-dev-environment-design.md
+#
+# Quick start:
+#   cp .env.docker.example .env.docker
+#   make up
+#
+# Hostnames (auto-resolve to 127.0.0.1):
+#   https://ezscale.docker.localhost           — marketing
+#   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)
+# ==============================================================================
+
+name: ezscale
+
+x-app-base: &app-base
+  build:
+    context: ./docker/app
+    args:
+      UID: ${UID:-1000}
+      GID: ${GID:-1000}
+  image: ezscale/app:dev
+  env_file:
+    - .env.docker
+  volumes:
+    - ./website:/var/www/html
+  networks:
+    - ezscale
+  depends_on:
+    mariadb:
+      condition: service_healthy
+    valkey:
+      condition: service_healthy
+    mailpit:
+      condition: service_started
+
+services:
+  # ---------------------------------------------------------------------------
+  # Edge: Traefik (TLS + routing)
+  # ---------------------------------------------------------------------------
+  traefik:
+    image: traefik:v3.6
+    restart: unless-stopped
+    command: []
+    ports:
+      - "80:80"
+      - "443:443"
+      - "8080:8080"
+    volumes:
+      - ./docker/traefik/traefik.yml:/etc/traefik/traefik.yml:ro
+      - ./docker/traefik/dynamic.yml:/etc/traefik/dynamic.yml:ro
+      - traefik_certs:/etc/traefik/acme
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - ezscale
+    labels:
+      - "traefik.enable=true"
+
+  # ---------------------------------------------------------------------------
+  # PHP-FPM application container (php artisan serve replacement)
+  # ---------------------------------------------------------------------------
+  app:
+    <<: *app-base
+    container_name: ezscale-app
+    restart: unless-stopped
+    command: ["php-fpm"]
+
+  # ---------------------------------------------------------------------------
+  # nginx — serves public/, proxies PHP to app:9000
+  # ---------------------------------------------------------------------------
+  web:
+    build:
+      context: ./docker/nginx
+    image: ezscale/nginx:dev
+    restart: unless-stopped
+    volumes:
+      - ./website:/var/www/html:ro
+      - ./docker/nginx/conf.d:/etc/nginx/conf.d:ro
+    networks:
+      - ezscale
+    depends_on:
+      - app
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=ezscale"
+      - "traefik.http.services.ezscale-web.loadbalancer.server.port=80"
+      - "traefik.http.routers.ezscale-web.rule=Host(`ezscale.docker.localhost`) || Host(`account.ezscale.docker.localhost`) || Host(`admin.ezscale.docker.localhost`)"
+      - "traefik.http.routers.ezscale-web.entrypoints=web"
+
+  # ---------------------------------------------------------------------------
+  # Vite dev server (HMR)
+  # ---------------------------------------------------------------------------
+  vite:
+    build:
+      context: ./docker/vite
+      args:
+        UID: ${UID:-1000}
+        GID: ${GID:-1000}
+    image: ezscale/vite:dev
+    restart: unless-stopped
+    working_dir: /var/www/html
+    environment:
+      VITE_HOST: "0.0.0.0"
+      VITE_ORIGIN: "http://vite.ezscale.docker.localhost"
+      VITE_HMR_HOST: "vite.ezscale.docker.localhost"
+    volumes:
+      - ./website:/var/www/html
+    networks:
+      - ezscale
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=ezscale"
+      - "traefik.http.services.ezscale-vite.loadbalancer.server.port=5173"
+      - "traefik.http.routers.ezscale-vite.rule=Host(`vite.ezscale.docker.localhost`)"
+      - "traefik.http.routers.ezscale-vite.entrypoints=web"
+
+  # ---------------------------------------------------------------------------
+  # Horizon — queue worker supervisor (Redis-only)
+  # ---------------------------------------------------------------------------
+  horizon:
+    <<: *app-base
+    container_name: ezscale-horizon
+    restart: unless-stopped
+    command: ["php", "artisan", "horizon"]
+    stop_signal: SIGTERM
+    stop_grace_period: 60s
+
+  # ---------------------------------------------------------------------------
+  # Scheduler — runs `schedule:work` in a loop (cron replacement)
+  # ---------------------------------------------------------------------------
+  scheduler:
+    <<: *app-base
+    container_name: ezscale-scheduler
+    restart: unless-stopped
+    command: ["php", "artisan", "schedule:work"]
+
+  # ---------------------------------------------------------------------------
+  # MariaDB — primary database
+  # ---------------------------------------------------------------------------
+  mariadb:
+    image: mariadb:12
+    restart: unless-stopped
+    command:
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+      - --skip-character-set-client-handshake
+    environment:
+      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-root}
+      MARIADB_DATABASE: ${DB_DATABASE:-ezscale_billing}
+      MARIADB_USER: ${DB_USERNAME:-ezscale}
+      MARIADB_PASSWORD: ${DB_PASSWORD:-ezscale_local}
+    volumes:
+      - mariadb_data:/var/lib/mysql
+      - ./docker/mariadb/init:/docker-entrypoint-initdb.d:ro
+    networks:
+      - ezscale
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 30s
+
+  # ---------------------------------------------------------------------------
+  # Valkey — sessions, cache, queues
+  # ---------------------------------------------------------------------------
+  valkey:
+    image: valkey/valkey:9-alpine
+    restart: unless-stopped
+    command: ["valkey-server", "--appendonly", "yes"]
+    volumes:
+      - valkey_data:/data
+    networks:
+      - ezscale
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ---------------------------------------------------------------------------
+  # Mailpit — SMTP catcher + web UI
+  # ---------------------------------------------------------------------------
+  mailpit:
+    image: axllent/mailpit:v1.29
+    restart: unless-stopped
+    environment:
+      MP_SMTP_AUTH_ACCEPT_ANY: "1"
+      MP_SMTP_AUTH_ALLOW_INSECURE: "1"
+      MP_MAX_MESSAGES: "5000"
+    volumes:
+      - mailpit_data:/data
+    networks:
+      - ezscale
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=ezscale"
+      - "traefik.http.services.ezscale-mail.loadbalancer.server.port=8025"
+      - "traefik.http.routers.ezscale-mail.rule=Host(`mail.ezscale.docker.localhost`)"
+      - "traefik.http.routers.ezscale-mail.entrypoints=web"
+
+# ==============================================================================
+# Volumes & networks
+# ==============================================================================
+
+volumes:
+  mariadb_data:
+  valkey_data:
+  mailpit_data:
+  traefik_certs:
+
+networks:
+  ezscale:
+    name: ezscale
+    driver: bridge
--- a/docker/README.md
+++ b/docker/README.md
@@ -0,0 +1,142 @@
+# EZSCALE — Docker Compose Dev Environment
+
+Multi-service development stack for the EZSCALE Laravel app. Replaces the bare-metal `composer run dev` workflow with a fully-containerized environment that mirrors the production topology (nginx + PHP-FPM + MariaDB + Valkey + Horizon).
+
+## Prerequisites
+
+- **Docker Engine 24+** with **Compose V2** (`docker compose`, not `docker-compose`)
+- **WSL2 with files cloned under `/home/$USER/`** (NOT `/mnt/c/...` — bind-mount performance is unusable on the Windows-mounted filesystem)
+- A modern browser (Chrome, Firefox, Safari) — `*.docker.localhost` resolution requires no `/etc/hosts` edits
+
+## First-time setup
+
+```bash
+make init
+```
+
+That single command:
+1. Copies `.env.docker.example` → `.env.docker`
+2. Builds all custom images (PHP-FPM, nginx, vite)
+3. Pulls third-party images (Traefik, MariaDB, Valkey, Mailpit)
+4. Boots MariaDB and Valkey, waits for them to be healthy
+5. Runs `composer install` and `npm install`
+6. Brings up the rest of the stack
+
+When `make init` finishes, you should be able to open:
+
+- **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 (catches all outgoing email)
+- **https://vite.ezscale.docker.localhost** — Vite dev server (for HMR)
+- **http://localhost:8080** — Traefik dashboard (insecure, dev-only)
+
+The first time you visit any of these, your browser will warn about a self-signed cert. Accept once — Traefik issues a wildcard cert covering all subdomains.
+
+## Daily commands
+
+```bash
+make up                       # bring stack up
+make down                     # stop (volumes preserved)
+make logs                     # tail all logs
+make logs SVC=horizon         # tail one service
+make sh                       # bash inside app container
+make artisan ARGS="migrate"   # any artisan command
+make composer ARGS="require foo/bar"
+make npm ARGS="install foo"
+make test                     # php artisan test --compact
+make pint                     # format dirty PHP
+make fresh                    # migrate:fresh --seed
+make destroy                  # nuclear: stop + wipe volumes
+```
+
+`make help` prints the full list.
+
+## Architecture
+
+| Service | Image | Role |
+|---------|-------|------|
+| `traefik` | `traefik:v3.6` | Edge proxy + TLS termination + routing |
+| `app` | custom (PHP 8.3-FPM Debian) | Application container |
+| `web` | `nginx:1.30-alpine` | Serves `public/`, proxies PHP |
+| `vite` | custom (Node 24 Alpine) | HMR dev server |
+| `horizon` | same as `app` | Queue worker supervisor |
+| `scheduler` | same as `app` | `schedule:work` runner |
+| `mariadb` | `mariadb:12` | Primary database |
+| `valkey` | `valkey/valkey:9-alpine` | Sessions/cache/queues |
+| `mailpit` | `axllent/mailpit:v1.29` | SMTP catcher |
+
+Traefik routes the three Laravel subdomains (marketing/account/admin) to the same nginx container. Laravel's `Route::domain()` in `bootstrap/app.php` handles per-subdomain dispatch internally.
+
+## Environment
+
+The stack reads `.env.docker` at the repo root — separate from `website/.env`. This keeps the Docker workflow from fighting any bare-metal `composer run dev` setup you might still want to use.
+
+Critical Docker-specific values:
+
+```
+DB_HOST=mariadb
+REDIS_HOST=valkey
+MAIL_HOST=mailpit
+APP_URL=https://ezscale.docker.localhost
+```
+
+Third-party API keys (Stripe, PayPal, VirtFusion, etc.) need to be added to your `.env.docker` if you want to test those integrations.
+
+## Volumes
+
+Persisted across `make down` (lost only on `make destroy`):
+
+- `mariadb_data` — MySQL data
+- `valkey_data` — Valkey AOF persistence
+- `mailpit_data` — captured email
+- `traefik_certs` — self-signed cert cache
+
+The Laravel source (`./website`) is bind-mounted live — your edits show up immediately. `vendor/` and `node_modules/` are visible on the host for IDE autocomplete.
+
+## TLS
+
+Traefik auto-generates a single self-signed wildcard cert for `*.ezscale.docker.localhost` on first boot. The cert lives in the `traefik_certs` volume.
+
+If you want a green-padlock experience instead of accepting the warning once per browser:
+
+```bash
+brew install mkcert  # or apt/winget equivalent
+mkcert -install
+mkcert -cert-file docker/traefik/certs/cert.pem \
+       -key-file  docker/traefik/certs/key.pem \
+       "ezscale.docker.localhost" "*.ezscale.docker.localhost"
+```
+
+Then update `docker/traefik/dynamic.yml` to point `certificates:` at those files. Currently configured for self-signed; mkcert is left as a future enhancement.
+
+## Common gotchas
+
+**Port 80 or 443 already in use.**
+Edit `docker-compose.yml`'s `traefik` service and remap to e.g. `8000:80`, `8443:443`. Then access the stack at `https://ezscale.docker.localhost:8443`.
+
+**`make init` hangs on "waiting for mariadb".**
+First MariaDB boot creates the system tablespace and can take 20-30s. The healthcheck has a 30s `start_period` to accommodate this. If it really stalls, `make logs SVC=mariadb` to see why.
+
+**Permission errors on `storage/logs/laravel.log`.**
+The PHP container's UID matches your host UID (1000) by default. If your host UID differs, rebuild with `UID=$(id -u) GID=$(id -g) make build`.
+
+**Horizon dashboard 403s.**
+Horizon's gate is in `App\Providers\HorizonServiceProvider::gate()`. In dev all admin users have access; you need to log in with an admin role first.
+
+**Vite assets don't load.**
+Check `make logs SVC=vite`. The Laravel Vite plugin auto-injects the dev URL — if it can't reach `https://vite.ezscale.docker.localhost`, assets fall back to the manifest. Make sure that hostname is reachable in your browser.
+
+**Composer/npm install slow.**
+First-time `composer install` takes 1-2 min. After that the `vendor/` dir is cached on disk. Same for `node_modules`.
+
+## Co-existing with bare-metal dev
+
+This stack does NOT delete or modify `website/.env`. If you previously used `cd website && composer run dev`, that still works — it reads `website/.env` and connects to whatever local PHP/MySQL/Redis you had.
+
+Pick one or the other for any given session. Don't run both simultaneously (they'd fight over ports and sessions).
+
+## Spec
+
+Full design rationale in [`docs/superpowers/specs/2026-04-25-docker-compose-dev-environment-design.md`](../docs/superpowers/specs/2026-04-25-docker-compose-dev-environment-design.md).
--- a/docker/app/Dockerfile
+++ b/docker/app/Dockerfile
@@ -0,0 +1,64 @@
+FROM php:8.3-fpm-bookworm
+
+ARG UID=1000
+ARG GID=1000
+
+ENV COMPOSER_ALLOW_SUPERUSER=1 \
+    COMPOSER_NO_INTERACTION=1 \
+    COMPOSER_MEMORY_LIMIT=-1
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        git \
+        unzip \
+        curl \
+        ca-certificates \
+        libzip-dev \
+        libpng-dev \
+        libjpeg-dev \
+        libfreetype6-dev \
+        libwebp-dev \
+        libicu-dev \
+        libonig-dev \
+        libxml2-dev \
+        libcurl4-openssl-dev \
+        libssl-dev \
+        pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
+    && docker-php-ext-install -j"$(nproc)" \
+        pdo_mysql \
+        intl \
+        bcmath \
+        gd \
+        zip \
+        pcntl \
+        posix \
+        exif \
+        sockets \
+        opcache
+
+RUN pecl install redis \
+    && docker-php-ext-enable redis
+
+COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer
+
+RUN groupmod -g ${GID} www-data \
+    && usermod -u ${UID} -g ${GID} www-data \
+    && mkdir -p /var/www/.composer \
+    && chown -R www-data:www-data /var/www
+
+COPY php.ini       /usr/local/etc/php/conf.d/zz-app.ini
+COPY opcache.ini   /usr/local/etc/php/conf.d/zz-opcache.ini
+COPY php-fpm.conf  /usr/local/etc/php-fpm.d/zz-app.conf
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+WORKDIR /var/www/html
+USER www-data
+
+EXPOSE 9000
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+CMD ["php-fpm"]
--- a/docker/app/entrypoint.sh
+++ b/docker/app/entrypoint.sh
@@ -0,0 +1,55 @@
+#!/bin/sh
+set -e
+
+# ==============================================================================
+# EZSCALE app container entrypoint
+# Used by `app`, `horizon`, and `scheduler` services. Idempotent.
+# ==============================================================================
+
+cd /var/www/html
+
+# Wait for MariaDB. depends_on: condition: service_healthy already gates this,
+# but the belt-and-braces loop is cheap and survives healthcheck regressions.
+if [ -n "${DB_HOST:-}" ]; then
+    echo "[entrypoint] waiting for ${DB_HOST}:${DB_PORT:-3306}..."
+    until php -r "new PDO('mysql:host=${DB_HOST};port=${DB_PORT:-3306}', '${DB_USERNAME}', '${DB_PASSWORD}');" 2>/dev/null; do
+        sleep 1
+    done
+    echo "[entrypoint] mariadb is up."
+fi
+
+# Bootstrap .env on first boot. We bind-mount the website/ source, so .env may
+# already exist from a previous bare-metal `composer run dev` workflow.
+if [ ! -f .env ]; then
+    if [ -f /var/www/html/.env.docker ]; then
+        echo "[entrypoint] copying .env.docker -> .env"
+        cp /var/www/html/.env.docker .env
+    elif [ -f .env.example ]; then
+        echo "[entrypoint] copying .env.example -> .env (fallback)"
+        cp .env.example .env
+    fi
+fi
+
+# Vendor dir bootstrapping — first-clone convenience. Skipped if already present.
+if [ ! -d vendor ] || [ ! -f vendor/autoload.php ]; then
+    echo "[entrypoint] vendor/ missing; running composer install"
+    composer install --no-interaction --prefer-dist --no-progress
+fi
+
+# Generate APP_KEY if blank. `key:generate` writes to .env in place.
+if ! grep -qE '^APP_KEY=base64:' .env; then
+    echo "[entrypoint] generating APP_KEY"
+    php artisan key:generate --force --no-interaction
+fi
+
+# Run migrations only when this container is the `app` (php-fpm) role.
+# Horizon and scheduler share this image but skip migrations to avoid races.
+case "$1" in
+    php-fpm|php-fpm*)
+        echo "[entrypoint] running migrations"
+        php artisan migrate --force --no-interaction || true
+        php artisan storage:link || true
+        ;;
+esac
+
+exec "$@"
--- a/docker/app/opcache.ini
+++ b/docker/app/opcache.ini
@@ -0,0 +1,18 @@
+; ==============================================================================
+; OPcache — DEV configuration
+; In prod, flip validate_timestamps to 0 and lock the cache.
+; ==============================================================================
+
+opcache.enable = 1
+opcache.enable_cli = 1
+opcache.memory_consumption = 256
+opcache.interned_strings_buffer = 32
+opcache.max_accelerated_files = 20000
+
+; Recheck files on every request — edits show up immediately
+opcache.validate_timestamps = 1
+opcache.revalidate_freq = 0
+
+opcache.fast_shutdown = 1
+opcache.jit = tracing
+opcache.jit_buffer_size = 100M
--- a/docker/app/php-fpm.conf
+++ b/docker/app/php-fpm.conf
@@ -0,0 +1,23 @@
+; ==============================================================================
+; PHP-FPM pool — DEV configuration
+; ==============================================================================
+
+[www]
+user = www-data
+group = www-data
+
+listen = 9000
+listen.backlog = 511
+
+pm = dynamic
+pm.max_children = 25
+pm.start_servers = 4
+pm.min_spare_servers = 2
+pm.max_spare_servers = 8
+pm.max_requests = 1000
+
+; Surface FPM logs to stdout/stderr so `docker compose logs app` shows them
+access.log = /proc/self/fd/2
+catch_workers_output = yes
+decorate_workers_output = no
+clear_env = no
--- a/docker/app/php.ini
+++ b/docker/app/php.ini
@@ -0,0 +1,24 @@
+; ==============================================================================
+; EZSCALE dev overrides — applied AFTER php.ini-development
+; ==============================================================================
+
+memory_limit = 512M
+max_execution_time = 120
+post_max_size = 50M
+upload_max_filesize = 50M
+max_input_vars = 5000
+
+display_errors = On
+display_startup_errors = On
+error_reporting = E_ALL
+log_errors = On
+
+date.timezone = UTC
+
+; Session handling delegated to Laravel; keep PHP-side defaults sane
+session.cookie_httponly = 1
+session.cookie_samesite = "Lax"
+
+; Realpath cache helps Composer/Laravel reload cycles
+realpath_cache_size = 4096K
+realpath_cache_ttl = 600
--- a/docker/mariadb/init/01-create-test-db.sql
+++ b/docker/mariadb/init/01-create-test-db.sql
@@ -0,0 +1,9 @@
+-- Runs once on first MariaDB volume bootstrap.
+-- Creates the testing database used by `php artisan test`.
+
+CREATE DATABASE IF NOT EXISTS ezscale_billing_testing
+    CHARACTER SET utf8mb4
+    COLLATE utf8mb4_unicode_ci;
+
+GRANT ALL PRIVILEGES ON ezscale_billing_testing.* TO 'ezscale'@'%';
+FLUSH PRIVILEGES;
--- a/docker/nginx/Dockerfile
+++ b/docker/nginx/Dockerfile
@@ -0,0 +1,8 @@
+FROM nginx:1.30-alpine
+
+RUN rm -f /etc/nginx/conf.d/default.conf
+
+COPY nginx.conf /etc/nginx/nginx.conf
+COPY conf.d/    /etc/nginx/conf.d/
+
+EXPOSE 80
--- a/docker/nginx/conf.d/ezscale.conf
+++ b/docker/nginx/conf.d/ezscale.conf
@@ -0,0 +1,54 @@
+# ==============================================================================
+# EZSCALE catch-all server block
+# Traefik routes all 3 subdomains (marketing/account/admin) here. Laravel's
+# Route::domain() in bootstrap/app.php handles per-subdomain dispatch.
+# ==============================================================================
+
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name _;
+
+    root /var/www/html/public;
+    index index.php index.html;
+
+    add_header X-Frame-Options "SAMEORIGIN";
+    add_header X-Content-Type-Options "nosniff";
+    add_header Referrer-Policy "strict-origin-when-cross-origin";
+
+    charset utf-8;
+
+    location = /favicon.ico { access_log off; log_not_found off; }
+    location = /robots.txt  { access_log off; log_not_found off; }
+
+    location / {
+        try_files $uri $uri/ /index.php?$query_string;
+    }
+
+    location ~ \.php$ {
+        try_files $uri =404;
+        fastcgi_split_path_info ^(.+\.php)(/.+)$;
+        fastcgi_pass php-upstream;
+        fastcgi_index index.php;
+
+        include fastcgi_params;
+        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
+        fastcgi_param DOCUMENT_ROOT   $realpath_root;
+        fastcgi_param HTTP_PROXY      "";
+
+        # Match Traefik forwarded headers
+        fastcgi_param HTTPS           $http_x_forwarded_proto;
+        fastcgi_param REMOTE_ADDR     $http_x_forwarded_for;
+
+        fastcgi_buffers 16 16k;
+        fastcgi_buffer_size 32k;
+        fastcgi_read_timeout 300;
+    }
+
+    # Deny dotfiles except .well-known (LE/CSP)
+    location ~ /\.(?!well-known).* {
+        deny all;
+        access_log off;
+        log_not_found off;
+    }
+}
--- a/docker/nginx/nginx.conf
+++ b/docker/nginx/nginx.conf
@@ -0,0 +1,40 @@
+user nginx;
+worker_processes auto;
+error_log /var/log/nginx/error.log notice;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections 1024;
+    multi_accept on;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+
+    log_format main '$remote_addr - $remote_user [$time_local] '
+                    '"$request" $status $body_bytes_sent '
+                    '"$http_referer" "$http_user_agent" "$host"';
+
+    access_log /var/log/nginx/access.log main;
+
+    sendfile on;
+    tcp_nopush on;
+    tcp_nodelay on;
+    keepalive_timeout 65;
+    types_hash_max_size 2048;
+    server_tokens off;
+
+    # Traefik handles compression at the edge — leave it off here.
+    gzip off;
+
+    # 50M for file uploads (matches php upload_max_filesize)
+    client_max_body_size 50M;
+
+    # Upstream PHP-FPM
+    upstream php-upstream {
+        server app:9000;
+    }
+
+    include /etc/nginx/conf.d/*.conf;
+}
--- a/docker/traefik/dynamic.yml
+++ b/docker/traefik/dynamic.yml
@@ -0,0 +1,17 @@
+# ==============================================================================
+# Traefik dynamic config — TLS options + self-signed wildcard cert
+# ==============================================================================
+
+tls:
+  options:
+    default:
+      minVersion: VersionTLS12
+      sniStrict: false
+  stores:
+    default:
+      defaultGeneratedCert:
+        resolver: ""
+        domain:
+          main: "ezscale.docker.localhost"
+          sans:
+            - "*.ezscale.docker.localhost"
--- a/docker/traefik/traefik.yml
+++ b/docker/traefik/traefik.yml
@@ -0,0 +1,33 @@
+# ==============================================================================
+# Traefik static config — DEV
+# ==============================================================================
+
+global:
+  checkNewVersion: false
+  sendAnonymousUsage: false
+
+api:
+  dashboard: true
+  insecure: true   # Dev-only: dashboard at :8080 with no auth
+
+log:
+  level: INFO
+
+accessLog: {}
+
+entryPoints:
+  web:
+    address: ":80"
+  websecure:
+    address: ":443"
+  traefik:
+    address: ":8080"
+
+providers:
+  docker:
+    exposedByDefault: false
+    network: ezscale
+    watch: true
+  file:
+    filename: /etc/traefik/dynamic.yml
+    watch: true
--- a/docker/vite/Dockerfile
+++ b/docker/vite/Dockerfile
@@ -0,0 +1,16 @@
+FROM node:24-alpine
+
+ARG UID=1000
+ARG GID=1000
+
+RUN apk add --no-cache git \
+    && deluser --remove-home node 2>/dev/null || true \
+    && addgroup -g ${GID} node \
+    && adduser -D -u ${UID} -G node node
+
+WORKDIR /var/www/html
+USER node
+
+EXPOSE 5173
+
+CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0", "--port", "5173"]
--- a/docs/superpowers/specs/2026-04-25-docker-compose-dev-environment-design.md
+++ b/docs/superpowers/specs/2026-04-25-docker-compose-dev-environment-design.md
@@ -0,0 +1,226 @@
+# 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 |
--- a/website/bootstrap/app.php
+++ b/website/bootstrap/app.php
@@ -51,7 +51,7 @@ return Application::configure(basePath: dirname(__DIR__))
            \App\Http\Middleware\ScreenshotAuthMiddleware::class,
        );

-        $middleware->redirectGuestsTo(fn () => 'https://'.config('app.domains.account').'/login');
+        $middleware->redirectGuestsTo(fn () => request()->getScheme().'://'.config('app.domains.account').'/login');
        $middleware->redirectUsersTo('/dashboard');

        $middleware->alias([
--- a/website/composer.json
+++ b/website/composer.json
@@ -29,7 +29,6 @@
        "laravel/boost": "^2.1",
        "laravel/pail": "^1.2.2",
        "laravel/pint": "^1.24",
-        "laravel/sail": "^1.41",
        "mockery/mockery": "^1.6",
        "nunomaduro/collision": "^8.6",
        "pestphp/pest": "^4.3",
--- a/website/composer.lock
+++ b/website/composer.lock
--- a/website/vite.config.ts
+++ b/website/vite.config.ts
@@ -33,6 +33,23 @@ export default defineConfig({
    },
  },
  server: {
+    host: process.env.VITE_HOST ?? 'localhost',
+    // When running inside the Docker stack, Vite is reached via Traefik at
+    // a public hostname. VITE_ORIGIN tells the laravel-vite-plugin
+    // what URL to write into public/hot so the browser can fetch modules.
+    origin: process.env.VITE_ORIGIN || undefined,
+    // Vite 7 defaults to a strict CORS regex that doesn't allow multi-label
+    // .localhost hosts. When in Docker mode, allow any *.docker.localhost.
+    cors: process.env.VITE_HMR_HOST
+      ? { origin: /^https?:\/\/.+\.docker\.localhost(?::\d+)?$/ }
+      : true,
+    hmr: process.env.VITE_HMR_HOST
+      ? {
+          host: process.env.VITE_HMR_HOST,
+          protocol: process.env.VITE_ORIGIN?.startsWith('https') ? 'wss' : 'ws',
+          clientPort: process.env.VITE_ORIGIN?.startsWith('https') ? 443 : 80,
+        }
+      : undefined,
    watch: {
      ignored: ['**/storage/framework/views/**'],
    },