Docker Compose Setup

Docker Compose Setup Skill

Master Docker Compose for multi-container application orchestration with service dependencies, health checks, and environment management.

Purpose

Design and configure Docker Compose files for development and production environments with proper service orchestration.

Parameters

Modern Compose File (2024-2025)

Note: The version field is deprecated. Start directly with services:.

services:
  frontend:
    build:
      context: ./frontend
      target: production
    ports:
      - "80:80"
    depends_on:
      backend:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

  backend:
    build: ./backend
    expose:
      - "3000"
    environment:
      DATABASE_URL: postgres://user:${DB_PASSWORD}@database:5432/app
    depends_on:
      database:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5

  database:
    image: postgres:16-alpine
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  db_data:

Environment Management

Base + Override Pattern

# docker-compose.yaml (base)
services:
  app:
    image: myapp:latest

# docker-compose.override.yaml (dev - auto-loaded)
services:
  app:
    build: .
    volumes:
      - ./src:/app/src
    environment:
      - DEBUG=true

# docker-compose.prod.yaml (production)
services:
  app:
    deploy:
      replicas: 3
    restart: always

# Development (loads override automatically)
docker compose up

# Production
docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d

Environment Variables

# .env file (auto-loaded)
DB_PASSWORD=secret123
APP_VERSION=1.2.3

# Using in compose
environment:
  - DB_PASSWORD=${DB_PASSWORD}
  - VERSION=${APP_VERSION:-latest}  # Default value

Service Profiles

services:
  app:
    image: myapp

  # Only with --profile debug
  debugger:
    image: debug-tools
    profiles:
      - debug

  # Only with --profile testing
  test-db:
    image: postgres:alpine
    profiles:
      - testing

docker compose up                     # app only
docker compose --profile debug up     # app + debugger

Common Commands

# Start services
docker compose up -d

# Rebuild and start
docker compose up -d --build

# View logs
docker compose logs -f backend

# Scale service
docker compose up -d --scale backend=3

# Stop and clean
docker compose down -v

# Validate config
docker compose config

Error Handling

Common Errors

Fallback Strategy

1. Validate with docker compose config 2. Start services individually 3. Use --no-deps to skip dependencies

Troubleshooting

Debug Checklist

• [ ] Valid YAML? docker compose config
• [ ] Images available? docker compose pull
• [ ] Dependencies healthy? Check healthchecks
• [ ] Environment set? Check .env file

Health Check Debugging

# Check health status
docker inspect --format='{{json .State.Health}}' <container>

# View health logs
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' <container>

Usage

Skill("docker-compose-setup")

Related Skills

• docker-networking
• docker-volumes
• docker-production

Docker Compose Setup Guide

Overview

This guide provides comprehensive documentation for the docker-compose-setup skill in the custom-plugin-docker plugin.

Category: Containers

Quick Start

Prerequisites

• Familiarity with containers concepts
• Development environment set up
• Plugin installed and configured

Basic Usage

# Invoke the skill
claude "docker-compose-setup - [your task description]"

# Example
claude "docker-compose-setup - analyze the current implementation"

Core Concepts

Key Principles

1. Consistency - Follow established patterns 2. Clarity - Write readable, maintainable code 3. Quality - Validate before deployment

Best Practices

• Always validate input data
• Handle edge cases explicitly
• Document your decisions
• Write tests for critical paths

Common Tasks

Task 1: Basic Implementation

# Example implementation pattern
def implement_docker_compose_setup(input_data):
    """
    Implement docker-compose-setup functionality.

    Args:
        input_data: Input to process

    Returns:
        Processed result
    """
    # Validate input
    if not input_data:
        raise ValueError("Input required")

    # Process
    result = process(input_data)

    # Return
    return result

Task 2: Advanced Usage

For advanced scenarios, consider:

• Configuration customization via assets/config.yaml
• Validation using scripts/validate.py
• Integration with other skills

Troubleshooting

Common Issues

Related Resources

• SKILL.md - Skill specification
• config.yaml - Configuration options
• validate.py - Validation script

---

Last updated: 2025-12-30

Docker Compose Setup Patterns

Design Patterns

Pattern 1: Input Validation

Always validate input before processing:

def validate_input(data):
    if data is None:
        raise ValueError("Data cannot be None")
    if not isinstance(data, dict):
        raise TypeError("Data must be a dictionary")
    return True

Pattern 2: Error Handling

Use consistent error handling:

try:
    result = risky_operation()
except SpecificError as e:
    logger.error(f"Operation failed: {e}")
    handle_error(e)
except Exception as e:
    logger.exception("Unexpected error")
    raise

Pattern 3: Configuration Loading

Load and validate configuration:

import yaml

def load_config(config_path):
    with open(config_path) as f:
        config = yaml.safe_load(f)
    validate_config(config)
    return config

Anti-Patterns to Avoid

❌ Don't: Swallow Exceptions

# BAD
try:
    do_something()
except:
    pass

✅ Do: Handle Explicitly

# GOOD
try:
    do_something()
except SpecificError as e:
    logger.warning(f"Expected error: {e}")
    return default_value

Category-Specific Patterns: Containers

Recommended Approach

1. Start with the simplest implementation 2. Add complexity only when needed 3. Test each addition 4. Document decisions

Common Integration Points

• Configuration: assets/config.yaml
• Validation: scripts/validate.py
• Documentation: references/GUIDE.md

---

Pattern library for docker-compose-setup skill