docker

name	docker
description	Docker, Docker Compose, Dockerfile best practices, and multi-service orchestration. Use when writing Dockerfiles, docker-compose.yml, container healthchecks, or working with Docker images, volumes, and networks.

Docker

Project Setup

• Use docker-compose.yml for multi-service orchestration
• Use Dockerfile for custom images; place in dockerfiles/<service>/Dockerfile
• Use .env for configurable ports and credentials (never hardcode)
• Use .dockerignore to exclude node_modules, .git, .env, logs

Docker Compose Best Practices

• Every service needs a container_name
• Use healthcheck with appropriate intervals for all services
• Use depends_on with condition: service_healthy for startup ordering
• Use named volumes for persistent data (MySQL, MongoDB, Redis)
• Use bind mounts only for development code (./src:/app/src)
• Always specify restart: unless-stopped or on-failure:N
• Use networks to isolate services on a shared bridge network

Dockerfile Best Practices

• Use specific base image tags (e.g., php:8.5-apache, not php:latest)
• Combine RUN commands with && to reduce layers
• Clean up package caches in the same RUN layer (rm -rf /var/lib/apt/lists/*)
• Use COPY not ADD unless you need tar extraction
• Set WORKDIR before COPY/RUN commands
• Use multi-stage builds for compiled languages and Composer
• Order COPY by change frequency (package.json first, then source)
• Never run as root in production - use USER www-data or equivalent
• Include HEALTHCHECK instruction

PHP-Apache Specific

• Enable mod_rewrite for clean URLs: a2enmod rewrite
• Enable mod_headers for security headers: a2enmod headers
• Set AllowOverride All for .htaccess support
• Document root: /var/www/httpdocs (mapped from ./server/httpdocs)
• PHP extensions via install-php-extensions: gd, pdo_mysql, mysqli, zip, redis, xdebug
• PHP config in /usr/local/etc/php/conf.d/php-optimized.ini
• Composer install: curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
• APACHE_DOCUMENT_ROOT env var must match volume mount

MySQL Specific

• Use mysql:9.7 base image
• Healthcheck: mysqladmin ping -h localhost -uroot --silent
• Init SQL in /docker-entrypoint-initdb.d/ (runs alphabetically on first boot)
• Data persisted via named volume to /var/lib/mysql
• For development, MYSQL_ALLOW_EMPTY_PASSWORD: "true"; for production, use MYSQL_ROOT_PASSWORD

Port Conventions

• PHP-Apache: 8080 (configurable via APP_PORT)
• MySQL: 3306 (configurable via MYSQL_PORT)
• phpMyAdmin: 8081 (configurable via PMA_PORT)
• Node.js: 3000
• Deno: 8000
• Bun: 3000
• Redis: 6379
• MongoDB: 27017
• Nginx: 80/443
• Use 127.0.0.x for multi-service local access

Template Deployment

• When a template is deployed, READ ALL files before making changes
• Read the template README.md for guidance on file layout and conventions
• Update .env.example with new variables needed
• Update docker-compose.yml for any new services or port changes
• Update the Dockerfile for version changes or new extensions
• Update smoke tests to verify new functionality
• After all changes, verify: docker compose config (YAML validation)
• Run docker compose up -d --build and check docker compose ps

Smoke Test Pattern

• Verify docker --version and docker compose version
• Verify all containers running: docker compose ps --status running
• Verify healthchecks pass for each service
• Verify HTTP endpoints respond: curl -sf http://localhost:<port>/
• Verify database connectivity
• Verify file integrity (docker-compose.yml, README.md, key source files)

Common Pitfalls

• docker-compose vs docker compose - use docker compose (v2)
• Port conflicts - check nothing else uses the port before starting
• Volume permission issues on Linux - match UID/GID in Dockerfile
• Init SQL only runs on FIRST boot - use docker compose down -v to reset
• .env file must be in same directory as docker-compose.yml
• Container name conflicts - docker compose down before rebuilding