How to Deploy & Use docker/compose

# Docker Compose Deployment & Usage Guide

## Prerequisites

- **Docker Engine** 20.10.0 or later (required for the Compose V2 plugin architecture)
- **Go** 1.21 or later (only required for building from source)
- **Git** (for cloning the repository)
- **Linux/macOS/Windows**: Platform-specific binary support (Linux AMD64/ARM64, macOS Intel/Apple Silicon, Windows)

## Installation

### Option 1: Docker Desktop (Windows & macOS)
Docker Compose is included automatically with [Docker Desktop](https://www.docker.com/products/docker-desktop/). No additional installation required.

### Option 2: Binary Installation (Linux)
Download the latest release from the [GitHub Releases](https://github.com/docker/compose/releases) page:

```bash
# Download latest release (adjust version and architecture as needed)
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" -o docker-compose

# Make executable
chmod +x docker-compose

# Install as Docker CLI plugin (user-specific)
mkdir -p $HOME/.docker/cli-plugins
mv docker-compose $HOME/.docker/cli-plugins/

# Or install system-wide (requires root)
sudo mv docker-compose /usr/local/lib/docker/cli-plugins/
# Alternative system paths: /usr/lib/docker/cli-plugins or /usr/libexec/docker/cli-plugins

Option 3: Build from Source

# Clone repository
git clone https://github.com/docker/compose.git
cd compose

# Build the binary
go build -ldflags="-s -w" -o docker-compose ./cmd

# Install as plugin
mkdir -p $HOME/.docker/cli-plugins
cp docker-compose $HOME/.docker/cli-plugins/

# Verify installation
docker compose version

Configuration

Environment Variables

Configure Compose behavior using these environment variables (defined in cmd/compose/compose.go):

CLI Plugin Paths

Docker searches for plugins in the following order:

1. $HOME/.docker/cli-plugins/docker-compose (user-specific)
2. /usr/local/lib/docker/cli-plugins/docker-compose (system-wide)
3. /usr/lib/docker/cli-plugins/docker-compose (distribution packages)

Compose File Configuration

Create a compose.yaml (or docker-compose.yml) in your project root:

services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/code
  redis:
    image: redis

Advanced Options (from pkg/api/api.go):

• COMPOSE_PROFILES: Activate specific service profiles
• COMPOSE_FILE: Specify alternative compose file paths
• COMPOSE_ENV_FILES: Load additional environment files

Build & Run

Development Build

# Build with debug symbols
go build -o docker-compose ./cmd

# Run locally without installing
./docker-compose up

# Or use as Docker plugin directly
docker compose up

Production Build

# Optimized build
go build -ldflags="-s -w -X github.com/docker/compose/v5/internal.Version=$(git describe --tags)" -o docker-compose .

# Install system-wide
sudo install -m 755 docker-compose /usr/local/bin/
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo ln -sf /usr/local/bin/docker-compose /usr/local/lib/docker/cli-plugins/docker-compose

Basic Usage

# Start all services
docker compose up

# Start in detached mode
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

# Build images before starting
docker compose up --build

# Scale specific services
docker compose up -d --scale web=3

Watch Mode (Development)

For file synchronization during development (using the watch functionality from pkg/compose/watch.go):

services:
  web:
    build: .
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: ./package.json

Then run:

docker compose watch

Deployment

Server Installation

For production servers running Linux:

# Download specific version
VERSION=v2.23.0
curl -L "https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-linux-x86_64" -o docker-compose
chmod +x docker-compose
sudo install -m 755 docker-compose /usr/local/lib/docker/cli-plugins/

# Verify
docker compose version

CI/CD Integration

GitHub Actions Example:

- name: Run Docker Compose
  run: |
    docker compose up -d
    docker compose exec app ./run-tests.sh
    docker compose down

GitLab CI Example:

deploy:
  image: docker:latest
  script:
    - docker compose -f docker-compose.prod.yml up -d

Air-Gapped Environments

1. Download binary and transfer to target system
2. Place compose files in project directory
3. Use COMPOSE_OFFLINE=true to prevent remote resource fetching (referencing pkg/api/api.go Offline mode)
4. Pre-pull required images on connected system: docker compose pull

Troubleshooting

Plugin Not Detected

Symptom: docker: 'compose' is not a docker command

Solution:

# Verify plugin path
docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}'

# Check if binary exists in correct location
ls -la $HOME/.docker/cli-plugins/docker-compose

# Ensure executable permissions
chmod +x $HOME/.docker/cli-plugins/docker-compose

Permission Denied

Symptom: permission denied while trying to connect to Docker daemon

Solution:

• Add user to docker group: sudo usermod -aG docker $USER
• Or use sudo (not recommended for CI): sudo docker compose up

Build Failures

Symptom: Build context errors or missing dependencies

Solution:

# Clean build cache
docker compose build --no-cache

# Verify Go version (for source builds)
go version  # Must be 1.21+

# Check module dependencies
go mod download
go mod verify

Convergence Issues

Symptom: Services fail to start with dependency errors (referencing pkg/compose/convergence.go)

Solution:

• Check service health definitions in compose file
• Verify network connectivity between containers
• Use docker compose up --abort-on-container-exit to catch early failures
• Check for port conflicts: docker compose ps to see allocated ports

Dry Run Debugging

To test configurations without executing (using dry run client from pkg/dryrun/dryrunclient.go):

# Validate compose file
docker compose config

# Check for syntax errors
docker compose config --quiet