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

```yaml
# 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):**
```bash
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

```bash
# 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:

```bash
# 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:

```bash
# 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:**
   ```bash
   # Old
   docker-compose -f docker-compose.dev.yml up -d
   
   # New
   docker compose -f compose.dev.yml up -d
   ```

2. **Install Plugin:**
   ```bash
   # 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:

```bash
# 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:**
   ```bash
   # 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:**
   ```bash
   # Always use project-specific .env
   cp .env.dev .env
   # Customize as needed
   ```

3. **Service Dependencies:**
   ```bash
   # 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.