Virtualization / Tutorial

Docker Compose: describing your services in a file

Moving from long docker run commands to a readable, version-controlled compose.yaml file: file structure, a complete example of an application with its PostgreSQL database, secrets in a .env file, health checks, everyday commands, updates and backups.

Virtualization Tutorial Intermediate Published October 20, 2026 Translated November 20, 2026 25 min read Version française
Aerial view of a commercial port and the city around it
Photo: Thilina Alagiyawanna on Unsplash

Before you start

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

  1. Read the application's release notes: a major version may require a migration.
  2. Back up (section 6).
  3. Change the version in .env if 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.yaml describes 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 -v deletes the data: handle with care.
  • Backup = configuration + database export + volumes, copied off the server and tested.

Read next