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 llama-cpp

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:

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