speckit.devops

🎯 Mission

Set up and manage a standardized and secure Docker system for the project. Published ports MUST always be configured via environment variables.

📥 Input

• .agents/memory/constitution.md (port configuration, security rules)
• Existing Dockerfile , docker-compose.yml (if available)
• .env.example

📋 Protocol

1. Port Allocation (ENV-first) ⭐

ALWAYS configure ports via ENV:

• .env file (local) or server ENV (production)
• docker-compose.yml reads: "${PUBLIC_PORT}:${WEB_CONTAINER_PORT}"
• Document required port variables in .env.example; do not hide missing configuration behind a fixed fallback.
• CRITICAL: If .env or system environment already has port variables defined (e.g. PUBLIC_PORT, ADMIN_PORT, API_PORT or equivalents), ABSOLUTELY SKIP port scanning/assignment and NEVER overwrite the existing port configuration.

Port scanning rules according to environment:

Environment	Existing Ports in .env?	Docker running?	Act
Any	✅ Yes	Any	SKIP scan — use existing ports, DO NOT overwrite
Local	❌ No	❌ No (first time)	Scan available ports with socket/helper → select 3 consecutive empty ports
Local	❌ No	✅ Already running	SKIP scan — use current ports from docker/containers
Staging/Beta/Prod	❌ No	Any	ALWAYS initial scan for configuration → write to .env

Check Docker is running (Local):

docker compose ps --format json 2>$null
# There are containers → SKIP port scan
# Empty/error → RUN port scan

• Pattern: Public FE N → Admin FE N+1 → Backend API N+2

2. Local Docker (docker-compose.yml):

• Published and container ports read from ENV: "${PUBLIC_PORT}:${WEB_CONTAINER_PORT}"
• Volume mounts cho hot-reload code
• Named volumes for node_modules (avoid host-container lock)
• Health checks for each service

3. Production Docker (docker-compose.prod.yml):

• Multi-stage builds (builder → runner)
• USER node or USER appuser (DO NOT run as root)
• Remove devDependencies in the final image
• Alpine/Slim base images
• Ports read from ENV (NO hard-code)