What are we building?

By the end, a complete monitoring stack runs behind your Traefik proxy, reachable at https://grafana.YOUR_DOMAIN with valid HTTPS. Four building blocks interlock:

• Prometheus 3.13 – the time-series database. It pulls (scrapes) metrics from the other services at intervals and stores them with a timestamp.
• node-exporter 1.12 – delivers the host metrics: CPU, memory, load, disks, network interfaces.
• cAdvisor 0.55 – delivers the container metrics: CPU and RAM per running container, so you see which service is eating.
• Grafana 13.1 – the interface: ready-made dashboards that turn the Prometheus data into graphs and displays.

The decisive difference from Uptime Kuma: instead of “green/red” you get trends – you recognize that the RAM has been slowly filling up for days, before the server swaps. Only Grafana is reachable from outside; Prometheus, node-exporter and cAdvisor get no public route.

Prerequisites

• Confidence with Docker Compose – services, volumes, networks. If that’s still new: understanding Docker Compose.
• A running Traefik reverse proxy with the shared proxy network and the Let’s Encrypt resolver le – set up as in reverse proxy with Traefik.
• A subdomain grafana.YOUR_DOMAIN whose DNS record (A/AAAA) points to your server IP – see connecting a domain to your server.

Step by step

Step 1: Understand the architecture

Before we create files, the picture behind it – otherwise you debug blind. Prometheus works on the pull principle: the services don’t send their values somewhere, but Prometheus queries them actively. Every “exporter” provides its metrics under /metrics, Prometheus fetches them every 15 seconds and stores them in its time-series database. Grafana in turn queries Prometheus and draws the graphs from it.

Why pull instead of push at all? Because this way Prometheus always knows whether a target is alive: if an exporter doesn’t respond, that’s itself information (up = 0). You need no agents that actively “phone home”, and you can simply enter every new target into the configuration. An exporter is nothing magical – it’s a tiny web server that delivers a text list of current measurements under /metrics.

From this follows the security rule of this setup: node-exporter, cAdvisor and Prometheus have no authentication. So they must never stand open on the internet. Prometheus and cAdvisor we bind only to the internal Docker network monitoring; node-exporter runs in the host network (why is explained in step 4), but stays unreachable from outside thanks to UFW and the netcup firewall. Only Grafana is additionally on the proxy network and gets a Traefik route – the only service with a login and a public address.

Step 2: Create the project folder and configure Prometheus

Create the folder structure:

mkdir -p ~/monitoring/prometheus ~/monitoring/grafana/provisioning/datasources
cd ~/monitoring

Create the Prometheus configuration. It defines whom Prometheus queries at what interval:

# prometheus/prometheus.yml
global:
  scrape_interval: 15s
  scrape_timeout: 10s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: node
    static_configs:
      - targets: ["host.docker.internal:9100"]

  - job_name: cadvisor
    static_configs:
      - targets: ["cadvisor:8080"]

Important: cadvisor:8080 appears as a service name – Docker resolves it automatically in the shared monitoring network. The node-exporter, on the other hand, runs in the host network (step 4 explains why) and is therefore addressed via host.docker.internal:9100 – Prometheus gets this name mapped to the Docker host’s IP via extra_hosts shortly. scrape_interval: 15s is a good compromise – often enough for meaningful curves, seldom enough to hardly create load.

Step 3: Provision the Grafana data source automatically

Instead of clicking the Prometheus data source into Grafana by hand later, we set it up via provisioning – as a file. That’s reproducible: after a rebuild, everything is immediately back, without clicking.

# grafana/provisioning/datasources/datasource.yml
apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

access: proxy means that Grafana itself (server-side) queries Prometheus – the user’s browser never talks to Prometheus directly. That’s exactly why Prometheus can stay internal.

Step 4: The Compose stack

Now the heart. Create the compose.yaml. Replace grafana.YOUR_DOMAIN and the Grafana password:

services:
  prometheus:
    image: prom/prometheus:v3.13.1
    container_name: prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=30d"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom_data:/prometheus
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks: [monitoring]
    restart: unless-stopped

  node-exporter:
    image: prom/node-exporter:v1.12.1
    container_name: node-exporter
    command:
      - "--path.rootfs=/host"
    network_mode: host
    pid: host
    volumes:
      - "/:/host:ro,rslave"
    restart: unless-stopped

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:v0.55.1
    container_name: cadvisor
    privileged: true
    devices:
      - /dev/kmsg
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    networks: [monitoring]
    restart: unless-stopped

  grafana:
    image: grafana/grafana:13.1.0
    container_name: grafana
    depends_on: [prometheus]
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: YOUR_GRAFANA_PASSWORD
      GF_SERVER_ROOT_URL: https://grafana.YOUR_DOMAIN
      GF_USERS_ALLOW_SIGN_UP: "false"
    volumes:
      - grafana_data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.grafana.rule=Host(`grafana.YOUR_DOMAIN`)"
      - "traefik.http.routers.grafana.entrypoints=websecure"
      - "traefik.http.routers.grafana.tls.certresolver=le"
      - "traefik.http.services.grafana.loadbalancer.server.port=3000"
    networks: [monitoring, proxy]
    restart: unless-stopped

volumes:
  prom_data:
  grafana_data:

networks:
  monitoring:
  proxy:
    external: true

What matters here:

• --storage.tsdb.retention.time=30d keeps metrics for 30 days. More = more meaning, but also more storage. 30 days is a good start.
• node-exporter needs the host root directory (/:/host:ro,rslave), pid: host and network_mode: host to read real host values instead of container values. --path.rootfs=/host tells it where the host view is (read-only, :ro). The host network isn’t a nice-to-have: /proc/net is bound to the network namespace – in a normal bridge network, node-exporter would see only its own container interface (effectively just the scrape traffic), not the real host interfaces. The price: node-exporter thus listens on port 9100 of the host – your firewall keeps the port closed from outside, and Prometheus reaches it via the extra_hosts entry (host-gateway).
• cAdvisor needs privileged: true, the device /dev/kmsg and read mounts on /sys and /var/lib/docker to detect all containers. That’s unavoidable for container monitoring – that’s why cAdvisor stays strictly internal.
• Only grafana carries Traefik labels and is on the proxy network. The internal port is 3000. GF_SERVER_ROOT_URL must be the public HTTPS address, otherwise logins and redirects break behind the proxy.
• GF_USERS_ALLOW_SIGN_UP: "false" prevents strangers from creating their own account. Set a strong admin password – Grafana is publicly accessible.

Step 5: Start and check the Prometheus targets

Start the complete stack:

docker compose up -d

The first time, Docker downloads four images – that takes a moment. Check that all containers are running:

docker compose ps

All four services (node-exporter, cadvisor, prometheus, grafana) should be running. Now the decisive test: Does Prometheus see its targets? Since Prometheus stays internal, we query it from a short-lived container that’s on the same network (Compose calls the network monitoring_monitoring – project folder plus network name):

docker run --rm --network monitoring_monitoring curlimages/curl:8.21.0 \
  -s http://prometheus:9090/api/v1/query?query=up

In the JSON response there’s a "value" with "1" for each target – that means “reachable”. In the test all three jobs (prometheus, node, cadvisor) returned a 1. A 0 means Prometheus can’t scrape the target – then the section “When things go wrong” helps.

Step 6: Open Grafana and import dashboards

Open https://grafana.YOUR_DOMAIN. Traefik fetches the certificate on the first access (a few seconds). Log in with admin and your password from the compose.yaml. Thanks to provisioning, the Prometheus data source is already connected – you find it under Connections → Data sources:

Now the dashboards. Instead of building panels ourselves, we import two proven ones from the Grafana community. Go to Dashboards → New → Import, enter the ID and click Load:

Import these two:

• 1860 – “Node Exporter Full”: the comprehensive host dashboard.
• 19792 – “cAdvisor Dashboard”: metrics per container.

On import, select the Prometheus data source each time. After that, “Node Exporter Full” shows your host in real time – CPU usage, used RAM, disk, network, uptime:

The cAdvisor dashboard breaks the same load down to individual containers – here you immediately see which service draws how much CPU and RAM:

Step 7: Read the most important metrics correctly

A dashboard full of curves is of little use if you don’t know what to watch for. These five values in the “Node Exporter Full” dashboard tell you almost everything about the health of your server:

• CPU Busy. Short spikes are normal. It gets critical when the usage stays permanently high – then the server is the bottleneck.
• Sys Load. The load should on average be below the number of your CPU cores (in the test: 4 cores → load permanently above 4 is a warning sign of overload).
• RAM Used. Important: Linux uses free memory as a file cache – so “used” isn’t the same as “tight”. Only when little stays free besides the cache and SWAP Used rises does the server get sluggish. It’s exactly this creeping rise you want to see early.
• Root FS Used. The classic among server outages is the full disk. The trend shows you the fill rate – so you recognize days in advance when it’s getting tight.
• Network Traffic. Unusual spikes even though nothing is running can indicate a backup, an update or – in the bad case – unwanted traffic.

In the cAdvisor dashboard the most exciting question is: Which container draws the load? If your server suddenly gets slow, you see here at a glance whether it’s due to a single app – and don’t have to guess. This turns “something is slow” into a targeted “the photo import in container X is eating the CPU right now”.

When things go wrong

Maintenance & backups

• What you must back up. Important is the grafana_data volume: it contains your users, settings and self-built dashboards. Back it up encrypted and off-site with Restic. The Prometheus metrics (prom_data) are pure measurements – a loss is bearable, a backup optional.
• Updates. The image tags are pinned (prometheus:v3.13.1, grafana:13.1.0 …). To update, raise the tags, then docker compose pull && docker compose up -d. Read the release notes first – Grafana in particular occasionally changes defaults between major versions. You get cAdvisor from gcr.io; there v0.55.1 is currently the latest available image version.
• Security. Grafana is publicly accessible – assign a strong admin password and leave GF_USERS_ALLOW_SIGN_UP at false. Prometheus and cAdvisor stay internal; don’t expose them “just quickly” for debugging, they have no authentication.
• The next step: alerts. A dashboard only helps if you look at it. Grafana can trigger alerts itself at thresholds (RAM > 90%, disk almost full) and report e.g. via push. This turns the pretty dashboard into an early-warning system – a good connection to your existing Uptime Kuma.
• Honest about the effort: the stack runs largely on its own after setup. Occasionally plan a look at the retention time and storage usage, and bump the versions roughly quarterly.

What are we building?

By the end, Traefik v3 runs as the central entry point on your server. It listens on ports 80/443, detects new containers automatically via Docker labels, redirects HTTP to HTTPS automatically, and obtains a valid Let’s Encrypt certificate for every domain. As the first app, we hang whoami behind the proxy – a tiny test service that shows routing and TLS are working. A secured dashboard comes on top.

The pattern from this tutorial – a shared proxy network plus a few labels – repeats afterwards in every app recipe.

A request always passes through the same four stations in Traefik – this vocabulary helps you debug:

1. Entrypoint – the port on which the request arrives (web = 80, websecure = 443).
2. Router – decides based on a rule (usually Host(...)) whether this request belongs to an app.
3. Middleware (optional) – modifies the request along the way (e.g. HTTPS redirect, basic auth, security headers).
4. Service – the container that ultimately responds.

Debugging mnemonic: “Entrypoint → Router → Middleware → Service”. If a request ends up nowhere, it’s almost always the router (wrong domain) or the network (service not reachable) at fault.

Prerequisites

• Docker + Compose installed and the Compose basics understood
• A domain connected to the server: YOUR_DOMAIN and the subdomains must resolve to the server via A/AAAA
• Ports 80 and 443 are reachable from the internet – Let’s Encrypt uses them to verify that you own the domain. Open firewalls accordingly (see setting up a firewall with UFW).

Step by step

Step 1: Create the shared proxy network

Traefik and all apps must share a Docker network so Traefik can reach the containers. We create it once and explicitly, so later stacks can simply dock onto it:

docker network create proxy

Check:

docker network ls | grep proxy

c442da869c47   proxy     bridge    local

This network is independent of the individual Compose projects – that’s why we later include it as external.

Step 2: Create the Traefik project

Create a dedicated folder for Traefik and, inside it, the file where the certificates are stored:

mkdir -p ~/traefik && cd ~/traefik
touch acme.json
chmod 600 acme.json

Step 3: The Traefik compose.yaml

Now the central configuration. It’s long, but every line has a purpose – the explanation follows right below:

services:
  traefik:
    image: traefik:v3.7
    command:
      # Dashboard (secured in step 7)
      - "--api.dashboard=true"
      # Docker as source; only containers with traefik.enable=true
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      # Entrypoints: 80 (HTTP) and 443 (HTTPS)
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      # Redirect everything from HTTP to HTTPS automatically
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      # Let's Encrypt resolver named "le" via HTTP challenge
      - "--certificatesresolvers.le.acme.email=YOUR_EMAIL"
      - "--certificatesresolvers.le.acme.storage=/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./acme.json:/acme.json
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

The most important blocks:

• providers.docker + exposedbydefault=false: Traefik watches the Docker socket, but only containers that explicitly carry traefik.enable=true. No service is accidentally made public.
• providers.docker.network=proxy: tells Traefik which network it uses to reach the containers – important when containers are attached to several networks.
• entrypoints web/websecure: ports 80 and 443. The two redirections lines send every HTTP call automatically to HTTPS.
• certificatesresolvers.le: the Let’s Encrypt resolver. Via the HTTP challenge, Traefik proves to Let’s Encrypt that the domain points to this server and stores the certificate in acme.json. For this, port 80 must stay reachable from outside – even if your app only runs over HTTPS, because the challenge comes over HTTP. Let’s Encrypt uses the acme.email solely for warnings about expiring certificates; enter a real address.
• The Docker socket is mounted read-only (:ro) – Traefik must read it, but not write to it.

Start Traefik:

docker compose up -d
docker compose logs -f traefik

The logs must show no ERR about ACME or the provider. Ctrl+C only ends the following, not the container.

Step 4: The first app behind Traefik (whoami)

whoami is a tiny service that returns the received request – perfect for testing. Own folder, own compose.yaml:

mkdir -p ~/whoami && cd ~/whoami

services:
  whoami:
    image: traefik/whoami:v1.11
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.YOUR_DOMAIN`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls.certresolver=le"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

These are the four labels you’ll need again and again from now on:

• traefik.enable=true – only then does Traefik touch the container.
• ...routers.whoami.rule=Host(...) – at which domain this container responds. whoami is a freely chosen router name (unique per container).
• ...entrypoints=websecure – reachable over HTTPS (443).
• ...tls.certresolver=le – fetch the certificate via the resolver le defined in step 3.

Important: the service has no ports: – it’s only reachable via Traefik, not directly from outside. And it’s on the proxy network, otherwise Traefik won’t find it.

Create the DNS record whoami.YOUR_DOMAIN beforehand (A/AAAA to the server IP, as in the DNS tutorial), then:

docker compose up -d

Open https://whoami.YOUR_DOMAIN in the browser. On the first call, certificate issuance takes a few seconds; after that you see a valid padlock icon and a text output like:

Hostname: bfa4b8dee3d0
IP: 127.0.0.1
IP: 172.19.0.3
RemoteAddr: 172.19.0.2:49734
GET / HTTP/1.1
Host: whoami.YOUR_DOMAIN

The Host: line confirms that Traefik routed correctly to this container based on the domain. Exactly this behavior – a request for whoami.YOUR_DOMAIN lands at the whoami container, an unknown domain gets a 404 – is the heart of the reverse proxy.

Check which CA issued the certificate. This separates “HTTPS is running” from “I only see Traefik’s emergency certificate”:

echo | openssl s_client -connect whoami.YOUR_DOMAIN:443 -servername whoami.YOUR_DOMAIN 2>/dev/null | openssl x509 -noout -issuer

As long as you use the staging server (as recommended in step 3), a test issuer appears there – the browser still shows the certificate as insecure:

issuer=C=US, O=Let's Encrypt, CN=(STAGING) Ersatz Emmer YR2

If TRAEFIK DEFAULT CERT appears here, the resolver fetched no certificate – then go to troubleshooting below. If a Let’s Encrypt issuer is there, the whole chain works.

Step 5: Switch to the real certificate

Once staging runs cleanly, you fetch the real certificate that’s valid in the browser. Remove the caserver line from the traefik service (step 3), empty the staging certificates and restart Traefik:

> acme.json                 # discards the staging certificates (chmod 600 stays)
docker compose up -d

On the next call, Traefik fetches a fresh production certificate. In the issuer line from above, the (STAGING) then disappears, and the browser shows a valid padlock.

Step 6: The HTTP-to-HTTPS redirect

You already enabled this globally in step 3 (the two redirections lines). Test:

curl -sI http://whoami.YOUR_DOMAIN | grep -iE 'HTTP/|location'

HTTP/1.1 308 Permanent Redirect
location: https://whoami.YOUR_DOMAIN/

So every unencrypted call is automatically redirected to HTTPS – you no longer have to think about it in any app.

Step 7: Secure the dashboard

Traefik comes with a dashboard that shows which routers and services are active. Never put it unprotected on the internet. We secure it with basic auth and hang it on a dedicated subdomain. First create a user:

sudo apt install -y apache2-utils
htpasswd -nbB admin YOUR_PASSWORD

The output (admin:$2y$05$...) goes into the labels. In the compose.yaml, double every $ ($$), otherwise Compose interprets it as a variable. Add to the traefik service:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`traefik.YOUR_DOMAIN`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.tls.certresolver=le"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
      - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$2y$$05$$..."

After docker compose up -d you reach the dashboard at https://traefik.YOUR_DOMAIN – after a password prompt.

In the dashboard you see, under HTTP → Routers, every detected router (with its Host(...) rule), under Services the containers behind them, and under Middlewares your building blocks like dashboard-auth. A router turns green when rule, service and – for websecure – the certificate are correct; red means something is missing (usually network or host rule). That makes the dashboard your first look at “why isn’t my app responding?”.

Under HTTP Routers you see each router individually – with its Host(...) rule, the entrypoint, the TLS status (padlock) and the provider docker. This is how you check at a glance whether your labels were detected correctly:

Step 8: Security headers as a reusable middleware

A middleware hooks in between router and service and modifies the request or response. A set of security headers belongs on every public app – defined once, attached everywhere. Define the middleware on any container (common: on Traefik itself) via labels:

      - "traefik.http.middlewares.sec-headers.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.sec-headers.headers.stsIncludeSubdomains=true"
      - "traefik.http.middlewares.sec-headers.headers.frameDeny=true"
      - "traefik.http.middlewares.sec-headers.headers.contentTypeNosniff=true"
      - "traefik.http.middlewares.sec-headers.headers.browserXssFilter=true"

What the most important ones do:

• stsSeconds (HSTS) – the browser will address the domain only over HTTPS from now on. One year (31536000) is the usual value.
• frameDeny – forbids embedding in foreign <iframe>s (clickjacking protection).
• contentTypeNosniff – the browser doesn’t guess the content type but takes the one delivered – rules out a whole class of attacks.

Attach it to an app via a label (adjust the router name):

      - "traefik.http.routers.whoami.middlewares=sec-headers"

Multiple middlewares are given comma-separated (sec-headers,dashboard-auth) and are run in that order. This is how you gradually build a toolbox (auth, rate limiting, IP whitelist) that every app can reuse.

If a header set should apply to all apps, you don’t attach the middleware to each router individually, but globally to the entrypoint – one line in Traefik’s command block:

      - "--entrypoints.websecure.http.middlewares=sec-headers@docker"

The suffix @docker tells Traefik the middleware comes from the Docker provider (where you defined it via label).

Step 9: The recipe for every further app

From now on, every app is the same pattern – you never have to touch Traefik again. A new application gets its own folder with a compose.yaml, is on the proxy network, and carries exactly these labels (adjust router name and domain; for a port ≠ 80 add the loadbalancer label as well):

services:
  myapp:
    image: YOUR_IMAGE:TAG
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myapp.rule=Host(`app.YOUR_DOMAIN`)"
      - "traefik.http.routers.myapp.entrypoints=websecure"
      - "traefik.http.routers.myapp.tls.certresolver=le"
      # only needed if the app does NOT listen on port 80:
      - "traefik.http.services.myapp.loadbalancer.server.port=YOUR_PORT"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

docker compose up -d, set the DNS record to the server IP, done – domain and HTTPS are created automatically. This is exactly how the first real app (Uptime Kuma) hangs behind the proxy.

When things go wrong

Maintenance & backups

• You must back up acme.json and all compose.yaml files. With those, Traefik is restored within minutes after a crash – the certificates don’t need to be reissued (which also spares the rate limit). We build an encrypted off-site backup of these files in the Restic tutorial.
• Certificates renew automatically. Let’s Encrypt certificates expire after 90 days; Traefik renews them in good time on its own – no cron job needed. You can check the expiry date any time by appending -dates instead of -issuer to the openssl command from step 4 (shows notBefore/notAfter).
• Maintain the Traefik version. The fixed tag (traefik:v3.7) means you apply updates deliberately. Before jumping to a new minor/major version, read the release notes – Traefik changed the label syntax between v2 and v3, for example.
• Keep an eye on the dashboard. A quick login shows whether all routers are “green” – the fastest check of whether everything holds after a deploy.

From now on the path is the same for every app: container onto the proxy network, four labels on it, set the DNS record – and a publicly reachable service with HTTPS is ready. As the first real app, in the next recipe we hang Uptime Kuma behind Traefik and use it to monitor all subsequent services.

What are we building?

We build a small stack step by step and, along the way, get to know the five building blocks that make up practically every compose.yaml: services (the containers), ports (reachability from outside), volumes (persistent data), networks (containers talking to each other) and environment variables (configuration). By the end you’ll understand why your data survives a down command – and when it doesn’t.

Tested with Docker Compose v5.3 (the docker compose plugin without a hyphen – not the old docker-compose v1 with a hyphen).

Prerequisites

• A hardened server with Docker installed and the Compose plugin
• The user is in the docker group (then you don’t need sudo before docker)

Step by step

Step 1: The first compose.yaml

A compose.yaml describes declaratively which containers should run – you say what you want, not how. Create a project folder; the folder name later becomes the prefix of all containers:

mkdir -p ~/compose-demo/site && cd ~/compose-demo

Create a small HTML page that we’ll serve in a moment:

echo '<h1>Hallo aus der Serverküche</h1>' > site/index.html

And now the central file compose.yaml:

services:
  web:
    image: nginx:1.31
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    restart: unless-stopped

Line by line:

• services: – the top level. Every entry below it is a container.
• web: – a freely chosen service name. Remember it, it later also becomes the hostname on the internal network (step 3).
• image: nginx:1.31 – the container image with a fixed tag. Never use latest: latest changes under you and makes errors unreproducible.
• ports: - "8080:80" – format HOST:CONTAINER. Port 80 in the container is mapped to 8080 on the server. The server is always on the left.
• volumes: - ./site:...:ro – the local site folder is mounted into the web root, :ro = read-only. More on this in step 2.
• restart: unless-stopped – the container restarts automatically after a reboot or crash, unless you stopped it yourself. The sensible default for server services. The alternatives: no (never automatically – the default), always (restarts even after a manual stop, rarely wanted) and on-failure (only after a crash with an error code). For the vast majority of services, unless-stopped is exactly right.

Start the stack:

docker compose up -d

-d means detached (in the background). The first time, Docker downloads the image; after that you see at the end:

 Network compose-demo_default  Created
 Container compose-demo-web-1  Started

Check the status:

docker compose ps

NAME                 IMAGE        COMMAND                  SERVICE   CREATED          STATUS          PORTS
compose-demo-web-1   nginx:1.31   "/docker-entrypoint.…"   web       10 seconds ago   Up 9 seconds    0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

The container is called compose-demo-web-1 – project folder + service + number. Test:

curl localhost:8080

<h1>Hallo aus der Serverküche</h1>

Works. You see a service’s logs with docker compose logs web (or -f to follow).

Step 2: Volumes – where your data really lives

Containers are ephemeral: if you delete a container, everything written inside the container is gone. So that data survives this, there are two kinds of volumes:

• Bind mount (./site:/usr/share/nginx/html): a folder from your server is mounted into the container. Ideal for config files you edit yourself.
• Named volume (webdata:/var/lib/...): storage managed by Docker. Ideal for database data – performant and cleanly separated from the host.

In step 1 we used a bind mount. For database-like services it looks like this – change compose.yaml as a test:

services:
  web:
    image: nginx:1.31
    volumes:
      - webdata:/usr/share/nginx/html

volumes:
  webdata:

Named volumes must additionally be declared at the top level under volumes:. After docker compose up -d the volume appears:

docker volume ls

DRIVER    VOLUME NAME
local     compose-demo_webdata

Now comes the crucial point:

docker compose down
docker volume ls

 Container compose-demo-web-1  Removed
 Network compose-demo_default  Removed
DRIVER    VOLUME NAME
local     compose-demo_webdata

docker compose down removes the container and network – the volume stays. This is exactly why your database contents survive an update. Remember the counterpart:

Step 3: Networks – containers talking to each other

Compose automatically creates one network per project (seen above: compose-demo_default). All services in it reach each other via their service name as the hostname – no fiddling with IPs. That’s the reason why, in app tutorials, the application simply reaches its database under db.

As proof, a second service that talks to the first:

services:
  web:
    image: nginx:1.31
    volumes:
      - ./site:/usr/share/nginx/html:ro

  ping:
    image: curlimages/curl:8.21.0
    depends_on:
      - web
    command: ["curl", "-s", "http://web"]

• depends_on: - web – Compose starts web before ping. (Careful: this only waits for the start, not for “fully booted” – that’s what healthchecks are for, step 4.)
• command: – overrides the image’s default command. ping calls http://web – web is the service name from the same file.

Run only the ping service once:

docker compose run --rm ping

<h1>Hallo aus der Serverküche</h1>

ping reached web purely by name – without any port mapping. Remember: you only need ports: to make a service reachable from outside (the internet). Containers talk to each other over the internal network – that’s why we later deliberately run databases without ports:.

So far, every network lives inside a Compose project. But sometimes containers from different projects should talk to each other – the classic example is a reverse proxy sitting in front of many independent app stacks. For that there’s the external network: one you create once by hand and that several Compose projects then share:

docker network create proxy

In the compose.yaml you then don’t create it again, but reference the already existing network with external: true:

services:
  web:
    image: nginx:1.31
    networks:
      - proxy

networks:
  proxy:
    external: true

external: true tells Compose: “This network already exists – do not create it and do not delete it on down.” If the network is missing, up aborts with network proxy declared as external, but could not be found – then you forgot the docker network create. This very pattern – a shared proxy network plus external: true – is the basis of the Traefik tutorial, with which every app later gets its domain and its HTTPS.

Step 4: Configuration – environment variables, .env and healthchecks

Almost every application is configured via environment variables. Two ways:

services:
  app:
    image: beispiel/app:1.0
    environment:
      - TZ=Europe/Berlin
      - APP_PORT=3000

Secrets (passwords, tokens) do not belong in the compose.yaml, but in a .env file in the same folder. Compose reads it automatically:

echo "DB_PASSWORD=EIN_LANGES_ZUFALLSPASSWORT" > .env

services:
  db:
    image: postgres:18
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}

This is how you check whether Compose understands your file and inserts the .env values correctly – without starting anything:

docker compose config

config resolves all variables and prints the finished, normalized configuration:

name: compose-demo
services:
  db:
    environment:
      POSTGRES_PASSWORD: EIN_LANGES_ZUFALLSPASSWORT
    image: postgres:18
    networks:
      default: null

If your actual value appears there instead of ${DB_PASSWORD}, the .env is working. If you only need a quick syntax check without the whole output, use docker compose config --quiet – if nothing comes back (exit code 0), the file is valid. That’s also your first move for YAML errors (see below).

A healthcheck tells Docker when a service is really ready – the basis for dependent services only starting then:

services:
  db:
    image: postgres:18
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: beispiel/app:1.0
    depends_on:
      db:
        condition: service_healthy

With condition: service_healthy, app only starts once the healthcheck of db is green – the most common “why won’t my app connect to the database?” disappears with it. The four healthcheck fields mean: test is the command that runs in the container (exit code 0 = healthy), interval the spacing between checks, timeout how long a check may take, and retries how many consecutive failures are needed before the container counts as unhealthy. The current state is shown by the STATUS column of docker compose ps as (healthy) or (unhealthy).

Step 5: The operations toolbox

You need these commands daily – always run them in the project folder:

docker compose up -d        # start / apply changes
docker compose ps           # status of the services
docker compose logs -f web  # follow logs live (Ctrl+C only ends the viewing)
docker compose exec web sh  # shell in the running container
docker compose restart web  # restart a single service
docker compose stop         # halt without removing container/network
docker compose pull         # fetch new image versions
docker compose down         # stop and remove the stack (volumes stay)

Almost all commands can be restricted to one service by appending its name (docker compose logs -f web, docker compose restart web) – without a name they apply to the whole stack. The difference between stop and down: stop only halts the containers (start continues), down removes them along with the network (the named volumes stay in both cases).

An update almost always follows the same pattern: bump the tag in the compose.yaml → docker compose pull → docker compose up -d. Compose only replaces the containers whose image has changed.

Step 6: All together – a realistic app stack

This is the pattern you’ll encounter again and again in the app tutorials: an application plus its database. This file bundles everything from steps 1–4 – read it once in full, and you’ll have understood 90% of every later compose.yaml:

services:
  app:
    image: beispiel/app:1.4          # fixed version, no latest
    ports:
      - "8080:3000"                  # only the app is reachable from outside
    environment:
      - TZ=Europe/Berlin
      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/app
    volumes:
      - appdata:/data                # persistent app data (named volume)
    depends_on:
      db:
        condition: service_healthy   # starts only once db is ready
    restart: unless-stopped

  db:
    image: postgres:18
    environment:
      - POSTGRES_USER=app
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=app
    volumes:
      - dbdata:/var/lib/postgresql/data   # the actual database files
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    # no ports: – the database is reachable ONLY internally via the name "db"

volumes:
  appdata:
  dbdata:

Three design decisions worth remembering:

1. Only app has ports:. The database needs no open host port – the app reaches it internally via the hostname db (the DATABASE_URL points exactly there). A port that isn’t published is a port nobody from the internet can attack.
2. Two separate named volumes. App data and database files live cleanly separated – that makes later backups and restores traceable.
3. Password only as ${DB_PASSWORD}. The actual value is in the .env, not in this file. The same compose.yaml can thus be shared safely.

This very skeleton – app facing outward, database internal only, data in named volumes, secrets in the .env – repeats in Nextcloud, Vaultwarden, Paperless and most other recipes.

When things go wrong

Maintenance & backups

• Maintain image tags: Fixed tags (nginx:1.31) mean you apply updates deliberately by bumping the tag. That’s intended – this way you decide when an update comes, instead of being surprised. Expect a monthly look at your services’ release notes.
• What belongs in the backup? Not the containers – they can be rebuilt from the compose.yaml at any time. What you must back up are the named volumes (or bind-mount folders), the compose.yaml and the .env. We build a well-thought-out off-site backup of this data with encrypted Restic backups.
• Cleanup: docker compose down when tearing down a stack; you remove unused images with docker image prune. Named volumes are never deleted automatically – that’s by design.

What are we building?

By the end, the current Docker Engine with the Compose plugin runs on your Debian 13, installed from the official Docker repository. That has two advantages over the Debian package docker.io: more current versions with timely security updates, and the official docker compose that all Compose recipes here build on.

Prerequisites

• A hardened server with a sudo user

Step by step

Step 1: Set up the repository key

First, install the tools needed to verify the Docker repository:

sudo apt update
sudo apt install -y ca-certificates curl

Then create the keyring directory and download Docker’s GPG key – apt uses it later to check that the packages really come from Docker:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc

Step 2: Add the Docker package source

Add the Docker repository to your package sources. The command detects the architecture and Debian version automatically, so you can copy it unchanged:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Step 3: Install Docker

Refresh the package lists (now including the Docker repository) and install the Engine together with the Compose plugin:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Check that the service is running:

sudo systemctl status docker

You should see active (running). A quick smoke test:

sudo docker run --rm hello-world

The output Hello from Docker! confirms that the installation works.

Step 4: Use Docker without sudo

Add your user to the docker group so you don’t have to prefix every command with sudo:

sudo usermod -aG docker $USER

After that, docker ps works without sudo and shows a (still empty) container list.

When things go wrong

Maintenance & backups

• Updates: Docker updates along with the normal sudo apt update && sudo apt upgrade – one reason we use the official repository. When the Engine is updated, running containers restart briefly (or stop until you start them again) – plan for that.
• Cleanup: Unused images and build leftovers pile up quickly. docker system df shows the usage, docker system prune cleans up (careful: it also removes stopped containers).
• Backups: The actual data of your applications will later live in volumes or bind mounts – we build the backup strategy for that with encrypted Restic backups and in the individual application tutorials.