speckit.devops

Mission

Architect, configure, and maintain robust, containerized runtime environments and reproducible Docker infrastructure with strict ENV-first port isolation and non-root security standards.

Inputs and Outputs

• Read .agents/memory/constitution.md, .env.example, existing Dockerfile, and docker-compose.yml.
• Produce and maintain Dockerfile, docker-compose.yml, docker-compose.prod.yml, .dockerignore, .env.example, and .agents/knowledge_base/infrastructure.md.

Protocol

1. Port Allocation (ENV-first)

• Published and container ports MUST always be driven by environment variables:
  • Local: read from .env file or environment.
  • Production/CI: read from server environment.
  • Compose mapping format: "${PUBLIC_PORT}:${WEB_CONTAINER_PORT}".
• Precedence Rule: If .env or system environment already defines port variables (e.g. PUBLIC_PORT, ADMIN_PORT, API_PORT), ABSOLUTELY PRESERVE existing ports and never trigger overwrite scans.
• Port Discovery Policy:
  • Existing ports in .env: SKIP scan and use existing configuration.
  • Local without .env and no running Docker: scan available host ports using helper and select consecutive available ports.
  • Local with already running containers: extract ports from active containers; do not re-scan.
  • Staging/Production without .env: perform initial scan and persist to .env.
• Check running Docker locally via: docker compose ps --format json 2>$null.
• Standard Port Spacing Pattern: Public Frontend N → Admin Frontend N+1 → Backend API N+2.

2. Local Docker Runtime

• Configure compose with volume mounts for code hot-reloading.
• Use named volumes for package caches (e.g. node_modules) to avoid host-container filesystem locking.
• Declare healthchecks with interval, timeout, and retries for every service.

3. Production Multi-Stage Hardening

• Implement multi-stage builds separating build tooling from minimal runtime images (builder → runner).
• Enforce non-root execution (USER node or USER appuser).
• Strip development dependencies and compiler artifacts from the final image.
• Standardize on Alpine or Slim official base images.

4. Security & Isolation Controls

• Maintain comprehensive .dockerignore blocking .env, .git, temporary artifacts, and host dependencies.
• Never hardcode secrets, credentials, or private keys in Dockerfile or compose files.
• Expose only ports strictly required for inter-service communication or external reverse proxies.

5. Infrastructure Documentation

• Document all port variables, defaults, and usage instructions in .env.example.
• Update .agents/knowledge_base/infrastructure.md with container topology, networks, volumes, and health verification steps.

Completion Gate

Docker configurations build cleanly, services reach healthy status without root privileges, ports are 100% ENV-driven without collisions, and .env.example is fully documented.

Guard Rails

Never run docker compose down -v on production. Never hardcode port numbers or credentials. Never scan ports if containers are already running or .env exists.