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>
This commit is contained in:
137
.env.docker.example
Normal file
137
.env.docker.example
Normal file
@@ -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
|
||||||
135
Makefile
Normal file
135
Makefile
Normal file
@@ -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"
|
||||||
220
docker-compose.yml
Normal file
220
docker-compose.yml
Normal file
@@ -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
|
||||||
142
docker/README.md
Normal file
142
docker/README.md
Normal file
@@ -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).
|
||||||
64
docker/app/Dockerfile
Normal file
64
docker/app/Dockerfile
Normal file
@@ -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"]
|
||||||
55
docker/app/entrypoint.sh
Normal file
55
docker/app/entrypoint.sh
Normal file
@@ -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 "$@"
|
||||||
18
docker/app/opcache.ini
Normal file
18
docker/app/opcache.ini
Normal file
@@ -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
|
||||||
23
docker/app/php-fpm.conf
Normal file
23
docker/app/php-fpm.conf
Normal file
@@ -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
|
||||||
24
docker/app/php.ini
Normal file
24
docker/app/php.ini
Normal file
@@ -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
|
||||||
9
docker/mariadb/init/01-create-test-db.sql
Normal file
9
docker/mariadb/init/01-create-test-db.sql
Normal file
@@ -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;
|
||||||
8
docker/nginx/Dockerfile
Normal file
8
docker/nginx/Dockerfile
Normal file
@@ -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
|
||||||
54
docker/nginx/conf.d/ezscale.conf
Normal file
54
docker/nginx/conf.d/ezscale.conf
Normal file
@@ -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;
|
||||||
|
}
|
||||||
|
}
|
||||||
40
docker/nginx/nginx.conf
Normal file
40
docker/nginx/nginx.conf
Normal file
@@ -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;
|
||||||
|
}
|
||||||
17
docker/traefik/dynamic.yml
Normal file
17
docker/traefik/dynamic.yml
Normal file
@@ -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"
|
||||||
33
docker/traefik/traefik.yml
Normal file
33
docker/traefik/traefik.yml
Normal file
@@ -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
|
||||||
16
docker/vite/Dockerfile
Normal file
16
docker/vite/Dockerfile
Normal file
@@ -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"]
|
||||||
@@ -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 |
|
||||||
@@ -51,7 +51,7 @@ return Application::configure(basePath: dirname(__DIR__))
|
|||||||
\App\Http\Middleware\ScreenshotAuthMiddleware::class,
|
\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->redirectUsersTo('/dashboard');
|
||||||
|
|
||||||
$middleware->alias([
|
$middleware->alias([
|
||||||
|
|||||||
@@ -29,7 +29,6 @@
|
|||||||
"laravel/boost": "^2.1",
|
"laravel/boost": "^2.1",
|
||||||
"laravel/pail": "^1.2.2",
|
"laravel/pail": "^1.2.2",
|
||||||
"laravel/pint": "^1.24",
|
"laravel/pint": "^1.24",
|
||||||
"laravel/sail": "^1.41",
|
|
||||||
"mockery/mockery": "^1.6",
|
"mockery/mockery": "^1.6",
|
||||||
"nunomaduro/collision": "^8.6",
|
"nunomaduro/collision": "^8.6",
|
||||||
"pestphp/pest": "^4.3",
|
"pestphp/pest": "^4.3",
|
||||||
|
|||||||
1475
website/composer.lock
generated
1475
website/composer.lock
generated
File diff suppressed because it is too large
Load Diff
@@ -33,6 +33,23 @@ export default defineConfig({
|
|||||||
},
|
},
|
||||||
},
|
},
|
||||||
server: {
|
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: {
|
watch: {
|
||||||
ignored: ['**/storage/framework/views/**'],
|
ignored: ['**/storage/framework/views/**'],
|
||||||
},
|
},
|
||||||
|
|||||||
Reference in New Issue
Block a user