feat(docker): single-command Docker stack for local development

[andrefrd]

Summary

• Adds a self-contained docker compose up --build workflow that brings the full Laravel + Vite + Reverb + Horizon + scheduler stack online inside one container, plus Postgres 16, Redis 7, and Mailpit. No host PHP / Node prerequisites.
• Replaces the existing compose.yaml (a stale Sail file pointing at ./vendor/laravel/sail/runtimes/8.5/ — Sail isn't installed and the path doesn't exist) with a self-describing build that uses a new docker/Dockerfile.
• The same docker/Dockerfile exposes a production target so self-hosters get a hardened image (composer --no-dev, npm production build, SSR build, OpCache locked) from the same source contributors use in dev.
• Documents the workflow under "Get Started" in the README — common commands, override mechanism, troubleshooting, and the production build hint.

What changed

File	Purpose
docker/Dockerfile	Multi-stage: shared system-base (PHP 8.4-FPM Alpine + Postgres / Redis / intl / sockets / redis extensions) → composer-deps / composer-deps-prod → wayfinder-gen → asset-build → dev / production targets. UID/GID build args.
docker/{nginx,php.dev,php.prod,supervisord.dev,supervisord.prod}.{conf,ini}	Sidecar configs. Dev opcache validates timestamps for hot-reload; prod is hardened. Supervisord runs fpm + nginx + reverb + horizon + scheduler (+ vite in dev).
docker/entrypoint.sh	Idempotent: seeds .env from .env.docker.example, generates APP_KEY, waits for Postgres, runs migrations, links storage, generates Passport keys, regenerates Wayfinder helpers, and re-installs deps if anonymous volumes were wiped.
docker/.env.docker.example	Docker-tuned env template (service-name hosts, sane defaults). Does not touch .env.example, so the existing Herd workflow is untouched.
docker/postgres-init.sh	Creates the trypost_test database phpunit.xml expects, on first Postgres boot.
compose.yaml	Self-contained dev stack. Bind-mounts source for hot reload; named volumes for vendor/ and node_modules/ so image-baked deps survive. Healthchecks gate app startup until Postgres / Redis are ready. Sets DB_HOST=pgsql, DB_USERNAME=postgres, REDIS_HOST=redis as process env so .env.testing's pre-existing CI defaults don't break in-container tests.
compose.override.yaml.example	Per-developer customizations (UID/GID alignment, port conflicts, Xdebug, Selenium for Dusk).
.dockerignore	Keeps the build context small and prevents secrets / dev artifacts from leaking into the image.
.gitignore	Adds .env.testing.local as a safety net for any per-developer testing override.
README.md	New "Run with Docker" section covering single-command boot, common commands, override workflow, troubleshooting (port conflicts, UID on Linux, first-boot expectations), and the production target hint.

Why these specific choices

• Single container with supervisord instead of separate compose services for fpm / nginx / reverb / horizon / scheduler / vite, because the @laravel/vite-plugin-wayfinder plugin shells out to php artisan at runtime — splitting Vite into a Node-only container would break it. Co-locating mirrors the production supervisord layout and gives one mental model.
• Postgres 16-alpine matches .env.ci. docker/postgres-init.sh covers the trypost_test database that phpunit.xml pins.
• .env.docker.example separate from .env.example so Herd / composer dev users keep their flow unchanged. The entrypoint only seeds the Docker variant when TRYPOST_DOCKER_BOOTSTRAP=1 (set by compose).
• UID/GID build args (default 1000) keep bind-mount writes owned by the host user. Linux contributors on non-1000 systems pass UID=$(id -u) GID=$(id -g).

Test plan

• docker compose up --build from a fresh clone reaches healthy in ~3-4 min on first boot, seconds on subsequent boots.
• curl -fsS http://localhost:8000/up → 200.
• Homepage at http://localhost:8000 renders (302 → /login).
• Vite dev server reachable at http://localhost:5173/@vite/client → 200.
• Mailpit UI at http://localhost:8025 → 200.
• docker compose exec app php artisan test --compact tests/Feature/Auth/PasswordResetTest.php → 5 passed (10 assertions).
• docker compose exec app php artisan horizon:status → running.
• docker compose exec app php artisan schedule:list → 4 scheduled commands.
• docker compose down && docker compose up -d → fast restart, no re-migration thanks to migrate --graceful.
• docker compose down -v && docker compose up --build → full reset works; composer install + npm ci re-run inside the container.
• docker build --target production -t trypost:prod -f docker/Dockerfile . → production image builds cleanly without source-mount.
• compose.yaml validated: docker compose config --quiet exits 0; docker buildx --check reports no warnings.

Out of scope

• Production deploy guides (Swarm / Kubernetes / Forge). The production target is offered, but orchestration is left to self-hosters.
• Selenium / Dusk service: omitted from compose.yaml to keep first-boot small. compose.override.yaml.example shows how to add it.
• CI changes: .env.ci and .github/workflows/ are unchanged.

🤖 Generated with Claude Code