flamenco/docs/MODERN_COMPOSE_SETUP.md

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.yml → compose.dev.yml
• Removed version specification (now inferred automatically)

Command Usage:

• docker-compose → docker 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.