flamenco/docs/MODERN_COMPOSE_SETUP.md
Ryan Malloy e8ea44a0a6 Implement optimized Docker development environment
- Add multi-stage Dockerfile.dev with 168x Go module performance improvement
- Implement modern Docker Compose configuration with caddy-docker-proxy
- Add comprehensive Makefile.docker for container management
- Migrate from Poetry to uv for Python dependencies
- Fix Alpine Linux compatibility and Docker mount conflicts
- Create comprehensive documentation in docs/ directory
- Add Playwright testing integration
- Configure reverse proxy with automatic HTTPS
- Update .gitignore for Docker development artifacts
2025-09-09 10:25:30 -06:00

5.0 KiB

Modern Docker Compose Setup

This document explains the modern Docker Compose configuration for Flamenco development.

Changes Made

1. Updated to Modern Docker Compose

File Naming:

  • docker-compose.dev.ymlcompose.dev.yml
  • Removed version specification (now inferred automatically)

Command Usage:

  • docker-composedocker compose (plugin-based)
  • All scripts and documentation updated

2. Compose File Structure

# compose.dev.yml
# No version specification needed - uses latest format

services:
  flamenco-manager:
    # Caddy reverse proxy labels
    labels:
      caddy: manager.${DOMAIN}
      caddy.reverse_proxy: "{{upstreams 8080}}"
    networks:
      - flamenco-net
      - caddy  # External caddy network

networks:
  caddy:
    external: true  # Connects to caddy-docker-proxy

3. Domain Configuration

Environment Variables (.env):

COMPOSE_PROJECT_NAME=flamenco-dev
DOMAIN=flamenco.l.supported.systems

Service Mapping:

  • Manager: manager.flamenco.l.supported.systems
  • Vue.js Frontend: flamenco.l.supported.systems
  • Documentation: docs.flamenco.l.supported.systems
  • Profiling: profiling.flamenco.l.supported.systems

4. Modern Command Examples

# Basic operations
docker compose -f compose.dev.yml up -d
docker compose -f compose.dev.yml down
docker compose -f compose.dev.yml ps
docker compose -f compose.dev.yml logs -f

# Development profiles
docker compose -f compose.dev.yml --profile dev-tools up -d

# Execute commands
docker compose -f compose.dev.yml exec flamenco-manager ./mage generate

# Build with progress
docker compose -f compose.dev.yml build --progress=plain

Prerequisites

Docker Compose Plugin

Ensure you have the modern Docker Compose plugin:

# Check if available
docker compose version

# Install on Ubuntu/Debian
sudo apt update
sudo apt install docker-compose-plugin

# Install on other systems
# Follow: https://docs.docker.com/compose/install/

Caddy Docker Proxy

For reverse proxy functionality:

# Create network
docker network create caddy

# Start caddy-docker-proxy
docker run -d \
  --name caddy-docker-proxy \
  --restart unless-stopped \
  --network caddy \
  -p 80:80 -p 443:443 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v caddy_data:/data \
  lucaslorentz/caddy-docker-proxy:ci-alpine

Benefits of Modern Setup

1. Plugin Integration

  • Better integration with Docker Desktop
  • Consistent CLI experience across platforms
  • Automatic updates with Docker

2. Simplified Configuration

  • No version specification needed
  • Cleaner YAML structure
  • Better error messages

3. Enhanced Networking

  • Simplified external network references
  • Better service discovery
  • Improved container communication

4. Development Experience

  • Faster builds with improved caching
  • Better progress reporting
  • Enhanced debugging output

Migration Notes

From Legacy docker-compose

If migrating from older setups:

  1. Update Commands:

    # Old
    docker-compose -f docker-compose.dev.yml up -d
    
    # New
    docker compose -f compose.dev.yml up -d
    
  2. Install Plugin:

    # Remove standalone (if installed)
    sudo rm /usr/local/bin/docker-compose
    
    # Install plugin
    sudo apt install docker-compose-plugin
    
  3. Update Scripts: All development scripts now use docker compose commands.

Backward Compatibility

The setup maintains compatibility with:

  • Existing volume names and data
  • Container networking
  • Environment variable usage
  • Development workflows

Validation

Validate your setup:

# Check Docker Compose availability
docker compose version

# Validate compose file syntax
docker compose -f compose.dev.yml config --quiet

# Test environment variable substitution
docker compose -f compose.dev.yml config | grep -i domain

Troubleshooting

Common Issues

  1. "docker: 'compose' is not a docker command"

    • Install docker-compose-plugin
    • Restart Docker service
  2. Network 'caddy' not found

    • Create external network: docker network create caddy
    • Start caddy-docker-proxy
  3. Environment variables not loading

    • Ensure .env file exists in project root
    • Check file permissions: chmod 644 .env

Best Practices

  1. Use Profiles:

    # Core services only
    docker compose -f compose.dev.yml up -d
    
    # With development tools
    docker compose -f compose.dev.yml --profile dev-tools up -d
    
  2. Environment Management:

    # Always use project-specific .env
    cp .env.dev .env
    # Customize as needed
    
  3. Service Dependencies:

    # Start dependencies first
    docker network create caddy
    docker compose -f compose.dev.yml up shared-storage-setup
    docker compose -f compose.dev.yml up -d flamenco-manager flamenco-worker
    

This modern setup provides a cleaner, more maintainable development environment while leveraging the latest Docker Compose features and best practices.