Skip to main content

🌊 Docker Compose Guide

Running a Docker Compose Project

This guide explains how to start services defined in a compose.yml or docker-compose.yml file.

Prerequisites

Make sure the following software is installed:

    Docker Engine Docker Compose Plugin

    Verify the installation:

    docker --version
docker compose version

    Expected output:

    Project Structure

    Example:

    llama-cpp/
├── compose.yml
└── models/

    services:
  llama-cpp:
    image: registry.chenjia.org/llama-cpp:sm120-rev1
    container_name: llama-cpp
    ports:
      - 8888:8080
    privileged: true
    ipc: host
    volumes:
      - ./models:/models:ro
    command: >
      -m /models/gemma-4-E2B-it-Q4_K_M.gguf
      -md /models/gemma-4-E2B-it-assistant.Q4_K_M.gguf
      --port 8080 --host 0.0.0.0 -t 12 -c 262144 -b 4096 -ub 4096 -ngl 99 -ngld 99
      --no-context-shift --no-mmap --jinja --cpu-moe --kv-unified
      -ctk turbo3 -ctv turbo3 -ctkd turbo3 -ctvd turbo3 --parallel 4 -fa on
      --spec-type nextn --draft-max 3 --draft-min 0
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities:
                - gpu
    restart: unless-stopped

    Start the Services

    Navigate to the directory containing the compose file:

    cd project

    Start all services in the background:

    docker compose up -d

    If your file has a custom name:

    docker compose -f my-compose.yml up -d

    Check Container Status

    Display running containers:

    docker compose ps

    Example output:

    NAME        IMAGE                    STATUS
web         nginx:latest             Up
database    postgres:17              Up

    View Logs

    Show logs from all services:

    docker compose logs

    Follow logs in real time:

    docker compose logs -f

    View logs from a specific service:

    docker compose logs -f web

    Restart Services

    Restart all services:

    docker compose restart

    Restart a single service:

    docker compose restart web

    Stop Services

    Stop containers while preserving volumes and networks:

    docker compose stop

    Stop and Remove Everything

    Remove containers, networks, and temporary resources:

    docker compose down

    Also remove volumes:

    docker compose down -v

    Also remove locally built images:

    docker compose down --rmi local

    Update Containers After Editing compose.yml

    If you modify the compose file, recreate the containers:

    docker compose up -d

    If the image needs to be rebuilt:

    docker compose up -d --build

    Force recreation:

    docker compose up -d --force-recreate

    Pull Latest Images

    Download the latest image versions:

    docker compose pull

    Then restart:

    docker compose up -d

    Useful Commands

    Action Command Start services docker compose up -d Stop services docker compose stop Remove services docker compose down View logs docker compose logs -f List containers docker compose ps Restart services docker compose restart Pull updates docker compose pull Rebuild images docker compose up -d --build

    Common Troubleshooting

    Port Already in Use

    Error:

    Bind for 0.0.0.0:8080 failed

    Check which process is using the port:

    Linux:

    sudo lsof -i :8080

    Windows:

    netstat -ano | findstr :8080

    Change the port mapping in compose.yml if necessary.

    Container Keeps Restarting

    Inspect logs:

    docker compose logs -f <service_name>

    Example:

    docker compose logs -f llama-cpp

    Configuration Validation

    Validate the compose file:

    docker compose config

    This command checks syntax and displays the final merged configuration.

    # Start services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

# Update images
docker compose pull
docker compose up -d

# Shutdown
docker compose down
    Back to top