Docker Compose Management

Instructions

Manage multi-container stacks using Docker Compose V2 (docker compose, not docker-compose).

Service orchestration:

• Define depends_on with condition: service_healthy to enforce startup order
• Every service must have a healthcheck — use curl, pg_isready, redis-cli ping, or wget as appropriate
• Group related services in a single compose file; use profiles for optional services (e.g., monitoring)

Named volumes for persistence:

• Always use named volumes, never bind mounts for production data
• Name volumes descriptively: iti-postgres-data, iti-redis-data, iti-n8n-data
• Declare volumes in the top-level volumes: section

Configuration with .env files:

• Store all environment-specific values in .env (gitignored)
• Reference in compose: ${VARIABLE_NAME} with sensible defaults via ${VAR:-default}
• Maintain a .env.example with placeholder values committed to the repo

Port mapping strategy:

• Map only necessary ports to the host; keep inter-service communication on the Docker network
• Use non-standard host ports to avoid conflicts: 5678:5678 (n8n), 8080:80 (Dify)
• Document all exposed ports in a comment block at the top of the compose file

Container naming conventions:

• Use project prefix: iti-postgres, iti-redis, iti-n8n, iti-dify-api
• Set container_name explicitly for predictable docker exec commands

Image management:

• Pin images to specific versions in production: pgvector/pgvector:pg16, redis:7-alpine
• Use :latest only in development; document the pinned version in comments
• Pull updates explicitly: docker compose pull && docker compose up -d

Reference architecture — ITI 9-container stack:

• PostgreSQL (pgvector:pg16), Redis (7-alpine), n8n, Dify API, Dify Web, Dify Worker, Dify Sandbox, Dify SSRF Proxy, Nginx

Backup strategy:

• Database: docker exec iti-postgres pg_dump -U postgres dbname > backup.sql
• Volumes: docker run --rm -v volume_name:/data -v $(pwd):/backup alpine tar czf /backup/volume.tar.gz /data
• Schedule backups via cron or n8n workflow; retain 7 daily + 4 weekly snapshots

Resource allocation:

• Full ITI stack: minimum 4 CPU cores, 6-8 GB RAM
• Set mem_limit and cpus per service to prevent resource starvation
• Monitor with docker stats and alert on sustained >80% usage