Before you start
- Docker and its Compose plugin installed (see installing Docker on Debian or Ubuntu)
- The basic commands (see the essential Docker commands)
In plain words
With docker run, each container starts with a long line of options that you have to remember or write down somewhere. Docker Compose replaces those lines with a file, compose.yaml, which describes the whole application: the containers, their ports, their volumes, their variables, and how they talk to each other. It's the recipe written down rather than kept in your head: you reread it, change it, save it with Git, and restart everything with one command.
1. Why Compose
With docker run |
With Compose |
|---|---|
| One command per container, to remember | One file describing all the containers |
| Network and names to create by hand | A private network created automatically; services reach each other by name |
| Startup order to manage yourself | Declared dependencies (depends_on) |
| Configuration hard to share | Text file, version-controlled with Git, readable |
| Updates container by container | docker compose pull then docker compose up -d |
2. The file structure
services: # the application's containers
service-name:
image: … # the image and its version
restart: … # the restart policy
ports: […] # the ports published on the host
environment: … # the configuration variables
volumes: […] # the persistent data
depends_on: … # the services to start first
volumes: # the named volumes used above
volume-name:
networks: # optional: extra networks
The file is called compose.yaml (the old name docker-compose.yml is still recognised). Indentation uses spaces, never tabs, and it has meaning: two spaces per level.
Keep each application in its own folder, for example /opt/forgejo/. The folder name becomes the project name, which prefixes the containers, volumes and networks created.
3. A complete example: Forgejo and PostgreSQL
Forgejo is an open source, self-hostable Git forge that stores its data in a PostgreSQL database. It's a good example of a two-service application.
The secrets file: .env
sudo mkdir -p /opt/forgejo
cd /opt/forgejo
Create /opt/forgejo/.env:
POSTGRES_PASSWORD=replace-with-a-long-password
FORGEJO_VERSION=16
Generate a strong password with openssl rand -base64 32, then protect the file:
sudo chmod 600 /opt/forgejo/.env
Compose automatically reads the .env file next to compose.yaml and replaces the ${VARIABLE} placeholders in the file with their value.
The compose.yaml file
services:
forgejo:
image: codeberg.org/forgejo/forgejo:${FORGEJO_VERSION}
container_name: forgejo
restart: unless-stopped
environment:
USER_UID: "1000"
USER_GID: "1000"
FORGEJO__database__DB_TYPE: postgres
FORGEJO__database__HOST: db:5432
FORGEJO__database__NAME: forgejo
FORGEJO__database__USER: forgejo
FORGEJO__database__PASSWD: ${POSTGRES_PASSWORD}
volumes:
- forgejo-data:/data
- /etc/localtime:/etc/localtime:ro
ports:
- "192.168.1.10:3000:3000"
- "192.168.1.10:2222:22"
depends_on:
db:
condition: service_healthy
db:
image: postgres:17-alpine
container_name: forgejo-db
restart: unless-stopped
environment:
POSTGRES_DB: forgejo
POSTGRES_USER: forgejo
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- forgejo-db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U forgejo -d forgejo"]
interval: 10s
timeout: 5s
retries: 5
volumes:
forgejo-data:
forgejo-db:
| Element | Explanation |
|---|---|
${FORGEJO_VERSION} |
The version comes from the .env file: you change it in one place only. Check the latest stable version on Forgejo's website |
FORGEJO__database__HOST: db:5432 |
Forgejo reaches the database by the service name db, in the private network created by Compose |
No ports: for db |
The database can only be reached by the project's containers, never from the network |
ports: "192.168.1.10:3000:3000" |
The web interface is only published on the local network address (published ports bypass ufw) |
2222:22 |
Git access over SSH, on port 2222 so as not to clash with the server's own SSH |
healthcheck and condition: service_healthy |
Forgejo waits until PostgreSQL is really ready, not just started |
/etc/localtime:ro |
The container uses the host's time zone, read-only |
volumes: at the bottom |
Declares the two named volumes: Git data and database |
Start and check
First check the syntax and the variable substitution:
sudo docker compose config
The command shows the final file, with variables substituted, or a precise error. Then start:
sudo docker compose up -d
sudo docker compose ps
NAME IMAGE SERVICE STATUS PORTS
forgejo codeberg.org/forgejo/forgejo:16 forgejo Up 20 seconds 192.168.1.10:3000->3000/tcp, 192.168.1.10:2222->22/tcp
forgejo-db postgres:17-alpine db Up 31 seconds (healthy)
Open http://192.168.1.10:3000 and finish Forgejo's setup wizard: the database settings are already filled in. Create the administrator account (for example spo).
The .env file doesn't go into Git
If you version the folder, add .env to the .gitignore file, and provide a .env.example without the real values instead. A password published on a forge, even a private one, must be considered compromised.
4. Everyday commands
They all run in the folder containing compose.yaml (or with -f /opt/forgejo/compose.yaml).
| Command | Effect |
|---|---|
docker compose up -d |
Creates and starts all services; recreates those whose configuration changed |
docker compose ps |
Status of the project's services |
docker compose logs -f |
Live logs of all services |
docker compose logs -f --tail 100 forgejo |
Logs of a single service |
docker compose restart forgejo |
Restarts a service |
docker compose stop |
Stops the services without deleting them |
docker compose down |
Stops and deletes the containers and the network; volumes are kept |
docker compose exec db psql -U forgejo |
Runs a command in a running service |
docker compose pull |
Downloads new versions of the images |
docker compose config |
Validates the file and shows the final result |
docker compose top |
Processes of each service |
docker compose down -v
The -v option also deletes the project's volumes: the database and the Git repositories disappear. Only use it to deliberately wipe a test project.
5. Updating
- Read the application's release notes: a major version may require a migration.
- Back up (section 6).
- Change the version in
.envif you follow a specific version, then:
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune
Compose only recreates the containers whose image changed. Follow the logs (docker compose logs -f) during the restart.
Automatic updates
Some tools can update containers on their own. It's handy for a low-stakes service, but risky for a database or an application that needs migrations: an update that fails at 3 a.m. goes unnoticed until the next day. Prefer scheduled, monitored updates, and pin major versions.
6. Backing up
A backup of a Compose application has three parts:
| Part | How |
|---|---|
The configuration: compose.yaml and .env |
Copy of the /opt/forgejo/ folder (the .env in a protected location) |
| The database | Consistent export with the database's own tool |
| The application's files | Archive of the volume, with the application stopped or frozen |
Export the PostgreSQL database without stopping the service:
sudo docker compose exec -T db pg_dump -U forgejo -d forgejo | gzip > forgejo-db-$(date +%F).sql.gz
Archive the data volume, with the service stopped to guarantee consistency:
sudo docker compose stop forgejo
sudo docker run --rm -v forgejo_forgejo-data:/data:ro -v "$PWD":/backup debian:13 tar czf /backup/forgejo-data-$(date +%F).tar.gz -C /data .
sudo docker compose start forgejo
The volume's real name is prefixed with the project name (forgejo_forgejo-data): check it with docker volume ls. Then copy these archives off the server (see the 3-2-1 rule), and test a restore.
7. Good practice
| Practice | Why |
|---|---|
One folder per application (/opt/name/) with its compose.yaml and .env |
Clear organisation, simple backup |
Pinned versions (postgres:17-alpine, not latest) |
No surprise major change |
Secrets in .env, permissions 600, out of Git |
Passwords don't lie around in the main file |
Databases with no ports: |
They can only be reached by the application |
| Ports published on a specific address or behind a reverse proxy | Published ports bypass the host's firewall |
restart: unless-stopped |
Automatic restart after a crash or a server reboot |
healthcheck on critical services |
Startup in the right order, status visible in docker compose ps |
docker compose config before every up |
Syntax or variable errors show up before they break the service |
File versioned with Git (without .env) |
History of changes, easy rollback |
Key points
compose.yamldescribes the whole application; services reach each other by name in a private network.- Secrets in
.env(permissions 600, never in Git), image versions pinned. docker compose up -d,ps,logs -f,pull,down: the five everyday commands.down -vdeletes the data: handle with care.- Backup = configuration + database export + volumes, copied off the server and tested.