# 🌊 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:

```bash
docker --version
docker compose version
```

Expected output:

[![](https://wiki.chenjia.org/uploads/images/gallery/2026-06/scaled-1680-/qKzhEAIKW7BHahBL-image-1781224171950.png)](https://wiki.chenjia.org/uploads/images/gallery/2026-06/qKzhEAIKW7BHahBL-image-1781224171950.png)

---

## Project Structure

Example:

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

```yaml
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:

```bash
cd llama-cpp
```

Start all services in the background:

```bash
docker compose up -d
```

If your file has a custom name:

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

---

## Check Container Status

Display running containers:

```bash
docker compose ps
```

Example output:

[![](https://wiki.chenjia.org/uploads/images/gallery/2026-06/scaled-1680-/SH34GBr2F5RfLLKx-image-1781224306798.png)](https://wiki.chenjia.org/uploads/images/gallery/2026-06/SH34GBr2F5RfLLKx-image-1781224306798.png)

---

## View Logs

Show logs from all services:

```bash
docker compose logs
```

Follow logs in real time:

```bash
docker compose logs -f
```

View logs from a specific service:

```bash
docker compose logs -f web
```

---

## Restart Services

Restart all services:

```bash
docker compose restart
```

Restart a single service:

```bash
docker compose restart web
```

---

## Stop Services

Stop containers while preserving volumes and networks:

```bash
docker compose stop
```

---

## Stop and Remove Everything

Remove containers, networks, and temporary resources:

```bash
docker compose down
```

Also remove volumes:

```bash
docker compose down -v
```

Also remove locally built images:

```bash
docker compose down --rmi local
```

---

## Update Containers After Editing compose.yml

If you modify the compose file, recreate the containers:

```bash
docker compose up -d
```

If the image needs to be rebuilt:

```bash
docker compose up -d --build
```

Force recreation:

```bash
docker compose up -d --force-recreate
```

---

## Pull Latest Images

Download the latest image versions:

```bash
docker compose pull
```

Then restart:

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

```text
Bind for 0.0.0.0:8080 failed
```

Check which process is using the port:

Linux:

```bash
sudo lsof -i :8080
```

Windows:

```powershell
netstat -ano | findstr :8080
```

Change the port mapping in `compose.yml` if necessary.

---

### Container Keeps Restarting

Inspect logs:

```bash
docker compose logs -f <service_name>
```

Example:

```bash
docker compose logs -f llama-cpp
```

---

### Configuration Validation

Validate the compose file:

```bash
docker compose config
```

This command checks syntax and displays the final merged configuration.

---

## Recommended Workflow

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