What are we building?

By the end, a CrowdSec agent runs alongside your Traefik, reading along with the access logs, detecting suspicious behavior based on scenarios (port scans, path probing, known CVE exploitation, login brute force) and putting attacker IPs on a block list. A bouncer – here as a Traefik plugin – enforces these decisions: a banned IP only gets 403 Forbidden at every one of your apps. Tested with CrowdSec v1.7.8, the Traefik bouncer plugin v1.6.0 and Traefik v3.7.

This is how the parts interlock:

• Agent + Local API (LAPI): reads the logs, evaluates them against the scenarios and manages the active bans (“decisions”). That’s the container we set up.
• Bouncer: asks the LAPI on every request “is this IP banned?” and blocks if yes. The Traefik bouncer runs as a plugin directly in the reverse proxy – no additional container.
• Community blocklist: CrowdSec reports (anonymized) detected attacks to the central network and gets a blocklist fed by all users back in return. IPs that were already flagged as malicious elsewhere are then banned at your place from the start. That’s the “collaborative” in the title.

Prerequisites

• A running reverse proxy with Traefik (the proxy network and the resolver le come from there) with at least one app behind it.
• Fail2ban for SSH protection – CrowdSec handles the HTTP layer here, not SSH.
• Basic knowledge of Docker Compose and a hardened server with an active firewall.

Step by step

Step 1: Enable Traefik’s access logs

CrowdSec can only detect what it sees – and it sees attacks via Traefik’s access logs. They’re off by default. Open the compose.yaml of your Traefik (from the Traefik tutorial, folder ~/traefik) and add these three lines to the command block:

      - "--accesslog=true"
      - "--accesslog.filepath=/var/log/traefik/access.log"
      - "--accesslog.format=json"

The JSON format is important – the CrowdSec parsers expect it that way. So that both Traefik (writing) and CrowdSec (reading) can reach the same file, you put it on a fixed host path. Add to Traefik’s volumes block:

      - /var/log/traefik:/var/log/traefik

Create the directory on the host and restart Traefik:

sudo mkdir -p /var/log/traefik
cd ~/traefik && docker compose up -d

Call one of your apps once and check that lines arrive:

tail -n 2 /var/log/traefik/access.log

You should see JSON lines with "ClientHost", "RequestPath" and "DownstreamStatus". If the file stays empty, the path in the volume is wrong, or simply no request has come in yet.

Step 2: Set up the CrowdSec container

CrowdSec gets its own folder. First generate a bouncer key – the Traefik bouncer later authenticates with it at the LAPI:

mkdir -p ~/crowdsec && cd ~/crowdsec
openssl rand -hex 32

Copy the output; it’s used in two places shortly. Create the acquisition – it tells CrowdSec which file with which log type to read:

# ~/crowdsec/acquis.yaml
filenames:
  - /var/log/traefik/access.log
labels:
  type: traefik

Now the compose.yaml. Replace YOUR_BOUNCER_KEY with the generated key:

services:
  crowdsec:
    image: crowdsecurity/crowdsec:v1.7.8
    container_name: crowdsec
    environment:
      COLLECTIONS: "crowdsecurity/traefik"
      BOUNCER_KEY_TRAEFIK: "YOUR_BOUNCER_KEY"
      GID: "1000"
    volumes:
      - ./acquis.yaml:/etc/crowdsec/acquis.d/traefik.yaml:ro
      - /var/log/traefik:/var/log/traefik:ro
      - crowdsec-db:/var/lib/crowdsec/data/
      - crowdsec-config:/etc/crowdsec/
    networks: [proxy]
    restart: unless-stopped

volumes:
  crowdsec-db:
  crowdsec-config:

networks:
  proxy:
    external: true

What matters here:

• COLLECTIONS: crowdsecurity/traefik installs the matching collection of parsers and scenarios for Traefik logs on the first start (including the HTTP base scenarios).
• BOUNCER_KEY_TRAEFIK registers a bouncer named TRAEFIK with your key right at startup – that saves the detour via cscli bouncers add.
• GID: "1000" runs the CrowdSec process under this group. 1000 is the usual default for the first user; if Traefik runs as root, the access.log is usually world-readable and the GID doesn’t matter anyway. If it’s set more tightly, check with ls -l /var/log/traefik/access.log and enter the GID of the file’s group.
• The log is mounted read-only (:ro). CrowdSec is on the proxy network so the Traefik bouncer can reach the LAPI at crowdsec:8080 later.

Start the container and check that everything takes effect:

docker compose up -d
docker exec crowdsec cscli collections list

The Traefik collection and the HTTP scenarios should appear as enabled:

 crowdsecurity/base-http-scenarios    ✔️  enabled
 crowdsecurity/http-cve               ✔️  enabled
 crowdsecurity/traefik                ✔️  enabled

Check that the community blocklist is active – it costs nothing and is half the benefit of CrowdSec:

docker exec crowdsec cscli capi status

You can successfully interact with Central API (CAPI)
Sharing signals is enabled
Pulling community blocklist is enabled
Pulling blocklists from the console is enabled

Pulling community blocklist is enabled confirms that you receive the collective block list of the CrowdSec community – attackers that stood out elsewhere are already banned at your place before they even try.

Step 3: Add the Traefik bouncer

Now the part that enforces the bans. The bouncer is a Traefik plugin and consists of two additions to your Traefik: load the plugin and define a middleware that acts on all apps.

Load the plugin by adding to the command block of ~/traefik/compose.yaml:

      - "--experimental.plugins.bouncer.modulename=github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
      - "--experimental.plugins.bouncer.version=v1.6.0"
      - "--entrypoints.websecure.http.middlewares=crowdsec@file"

The last line attaches the bouncer middleware globally to the websecure entrypoint – so every HTTPS request to every app runs through the bouncer, without you touching each app individually. You define the middleware itself via the file provider.

Create the middleware (path adapted to your existing file provider):

# ~/traefik/dynamic/crowdsec.yaml
http:
  middlewares:
    crowdsec:
      plugin:
        bouncer:
          enabled: true
          crowdsecMode: stream
          crowdsecLapiScheme: http
          crowdsecLapiHost: crowdsec:8080
          crowdsecLapiKey: "YOUR_BOUNCER_KEY"

crowdsecLapiKey is the same key as in step 2 – the bouncer identifies itself with it at the LAPI. With crowdsecMode: stream the bouncer pulls the block list completely in advance at a fixed interval and answers every request from the local cache – the mode recommended by the plugin, because it doesn’t load the LAPI on every request.

Make sure Traefik also sees the directory. If your existing file provider already uses a mounted dynamic directory, the new file is in it anyway – then there’s nothing to do here. If you create the directory anew, add it to Traefik’s volumes block:

      - ./dynamic:/etc/traefik/dynamic:ro

Restart Traefik so it downloads the plugin and loads the middleware:

cd ~/traefik && docker compose up -d
docker compose logs -f traefik

The log must show no ERR about the plugin or the middleware (Traefik v3 logs only errors at the default level – a quiet output is the good sign). Check from the CrowdSec side that the bouncer has connected:

docker exec crowdsec cscli bouncers list

 Name     IP Address  Valid  Last API pull         Type
 TRAEFIK  172.19.0.2  ✔️      2026-07-23T10:49:58Z  Crowdsec-Bouncer-Traefik-Plugin

A set Last API pull proves: the plugin talks to the LAPI.

Step 4: Arm it and test the ban

Call one of your apps – it should respond perfectly normally:

curl -s -o /dev/null -w "%{http_code}\n" https://YOUR_APP.YOUR_DOMAIN/

200

Now you test-ban an IP by hand and see whether the bouncer locks it out. Take your own public IP (curl -s https://ifconfig.me):

docker exec crowdsec cscli decisions add --ip YOUR_TEST_IP --duration 5m --reason "test"

After the wait, the banned IP only gets:

curl -s -o /dev/null -w "%{http_code}\n" https://YOUR_APP.YOUR_DOMAIN/

403

Lift the test ban again:

docker exec crowdsec cscli decisions delete --ip YOUR_TEST_IP

Step 5: Let it detect real attacks

The actual point: CrowdSec bans on its own, without you writing rules. As soon as a scanner probes your domain for paths (many 404 in a short time), the scenario crowdsecurity/http-probing kicks in. This is what a real, automatically detected ban looks like:

docker exec crowdsec cscli alerts list

 ID  value              reason                       country  as                      decisions
 4   Ip:109.250.21.197  crowdsecurity/http-probing   DE       8881 1&1 Versatel GmbH  ban:1

docker exec crowdsec cscli decisions list

 Source    Scope:Value        Reason                       Action  Country  AS
 crowdsec  Ip:109.250.21.197  crowdsecurity/http-probing   ban     DE       8881 1&1 Versatel GmbH

CrowdSec automatically enriches the ban with country and provider (AS). Besides the self-detected attacks, bans with the source lists:crowdsecurity/... appear here over time – that’s the community blocklist: IPs that already stood out negatively worldwide, you block before they hit you the first time.

Whoever prefers to see the bans graphically instead of in cscli tables enrolls the instance for free in the CrowdSec console (the enroll command is in “Maintenance & backups”). There the same decisions appear presented nicely:

The HTTP scenarios installed with the Traefik collection cover what real scanners try all day: probing non-existent paths (http-probing), searching for sensitive files and backdoors, path traversal and SQL injection/XSS probes, suspicious user agents of known scanners, as well as the exploitation of known CVEs (from the collection crowdsecurity/http-cve). Which scenarios are active is shown by docker exec crowdsec cscli scenarios list.

Whether CrowdSec reads your logs at all is shown by the metrics overview:

docker exec crowdsec cscli metrics

| Source                           | Lines read | Lines parsed |
| file:/var/log/traefik/access.log | 54         | 54           |

If it says Lines read: 0, no log is arriving – then back to step 1.

Step 6: Don’t lock yourself out

A false alarm against your own maintenance IP is annoying. Enter your fixed IP as trusted in the middleware – the bouncer then doesn’t even check it. Add to ~/traefik/dynamic/crowdsec.yaml under bouncer::

          clientTrustedIPs:
            - "YOUR_FIXED_IP/32"

If you did lock yourself out, one command lifts the ban immediately – and in an emergency you can always reach the server via the VNC console in the SCP:

docker exec crowdsec cscli decisions delete --ip YOUR_IP   # one IP
docker exec crowdsec cscli decisions delete --all           # all bans

When things go wrong

Maintenance & backups

• Keep scenarios current. CrowdSec’s strength is maintained detection rules – pull them regularly: docker exec crowdsec cscli hub update && docker exec crowdsec cscli hub upgrade. You bump the image (crowdsecurity/crowdsec) and the plugin version (v1.6.0) deliberately; read the release notes on major versions. CrowdSec develops briskly – a good candidate for regular version checks.

• Rotate the access log. Traefik’s /var/log/traefik/access.log otherwise grows unbounded. Set up a logrotate rule – mandatorily with copytruncate: this variant copies the file away and empties the original in place, instead of renaming it and creating a new one. Only this way does CrowdSec’s tail keep the file access (with rename/create it would lose the handle and read nothing anymore). Create /etc/logrotate.d/traefik:

  Ausgabe

  /var/log/traefik/access.log {
      daily
      rotate 7
      compress
      missingok
      notifempty
      copytruncate
  }

  After the truncate, CrowdSec reads on perfectly normally from the file that’s growing again – a restart of the container isn’t needed.

• fail2ban stays. Don’t remove fail2ban – it continues to protect your SSH access at the host level, while CrowdSec covers the web apps. Two tools, two responsibilities.

• Backups. What you must back up is above all your configuration: the folder ~/crowdsec (compose.yaml, acquis.yaml) and ~/traefik/dynamic/crowdsec.yaml with the bouncer key. Include them in your Restic backup. The block lists themselves are ephemeral and rebuild on their own – no backup needed.

• Optional: the CrowdSec dashboard. Whoever wants to see the attacks graphically enrolls the instance for free in the CrowdSec console (docker exec crowdsec cscli console enroll YOUR_ENROLL_KEY). The community blocklist runs without enrollment too.

• Integrate it into your monitoring. cscli metrics gives you numbers for the terminal; for continuous observation, CrowdSec provides a Prometheus endpoint (enable it in the config under prometheus:) that you can hang on your Grafana stack. Then you see bans by origin and scenario at a glance:

  

• Honest about the effort: After setup, CrowdSec runs largely on its own. Plan a hub upgrade and a look at cscli metrics and the container version once a month.

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, Jellyfin 10.11 runs as a container on your server, reachable at https://jellyfin.YOUR_DOMAIN with valid HTTPS. Jellyfin is a completely free media server (no cloud, no telemetry, no subscription): you store your files, Jellyfin automatically pulls covers, descriptions and metadata and streams everything to the browser, phone, smart TV or the Jellyfin app.

The real challenge with a media server is storage space – a movie collection quickly bursts the small system SSD of a VPS. That’s why we mount netcup’s Local Block Storage: an additional, local disk that appears in the server like a normal drive and on which the library lives.

Prerequisites

• A running Traefik reverse proxy with the proxy network and the resolver le – see reverse proxy with Traefik.
• A subdomain jellyfin.YOUR_DOMAIN with a DNS record to your server IP – see connecting a domain to your server.
• Dedicated CPU cores are clearly at an advantage for smooth streaming (transcoding). On a shared VPS it works too for Direct Play, but gets tight quickly on re-encoding.
• Optional but recommended: booked netcup Local Block Storage for the library (step 2). Without it, you simply put the media in a folder on the system disk – until the space runs out.
• A few of your own media files (movies/series/music) that you’re allowed to host.

Whether your setup really needs dedicated cores is shown by the server calculator – with transcoding the answer is usually yes.

Step by step

Step 1: Create the DNS record

Create jellyfin.YOUR_DOMAIN (A/AAAA to your server IP) and check that it resolves:

dig +short jellyfin.YOUR_DOMAIN

Your server IP must come back – otherwise Traefik won’t fetch a certificate later.

Step 2: Mount netcup Local Block Storage

The Local Block Storage is additional storage you book to your server in the netcup customer account. Unlike the network-attached Storage Space of other providers (which is connected via NFS and is slower), it appears in the server as a completely normal local disk – ideal for a library because it’s fast and freely partitionable.

First look at which disks the server knows:

sudo fdisk -l

The system disk is typically /dev/sda (or /dev/vda). The new block storage appears as an additional device, usually /dev/vdb – recognizable by the size you booked.

Create a partition on the new disk (here /dev/vdb):

sudo cfdisk /dev/vdb

Choose gpt at the prompt (the modern standard – dos/MBR can address at most 2 TiB, libraries like to grow beyond that), then New, take the full size, and write the table with Write (type yes), then Quit. The partition /dev/vdb1 is created. Format it with an ext4 filesystem:

sudo mkfs.ext4 /dev/vdb1

Create a mount point and mount the partition:

sudo mkdir -p /mnt/media
sudo mount /dev/vdb1 /mnt/media

So that the disk is mounted automatically even after a reboot, you enter it in /etc/fstab with its UUID (not with /dev/vdb1, which can change). Read out the UUID:

sudo blkid /dev/vdb1

/dev/vdb1: UUID="a1b2c3d4-...." TYPE="ext4" ...

Open the fstab and append the line with your UUID:

sudo nano /etc/fstab

UUID=a1b2c3d4-....   /mnt/media   ext4   defaults   0   2

Check the entries before you rely on the reboot – a typo in the fstab can block the boot process:

sudo umount /mnt/media && sudo mount -a && df -h /mnt/media

If no error appears here and df -h shows your new disk under /mnt/media, everything is entered correctly.

Step 3: Create the project and media folders

Create the Compose project – the configuration is small and may go on the system disk. You create the subfolders config and cache right along, before the container starts for the first time: if the Docker daemon created them first, they would belong to root – but Jellyfin runs as UID 1000 (see step 4) and couldn’t write into its own /config, the container would crash on the first start.

mkdir -p ~/jellyfin/{config,cache} && cd ~/jellyfin

And the folder structure for the library on the block storage. Jellyfin sorts best when movies, series and music are kept separate:

sudo mkdir -p /mnt/media/{filme,serien,musik}

So that the Jellyfin container may read the files, they have to belong to your user. Determine your user and group ID (usually 1000) and hand over the folder:

id -u && id -g
sudo chown -R 1000:1000 /mnt/media

Now copy your media into the appropriate subfolders (via scp, rsync or an SFTP client). For clean recognition, a clear naming helps, e.g. filme/The Godfather (1972)/The Godfather (1972).mkv.

Step 4: The compose.yaml

Now the central file. Replace jellyfin.YOUR_DOMAIN with your subdomain:

services:
  jellyfin:
    image: jellyfin/jellyfin:10.11.11
    user: "1000:1000"
    environment:
      - JELLYFIN_PublishedServerUrl=https://jellyfin.YOUR_DOMAIN
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.jellyfin.rule=Host(`jellyfin.YOUR_DOMAIN`)"
      - "traefik.http.routers.jellyfin.entrypoints=websecure"
      - "traefik.http.routers.jellyfin.tls.certresolver=le"
      - "traefik.http.services.jellyfin.loadbalancer.server.port=8096"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

What the lines mean:

• image: …:10.11.11 – the fixed, current stable version. No latest (see “Maintenance & backups”).
• user: "1000:1000" – Jellyfin runs with your user/group ID so it can read the media. If you adjust other IDs in step 3, change them here too.
• JELLYFIN_PublishedServerUrl – tells Jellyfin under which public address it’s reachable. This prevents app links from suddenly pointing to an internal IP.
• volumes: config (settings, users, metadata) and cache live small in the project folder; the library is mounted from the block storage under /mnt/media into the container as /media – :ro (read-only), so Jellyfin never changes your originals.
• The four Traefik labels are the familiar pattern. New is only the port: Jellyfin listens on 8096, hence the loadbalancer.server.port label. Without it, there’d be a 502 Bad Gateway.
• No ports: – Jellyfin is reachable exclusively via Traefik (HTTPS), not directly from the internet.

Start the stack and watch it boot:

docker compose up -d
docker compose logs -f jellyfin

On the first start, certificate issuance takes a few seconds. Once Startup complete appears in the log, Jellyfin is ready.

Step 5: The initial setup wizard

Open https://jellyfin.YOUR_DOMAIN in the browser. On the very first call, a wizard guides you through the basic setup:

1. Choose the language.
2. Create an administrator account – set a long, unique password, because the login page is publicly on the net.
3. Add media libraries: click “Add media library”, choose the type (e.g. Movies), and enter the container path as the folder – i.e. /media/filme (not /mnt/media/filme, that’s the path on the host!). Repeat this for serien and musik.
4. Set the metadata language and you can accept the rest.

After the wizard, Jellyfin scans the folders and loads covers and descriptions. For large collections the first scan takes a while – you see the progress under Dashboard → Scheduled Tasks. After that you land on the home page and see your library with the first titles:

Step 6: Configure Jellyfin cleanly behind the proxy

Two settings make Jellyfin work correctly behind Traefik. Open Dashboard → Networking:

• Under Known proxies you enter the Traefik network so Jellyfin sees the real client IP (instead of Traefik’s container IP). You determine the subnet with:

  Terminal

  docker network inspect proxy --format '{{ (index .IPAM.Config 0).Subnet }}'

  Enter the returned range (e.g. 172.19.0.0/16) there.

• HTTPS: since Traefik handles the encryption, Jellyfin itself needs no TLS. Leave the HTTPS options in Jellyfin empty – everything runs via the proxy.

WebSockets (for live updates of the interface) Traefik forwards automatically, nothing to do there.

Step 7: Transcoding vs. Direct Play

Whether your server breaks a sweat is decided here. Two cases:

• Direct Play – the end device can play the file as-is. The server just pushes bytes through, almost no CPU load. That’s the ideal case.
• Transcoding – format, codec or bitrate don’t fit the device (or the line is too slow), so Jellyfin re-encodes live. On a netcup server this happens via the CPU – with a 4K stream that can max out a whole server.

This is how you keep the load low:

• Provide suitable formats: H.264/AAC in an .mp4/.mkv plays directly on practically every device. Exotic codecs (e.g. certain 4K HEVC audio tracks) force transcoding.
• Set the client quality in the app to “Original/Direct Play” when the line is enough.
• Under Dashboard → Playback you can set the transcoding settings and a limit for simultaneous streams.

When things go wrong

Maintenance & backups

• Apply updates deliberately. The fixed tag (jellyfin:10.11.11) means: you decide when to update. Bump the tag → docker compose pull → docker compose up -d. Before jumping to a new major version, read the release notes – database migrations aren’t always reversible.
• Back up the config, treat the media separately. The config volume (users, settings, playback state, metadata) is small and the actually valuable part – back it up encrypted off-site with Restic. The library itself is usually too large for a classic backup and reproducible from the original media; decide deliberately whether you back it up or classify it as “replaceable”. Honestly: a second backup of your movie collection costs real storage.
• Monitor disk space. A library grows steadily. Keep an eye on usage (df -h /mnt/media) and best set up a monitor in Uptime Kuma that raises the alarm before the block storage is full.
• Publicly reachable = secure it. The login page is on the net, and Jellyfin brings no two-factor authentication (not even via an official plugin). So consistently assign strong passwords, deactivate unused accounts – and for purely private use, consider making Jellyfin reachable not publicly but only via a VPN.

What are we building?

By the end, Immich v3 runs behind your Traefik proxy, reachable at https://photos.YOUR_DOMAIN with valid HTTPS. The official Immich phone app then backs up your new photos and videos automatically to your server – like the cloud backup of Google Photos, except the images live exclusively with you. Via the web interface you browse your timeline, search by full text (“beach”, “dog”) and let Immich group faces.

Immich consists of four containers: the server (web + API), a machine-learning service (for search and face recognition), a PostgreSQL database with a vector extension, and a cache (Valkey). Sounds like a lot – but the official template takes most of it off your hands, and we only hang the server onto Traefik.

The appeal over Google Photos: the images don’t leave your server, there are no storage subscriptions and no automatic analysis of your shots by a corporation. In return, you bear responsibility for operation and – very importantly – for backups: if the server dies and you have no backup, the photos are gone. That’s exactly why the backup below is not optional but mandatory.

Prerequisites

• A running Traefik reverse proxy with the proxy network and the Let’s Encrypt resolver le – see reverse proxy with Traefik.
• A subdomain photos.YOUR_DOMAIN with a DNS record to your server IP – see connecting a domain to your server.
• A backup. Your photo collection is irreplaceable – first set up backups with Restic.

How much RAM your photo library including AI search really needs is calculated by the server calculator.

Step by step

Step 1: Create the DNS record

Create an entry photos.YOUR_DOMAIN that points to your server IP, and check it:

dig +short photos.YOUR_DOMAIN

Your server IP must come back – otherwise Traefik won’t fetch a certificate later.

Step 2: Prepare the folder and .env

Immich is configured via a .env file. Create the project:

mkdir -p ~/immich && cd ~/immich

Create a .env with the core values (set a strong DB password – letters and digits only, no special characters, Immich’s DB init doesn’t like those):

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
DB_PASSWORD=YOUR_DB_PASSWORD
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
IMMICH_VERSION=v3.0.3

• UPLOAD_LOCATION – this is where your photos and videos land. It’s the most important directory for the backup.
• DB_DATA_LOCATION – the PostgreSQL data. Must be on a local disk (no network drive/NFS – the DB resents that).
• IMMICH_VERSION – the pinned version.

Step 3: Create the compose.yaml

We adopt the official Immich template and only add the Traefik labels on the immich-server. Create compose.yaml:

name: immich
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION}
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
    env_file: .env
    environment:
      DB_HOSTNAME: database
      REDIS_HOSTNAME: redis
    depends_on:
      redis:
        condition: service_started
      database:
        condition: service_healthy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.immich.rule=Host(`photos.YOUR_DOMAIN`)"
      - "traefik.http.routers.immich.entrypoints=websecure"
      - "traefik.http.routers.immich.tls.certresolver=le"
      - "traefik.http.services.immich.loadbalancer.server.port=2283"
    networks: [default, proxy]
    restart: unless-stopped

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION}
    volumes:
      - model-cache:/cache
    networks: [default]
    restart: unless-stopped

  redis:
    image: docker.io/valkey/valkey:9
    networks: [default]
    restart: unless-stopped

  database:
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME} -d ${DB_DATABASE_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks: [default]
    restart: unless-stopped

volumes:
  model-cache:

networks:
  default:
  proxy:
    external: true

Important to understand:

• Only immich-server is on the proxy network and carries Traefik labels. The ML service, Valkey and the database stay exclusively on the internal default network – not reachable from outside.
• loadbalancer.server.port=2283 – Immich listens on port 2283 in the container.
• The database is deliberately the prebuilt Immich Postgres image with the vector extension VectorChord (for image search). Don’t just use a standard postgres – the extension is then missing.
• Valkey is the Redis successor; the service is still called redis in the Immich template for compatibility reasons.
• The healthcheck on the database reports when Postgres is really ready. Via depends_on: … condition: service_healthy, immich-server only starts then – this prevents migration errors and the “database not reachable” start on the first boot.

Step 4: Allow large uploads (Traefik timeout)

This is the stumbling block with Immich behind Traefik: by default Traefik aborts connections after 60 seconds (readTimeout). When uploading large videos from the phone this leads to aborted uploads (error 502/499). Increase the timeout on the websecure entrypoint in your Traefik configuration (the traefik service from the Traefik tutorial):

    command:
      # ... your existing lines ...
      - "--entrypoints.websecure.transport.respondingTimeouts.readTimeout=600s"

Restart Traefik afterwards (docker compose up -d in the Traefik folder). Unlike nginx, Traefik has no fixed size limit for uploads – only this timeout has to be high.

Step 5: Start and run through the initial setup

Pull the images (several GB – this takes a while) and start:

docker compose up -d
docker compose logs -f immich-server

The images are several gigabytes in size – the first pull takes a few minutes depending on your connection. Then check that all four containers are running:

docker compose ps

You should see immich-server, immich-machine-learning, redis and database with status running (the database healthy). Wait until Immich Server is listening on http://[::1]:2283 [v3.0.3] appears in the log. Then open https://photos.YOUR_DOMAIN. Traefik fetches the Let’s Encrypt certificate on the first access (be patient for a moment). On the very first start, Immich greets you with “Welcome to Immich” and the choice of whether you start fresh or restore a backup:

Click Getting Started (you only need Restore if you’re importing a backup). Then you create the administrator account – as the first user you automatically become admin:

After the first login, a short setup wizard guides you through theme, language and basic privacy settings:

After that you land on your (still empty) timeline – the heart of Immich:

Step 6: Connect the phone app

The real benefit comes from the app. Install Immich from the App Store or Play Store (or F-Droid). At launch it asks for the server address – enter https://photos.YOUR_DOMAIN and log in with your account. Then, in the app settings, enable the backup and choose the albums to be uploaded.

From now on your phone backs up new photos automatically to your server – in the background and over Wi-Fi. The first pass of a large library takes a while; after that only new shots are added.

After the upload, Immich keeps working in the background: it generates thumbnails, reads the capture metadata (date, location) and lets the ML service recognize faces and index the images for smart search. These jobs run for some time after the first big import – so faces and search hits only appear gradually. You see the progress under Administration → Job queues. In the sidebar you then find the typical photo features: Explore (by people and places), the map with geolocation, albums for sharing and the memories (“a year ago”).

When things go wrong

Maintenance & backups

• Two things belong in the backup – consistently together. Your photos (UPLOAD_LOCATION, i.e. ~/immich/library) and the database. The DB dump contains only the metadata; without the matching files it’s worthless, and vice versa. Cleanest is to stop Immich briefly and back up both together:

  Terminal

  docker compose stop immich-server
  docker compose exec -T database pg_dump --clean --if-exists \
    --dbname=immich --username=postgres | gzip > immich-db.sql.gz
  docker compose start immich-server

  Back up the dump together with the library folder encrypted and off-site with Restic. Alternatively, Immich can generate automatic DB dumps under Administration → Job queues – you still have to back up the photos separately.

• Rehearse the worst case once. A backup you’ve never restored is just a hope. To restore, you import the DB dump into a fresh Immich instance of the same version and place the library folder in the same spot – Immich offers the option “Restore from database” on the first start for this (the second button from step 5). What matters is the same version: the database state and the program must match.

• Backup before every update. Because migrations aren’t reversible, the backup is your only way back. Back up first, then raise IMMICH_VERSION, then docker compose pull && docker compose up -d.

• Honest about the effort: Immich often brings several releases per month. You don’t have to follow every one – but before a jump across several versions, read the release notes, and stick to the pinned version until you deliberately update.

• Keep an eye on disk space. Photos and videos grow steadily; Immich additionally creates thumbnails and converted videos. Monitor the disk usage (e.g. with Uptime Kuma) so the server doesn’t fill up.

What are we building?

By the end, Paperless-ngx 2.20 runs behind your Traefik proxy, reachable at https://paperless.YOUR_DOMAIN with HTTPS. Paperless is a document management system: you feed it scans or PDFs, it reads out the text via OCR (even from pure image scans), recognizes date and content, and stores everything searchably. Via tags, correspondents and document types you bring order into it; the full-text search later finds every document.

The clever part is the consume folder: everything you place there (e.g. from a network scanner) is imported and processed automatically. Paperless consists of five containers – the web server, a PostgreSQL database, a Redis broker for background processing, plus Gotenberg and Tika, which convert office documents into PDF. The official template provides the complete team.

The gain over a folder full of PDFs on the disk: Paperless makes every document searchable (even scanned paper), keeps the original and archive version cleanly separated, and can be automated via rules. Your documents stay on your server – no cloud service reads along, and you’re not tied to a proprietary format.

Prerequisites

• A running Traefik reverse proxy with the proxy network and the resolver le – see reverse proxy with Traefik.
• A subdomain paperless.YOUR_DOMAIN with a DNS record to your server IP – see connecting a domain to your server.
• A backup. Your most important documents land in Paperless – first set up backups with Restic.

Not sure which server size is enough? The server calculator calculates the RAM and CPU needs for your services.

Step by step

Step 1: Create the DNS record

Create paperless.YOUR_DOMAIN (A/AAAA to your server IP) and check:

dig +short paperless.YOUR_DOMAIN

Your server IP must come back – otherwise Traefik won’t fetch a certificate later.

Step 2: Generate a secret key

Paperless encrypts sessions with a secret key. The default is publicly known – a real risk for an instance on the internet. Generate your own:

head -c 50 /dev/urandom | base64

Copy the output – it goes into the configuration as PAPERLESS_SECRET_KEY shortly.

Step 3: Create the compose.yaml

Create the project – including the two bind-mount folders:

mkdir -p ~/paperless/{consume,export} && cd ~/paperless

You deliberately create the subfolders consume and export now, as a normal user: if the Docker daemon created them at startup, they would belong to root – then neither you (cp into the consume folder) nor Paperless itself (runs via USERMAP_UID as UID 1000) could write into them.

Create compose.yaml. Replace paperless.YOUR_DOMAIN, the passwords and the PAPERLESS_SECRET_KEY:

name: paperless
services:
  broker:
    image: docker.io/library/redis:8
    volumes:
      - redisdata:/data
    networks: [default]
    restart: unless-stopped

  db:
    image: docker.io/library/postgres:18
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: A_STRONG_DB_PASSWORD
    volumes:
      - pgdata:/var/lib/postgresql
    networks: [default]
    restart: unless-stopped

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.34
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"
    networks: [default]
    restart: unless-stopped

  tika:
    image: docker.io/apache/tika:3.3.1.0
    networks: [default]
    restart: unless-stopped

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15
    depends_on: [db, broker, gotenberg, tika]
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: A_STRONG_DB_PASSWORD
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_URL: https://paperless.YOUR_DOMAIN
      PAPERLESS_SECRET_KEY: YOUR_LONG_SECRET_KEY
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: A_STRONG_ADMIN_PASSWORD
      USERMAP_UID: "1000"
      USERMAP_GID: "1000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ppl.rule=Host(`paperless.YOUR_DOMAIN`)"
      - "traefik.http.routers.ppl.entrypoints=websecure"
      - "traefik.http.routers.ppl.tls.certresolver=le"
      - "traefik.http.services.ppl.loadbalancer.server.port=8000"
    networks: [default, proxy]
    restart: unless-stopped

volumes:
  data:
  media:
  pgdata:
  redisdata:

networks:
  default:
  proxy:
    external: true

The most important points:

• Only webserver is on the proxy network and carries Traefik labels (port 8000). The four helper services (db, broker, gotenberg, tika) stay internal.
• PAPERLESS_URL is mandatory behind a proxy. Without it, Paperless rejects the login with a CSRF/“403 Forbidden” error. It simultaneously sets the allowed hosts and the trusted origins.
• PAPERLESS_OCR_LANGUAGE: eng sets text recognition to English. English, German and a few other languages are already included in the image – no additional package needed.
• PAPERLESS_ADMIN_USER / _PASSWORD create the superuser automatically on the first start, so you can log in directly.
• USERMAP_UID/GID should match your server user’s ID (determine via id -u or id -g, usually 1000). Otherwise there’s “Permission denied” in the consume folder.
• export and consume are deliberately folders in the project directory (bind mounts): consume is the inbox, export the target for backups.

Paperless uses four storage areas in total, which you should keep apart: media contains your processed documents (the heart!), data the search index and helper data, consume is the inbox and export the backup target. For the backup, media and data plus the database count – exactly what the document_exporter further below takes off your hands.

Step 4: Start and log in

Pull the images (several GB) and start:

docker compose up -d
docker compose logs -f webserver

On the first start, Paperless sets up the database (migrations) – that takes a moment. Check that all five containers are running:

docker compose ps

You should see webserver, db, broker, gotenberg and tika with status running (the webserver becomes healthy after a short while). Once the worker is ready (celery@… ready in the log), open https://paperless.YOUR_DOMAIN. The login page appears:

Log in with admin and your password. You land on the home page with a short welcome message and initial statistics. At the bottom left you see the running version – handy to know the starting point before an update. You can change the language under Settings if needed; by default Paperless follows your browser’s language:

Step 5: Import the first document

Now the core. There are three ways to get a document in:

1. Via the web interface: click Upload documents at the top right and choose a PDF or image file.
2. Via the consume folder: place a file in ~/paperless/consume – Paperless detects it automatically, processes it and then deletes it from the folder. Ideal for a network scanner that scans directly there.
3. From a mailbox: under Email, Paperless can fetch an IMAP account and import attachments automatically – handy for invoices that come to you by mail anyway.

cp ~/an-invoice.pdf ~/paperless/consume/

Paperless accepts PDFs, images (JPG/PNG/TIFF) and – thanks to Gotenberg and Tika – office files like Word or Excel. For a pure image scan, the OCR reads out the text and places it as a searchable layer over the document; for a PDF with an existing text layer, Paperless skips the recognition and is correspondingly faster. The original is preserved untouched – Paperless additionally creates a searchable archive version.

After a few seconds (OCR takes some time), the document appears under Documents – with a preview and the recognized title:

A click opens the detail view: on the left the metadata (title, date, correspondent, tags) and the tabs for content, metadata and history, on the right the document with a zoomable preview. Paperless has already recognized the date from the scan and suggests it for confirmation – exactly what the OCR does for you in the background:

Step 6: Order with tags, correspondents & document types

So that the search works later, you assign tags (e.g. Tax, Insurance), assign a correspondent (the sender) and a document type (invoice, contract …). You can do that by hand – or automate it via workflows: rules that automatically tag incoming documents based on their content. This way your archive sorts itself over time.

The full-text search at the top then searches not only titles and tags, but the complete recognized text – a search for invoice amount or a customer name finds the matching document in seconds. Combined with the filters (correspondent, period, document type), the paper pile finally becomes a searchable archive.

A simple example of a workflow: if a new document contains the word “electricity bill”, automatically assign the tag Energy, set the correspondent to your electricity provider and the document type to Invoice. You create such rules under Administration → Workflows; they take effect for every incoming document. At the start it pays to sort a few documents by hand – from that you quickly see which rules repeat and can be automated. After a few weeks, the majority of your mail lands in the right place without your involvement.

When things go wrong

Maintenance & backups

• The clean backup is done by the document_exporter. It writes all documents, thumbnails, metadata and the database content into the export folder – portable and re-importable:

  Terminal

  docker compose exec -T webserver document_exporter ../export

  Then back up the export folder encrypted and off-site with Restic. Alternatively you back up the volumes media, data and the database directly – but the exporter is the recommended, migration-safe way.

• Use the same version when restoring. An export contains an image matching the database schema; only import it into a Paperless instance of the same version (document_importer ../export).

• Updates. Before the update, pull a backup, then raise the image tag (e.g. 2.20.15 → next version), docker compose pull and docker compose up -d. The database migrations run automatically at startup. Stay on the stable 2.x series – the 3.0 beta isn’t meant for production yet.

• Automate the backup. Best put the document_exporter in a daily cron job (e.g. at night) that afterwards backs up the export folder via Restic. That way you have a fresh, restorable state every morning – without having to think about it.

• Honest about the effort: Paperless runs very low-maintenance after that. The actual effort is filing new documents – but with a bit of set-up automation, the software increasingly takes that off your hands too. Plan the rough tag structure once, then the archive largely maintains itself.

What are we building?

By the end, Uptime Kuma 2.4 runs at https://status.YOUR_DOMAIN, secured via Traefik with automatic HTTPS. You’ve set up the first monitor (which checks every minute whether a service responds), connected a notification and optionally a public status page. For the first time we bind a service that doesn’t listen on port 80 – an important detail for all the following apps.

Prerequisites

• A running Traefik reverse proxy including the proxy network and a working Let’s Encrypt resolver le
• A DNS record status.YOUR_DOMAIN that points to the server

Step by step

Step 1: The compose.yaml

Own folder, own file:

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    volumes:
      - kuma-data:/app/data
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kuma.rule=Host(`status.YOUR_DOMAIN`)"
      - "traefik.http.routers.kuma.entrypoints=websecure"
      - "traefik.http.routers.kuma.tls.certresolver=le"
      - "traefik.http.services.kuma.loadbalancer.server.port=3001"
    restart: unless-stopped

volumes:
  kuma-data:

networks:
  proxy:
    external: true

You know this from the Traefik tutorial – except for one new, decisive line:

      - "traefik.http.services.kuma.loadbalancer.server.port=3001"

Uptime Kuma listens internally on port 3001, not on 80. This line tells Traefik which port to forward the requests to. Without it, Traefik guesses wrong and you get a Bad Gateway. Remember the label – every app that doesn’t run on port 80 needs it.

The rest is the familiar pattern: no ports: (only reachable via Traefik), proxy network, named volume for the data.

Step 2: Start and first login

docker compose up -d
docker compose logs -f uptime-kuma

When Kuma is ready, the log ends with this line – from here the service accepts requests (Ctrl+C only ends the following):

[SERVER] INFO: Welcome to Uptime Kuma
[SERVER] INFO: Uptime Kuma Version: 2.4.0
[SETUP-DATABASE] INFO: Listening on:
[SETUP-DATABASE] INFO: -  http://localhost:3001

On the first start, Kuma creates its database in the volume – that takes a few seconds. Then open https://status.YOUR_DOMAIN in the browser. Uptime Kuma 2.x first asks for the database – for a setup like ours, SQLite is the right, simplest choice (select it, click Next). Right after that you create the admin account (username + strong password).

Step 3: Create the first monitor

A monitor is a recurring check. Click Add New Monitor and create one for Traefik itself:

• Monitor type: HTTP(s)
• Friendly name: Traefik Dashboard
• URL: https://traefik.YOUR_DOMAIN
• Heartbeat interval: 60 seconds
• Authentication: the Traefik dashboard is protected by basic auth (step 7 of the Traefik tutorial) – so choose HTTP Basic Auth as the authentication method below and enter the user and password. Without credentials, Kuma only gets 401 and reports the monitor as Down.

Save – after a few seconds the monitor is Up (green) and shows the response time.

Besides the simple HTTP(s) check, it pays to choose the matching monitor type:

• HTTP(s) – Keyword: additionally checks whether a certain word appears in the response text. This detects “the server responds, but shows an error page”.
• TCP port: for services without a web interface (e.g. a database, an SSH port). Only checks whether the port is open.
• Ping: the simplest reachability test via ICMP.
• Docker container: checks the container status directly via the Docker socket – handy for internal services without their own domain.
• Push: here the monitored service calls Kuma regularly. Ideal for cron jobs and backups: if the script doesn’t report in time, Kuma raises the alarm (“dead man’s switch”).

Create the matching monitor for every important service.

For the HTTP(s) monitor, the option “certificate expiry notification” is also worth it: Kuma then warns in good time before a TLS certificate expires. For services behind Traefik, Let’s Encrypt renews automatically – but this very automation occasionally fails silently (a DNS record is changed, port 80 accidentally closed). The monitor is your safety net and reports in while there are still days to fix it, instead of visitors suddenly facing a certificate warning.

Step 4: Set up notifications (email and Telegram)

A monitor without an alarm is just a pretty chart. Under Settings → Notifications → Setup Notification you create a channel. Uptime Kuma supports over 90 – we set up the two most common completely: email for the classic message and Telegram for push straight to the phone.

Email (SMTP)

Choose “Email (SMTP)” as the notification service and enter your mail provider’s data:

• Hostname / port: e.g. smtp.YOUR_PROVIDER.com and 587
• Security: STARTTLS (port 587) or TLS/SSL (port 465)
• Username / password: your SMTP credentials
• From / to address: which address the warning comes from and which it’s sent to

Click Test – within a few seconds a test message lands in the mailbox. Only when it really arrives are the credentials and port correct. Don’t forget to save.

Telegram

Telegram is ideal for instant push alerts to the phone – without your own mail server. You need two pieces of information:

1. Bot token: message @BotFather in Telegram, send /newbot, assign a name – BotFather replies with the token.
2. Chat ID: send your new bot any message, then open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in the browser and read the chat.id from the response.

Enter the token and chat ID into the Telegram notification (Uptime Kuma links both helpers directly in the dialog) and click Test – the message should appear in the chat immediately.

If you want push messages entirely under your own control (without a Telegram server), ntfy comes later – self-hosted, with its own recipe in the series.

Step 5: A public status page (optional)

Kuma can publish a status page where visitors see whether your services are running. Here’s how:

1. Status Pages → New Status Page, then assign a name (e.g. “Serverküche Status”) and a slug (the URL, e.g. serverkueche) and click Next.
2. In the editor, Add Group (e.g. “Services”), and below it, add the desired monitors via the selection field.
3. Save at the top right – done. The page is then publicly reachable at https://status.YOUR_DOMAIN/status/serverkueche.

Only include what really everyone may see – better leave internal services out.

Step 6: Avoid false alarms – fine-tune the alarm behavior

A monitor that raises the alarm at every brief network hiccup is quickly ignored – and then you miss the real outage. In the monitor form you set the behavior appropriately:

• Retries: the service only counts as “Down” after n failed checks. 2–3 filters out individual dropouts without obscuring real outages for long.
• Heartbeat interval on failure: Kuma may check more often in the error case (e.g. every 20 seconds) to detect recovery quickly.
• Resend notification: Kuma can remind you every x minutes as long as a service is down – useful so an outage at night doesn’t get lost in a single mail.

Step 7: Monitor cron jobs with a push monitor

Classic monitors check from outside whether a service responds. For things that run silently in the background – a nightly backup, a sync script, a cron job – the push monitor flips the principle: not Kuma asks, but your script reports in. If the report fails to come, Kuma raises the alarm – the classic “dead man’s switch”.

Create a monitor of type Push. Kuma then shows you a unique push URL:

https://status.YOUR_DOMAIN/api/push/YOUR_TOKEN?status=up&msg=OK&ping=

You call this URL at the end of your script – for example after a successfully completed backup:

# ... your backup command ...
curl -fsS "https://status.YOUR_DOMAIN/api/push/YOUR_TOKEN?status=up&msg=Backup+OK" > /dev/null

Set the check interval in Kuma a bit more generously than your cron cadence (if the backup runs hourly, give Kuma e.g. 90 minutes of tolerance). If no curl comes in that time, the monitor goes to Down and you’re notified – so you learn about a backup that did not run, not only when you urgently need it.

Step 8: Secure the admin login with 2FA

Your Kuma login protects access to all monitors, the stored notification credentials and the status-page configuration – and it’s publicly on the net. So enable two-factor authentication: under Settings → Security → Two-Factor Authentication. Kuma shows a QR code you scan with an authenticator app (e.g. Aegis or 2FAS); to activate, you enter the generated code once.

When things go wrong

Maintenance & backups

• Back up: the complete heart of Kuma is the kuma-data volume (a SQLite database). Back it up regularly – if it’s gone, all monitors and the history are gone. We build the off-site backup for it in the Restic tutorial.
• Updates: the tag :2 stays on the 2.x series and brings bug fixes with docker compose pull && docker compose up -d. Before a jump to a new major version (e.g. later :3), read the release notes and back up the volume first.
• Coming from 1.x? The switch to :2 migrates the SQLite database automatically on the first start – that can take a moment, and going back to :1 is not intended afterwards. So back up the kuma-data volume beforehand, then you’re on the safe side. New installations (like above) aren’t affected.
• Honest limitation: a monitor that runs on the same server as the monitored services can’t warn you when the whole server fails – then Kuma is offline too. For that case, add an external watcher. Two cheap ways: a second Uptime Kuma on a small server (or at home) that only monitors this instance via HTTP – or a free external ping service that pings your public status page. This way you also get a notice when the whole host is gone – the only case a local monitor inherently can’t cover.

With that you’ve internalized the app pattern and monitor everything you hang behind Traefik from now on. What every further app requires are encrypted off-site backups with Restic – so your data survives a server crash.

What are we building?

By the end, Nextcloud 34 runs behind your Traefik proxy, reachable at https://cloud.YOUR_DOMAIN with a valid Let’s Encrypt certificate. Nextcloud is your private cloud: sync files (like Dropbox), calendar and contacts across all devices, photos, notes, office documents. You connect the official desktop sync client and the phone apps with your server – the data lives exclusively with you.

We deliberately use the classic nextcloud image (not “Nextcloud All-in-One”) plus MariaDB as the database and Redis for caching and file locking. This combination is stable, well documented and fits exactly into the Traefik pattern from the Serverküche.

Prerequisites

• A running Traefik reverse proxy with the shared proxy network and the Let’s Encrypt resolver le – set up as in the tutorial reverse proxy with Traefik.
• A subdomain cloud.YOUR_DOMAIN whose DNS record (A/AAAA) points to your server IP – see connecting a domain to your server.
• A working backup. A cloud is the place where data loss hurts most – first set up backups with Restic.

How big your server should be for your user count is estimated by the server calculator in a few clicks.

Step by step

Step 1: Create the DNS record

At your DNS provider, create an entry cloud.YOUR_DOMAIN that points to your server IP (A record for IPv4, AAAA for IPv6). Check that it resolves:

dig +short cloud.YOUR_DOMAIN

You should see your server IP. Only once the record is set can Traefik fetch the HTTPS certificate later.

Step 2: Determine the proxy subnet

Nextcloud sits behind Traefik. So that Nextcloud’s brute-force protection recognizes the real visitor IP (and doesn’t ban the internal Traefik IP), we have to enter Traefik as a “trusted proxy”. For that you need the subnet of your proxy network:

docker network inspect proxy -f '{{(index .IPAM.Config 0).Subnet}}'

You get something like 172.18.0.0/16. Remember this value – it goes into the configuration as TRUSTED_PROXIES shortly.

Step 3: Create the compose.yaml

Create a folder and change into it:

mkdir -p ~/nextcloud && cd ~/nextcloud

Create the compose.yaml. Replace cloud.YOUR_DOMAIN, all passwords and the TRUSTED_PROXIES subnet from step 2:

services:
  nc-db:
    image: mariadb:11.4
    container_name: nc-db
    command: --transaction-isolation=READ-COMMITTED --log-bin=binlog --binlog-format=ROW
    environment:
      MARIADB_ROOT_PASSWORD: A_STRONG_ROOT_PASSWORD
      MARIADB_DATABASE: nextcloud
      MARIADB_USER: nextcloud
      MARIADB_PASSWORD: A_STRONG_DB_PASSWORD
    volumes:
      - nc_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 6
    networks: [default]
    restart: unless-stopped

  nc-redis:
    image: redis:8-alpine
    container_name: nc-redis
    command: redis-server --requirepass A_STRONG_REDIS_PASSWORD
    networks: [default]
    restart: unless-stopped

  nc-app:
    image: nextcloud:34-apache
    container_name: nc-app
    depends_on:
      nc-db:
        condition: service_healthy
      nc-redis:
        condition: service_started
    environment:
      MYSQL_HOST: nc-db
      MYSQL_DATABASE: nextcloud
      MYSQL_USER: nextcloud
      MYSQL_PASSWORD: A_STRONG_DB_PASSWORD
      REDIS_HOST: nc-redis
      REDIS_HOST_PASSWORD: A_STRONG_REDIS_PASSWORD
      NEXTCLOUD_TRUSTED_DOMAINS: cloud.YOUR_DOMAIN
      OVERWRITEPROTOCOL: https
      OVERWRITECLIURL: https://cloud.YOUR_DOMAIN
      TRUSTED_PROXIES: 172.18.0.0/16
      PHP_MEMORY_LIMIT: 1024M
      PHP_UPLOAD_LIMIT: 10G
    volumes:
      - nc_html:/var/www/html
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.nc.rule=Host(`cloud.YOUR_DOMAIN`)"
      - "traefik.http.routers.nc.entrypoints=websecure"
      - "traefik.http.routers.nc.tls.certresolver=le"
      - "traefik.http.routers.nc.middlewares=nc-dav"
      - "traefik.http.services.nc.loadbalancer.server.port=80"
      # .well-known redirect for CalDAV/CardDAV (see below)
      - "traefik.http.middlewares.nc-dav.redirectregex.regex=https://(.*)/.well-known/(?:card|cal)dav"
      - "traefik.http.middlewares.nc-dav.redirectregex.replacement=https://cloud.YOUR_DOMAIN/remote.php/dav/"
      - "traefik.http.middlewares.nc-dav.redirectregex.permanent=true"
    networks: [default, proxy]
    restart: unless-stopped

volumes:
  nc_html:
  nc_db:

networks:
  default:
  proxy:
    external: true

What matters here:

• Three containers: nc-app (Nextcloud), nc-db (MariaDB), nc-redis. Only nc-app is on the proxy network (for Traefik) and on the internal default network. Database and Redis stay exclusively internal – they have no ports: and are not reachable from outside.
• Two named volumes: nc_html (program code, config.php, user data) and nc_db (the MariaDB data). The nc_db volume is mandatory: without the entry, the database lands in an anonymous volume, and a docker compose down followed by up would lose it irrecoverably.
• healthcheck + depends_on: service_healthy: Nextcloud starts faster than the database initializes. Without this healthcheck the initial install fails with a “Connection refused”. This way the app container waits until MariaDB is really ready.
• NEXTCLOUD_TRUSTED_DOMAINS: without your own domain here, Nextcloud greets you with “Access through untrusted domain”.
• OVERWRITEPROTOCOL: https tells Nextcloud it runs behind HTTPS – otherwise it builds internal links as http:// and logins/redirects break.
• TRUSTED_PROXIES: the subnet from step 2. This lets Nextcloud recognize the real client IP; otherwise the brute-force protection bans the Traefik IP.
• PHP_MEMORY_LIMIT / PHP_UPLOAD_LIMIT: the defaults (512 MB) are too small for large uploads. Set generously here.
• loadbalancer.server.port=80: the Apache image listens on port 80 in the container.
• The nc-dav middleware solves a classic Nextcloud problem – more on that shortly.

Step 4: Start and run through the initial setup

Start the stack:

docker compose up -d

On the first start, MariaDB initializes the database and Nextcloud unpacks itself – that takes a minute or two. Follow it in the log:

docker compose logs -f nc-app

On the first run the image unpacks Nextcloud into the volume; you see lines like Initializing nextcloud 34.0.1.2 ... and finally Initializing finished, followed by the Apache start. If restarting appears repeatedly instead, take a look at the “When things go wrong” section. With Ctrl+C you leave the log view again (the container keeps running).

Then open https://cloud.YOUR_DOMAIN. Traefik fetches the certificate on the first access (can take a few seconds). Because we already configured the database and Redis via environment variables, Nextcloud detects that automatically and only asks for an administration account:

Set an admin name and a strong password and click Install. Nextcloud sets up the instance – after that you land on the login page:

After the login, the dashboard greets you, and under Files you find your cloud with a few example files:

Step 5: Set up background jobs (cron)

Nextcloud has to perform tasks regularly (cleanup, notifications, thumbnails). By default this happens via “AJAX” on every page load – which is unreliable. The recommended way is a cron sidecar: a second container with the same image that only runs cron.php. Add a service to the compose.yaml:

  nc-cron:
    image: nextcloud:34-apache
    container_name: nc-cron
    entrypoint: /cron.sh
    depends_on:
      nc-db:
        condition: service_healthy
    volumes:
      - nc_html:/var/www/html
    networks: [default]
    restart: unless-stopped

The sidecar shares the nc_html volume with the app and runs the jobs every five minutes. Apply the change and set the mode in Nextcloud to “Cron”:

docker compose up -d
docker exec -u www-data nc-app php occ background:cron

Under Administration → Basic settings, “Cron” should now be active.

docker exec -u www-data nc-app php occ db:add-missing-indices
docker exec -u www-data nc-app php occ config:system:set default_phone_region --value=DE

Step 6: Connect the clients

Now the real benefit. There are three ways to use your cloud:

1. Desktop sync client (Windows/macOS/Linux): install the “Nextcloud Desktop” client, enter https://cloud.YOUR_DOMAIN as the server address, log in and choose a local folder. Files are synced like with Dropbox. With virtual files (Windows/macOS) they only take up space on the disk when you open them – handy when your cloud is larger than the local disk.
2. Phone app (Android/iOS): the official Nextcloud app, same server address. Ideal for automatic photo upload from the smartphone.
3. Calendar & contacts: in your device’s system settings, create a CalDAV/CardDAV account with the address https://cloud.YOUR_DOMAIN – thanks to the .well-known middleware from step 3, automatic detection works.

Features like calendar, contacts or mail are separate apps you install with one click under Administration → Apps – so Nextcloud is extensible without you touching anything on the server.

When things go wrong

Maintenance & backups

• Backups are mandatory for a cloud. A consistent backup needs three things: the database (MariaDB dump), the data directory (your files) and the configuration (config.php). Put Nextcloud into maintenance mode briefly before the backup so the database and files match each other:

  Terminal

  docker exec -u www-data nc-app php occ maintenance:mode --on
  docker exec nc-db mariadb-dump -u root -pA_STRONG_ROOT_PASSWORD nextcloud > nextcloud-db.sql
  docker exec -u www-data nc-app php occ maintenance:mode --off

  Back up the dump together with the nc_html volume encrypted and off-site with Restic – thanks to the dump you don’t need to additionally back up the raw nc_db volume. The nc_html volume contains both the program code and the config.php as well as – under data/ – your actual user files. If your cloud grows a lot, you can later move this data/ directory to a separate, larger volume; for now one volume for everything is enough.

• Updates: only one major version per step. From 34 to 35, never directly to 36. Bump the image tag (nextcloud:35-apache), then docker compose pull and docker compose up -d. The container runs the necessary occ upgrade automatically on start. Always make a backup first. Bump the cron sidecar to the same version.

• Check security. After setup, run the official Nextcloud Security Scan against your domain (target: grade A) and work through the warnings from the admin overview. The overview under Administration → Overview runs automatic checks and shows exactly what’s still missing. Keep Nextcloud up to date – security holes are closed promptly, but only if you update.

• Honest about the effort: a self-hosted cloud wants to be maintained. Reckon with an update pass roughly monthly and a regular look at the admin overview. In return, the data then really belongs to you.

What are we building?

By the end, Vaultwarden 1.36 runs in a container behind your Traefik proxy, reachable at https://vault.YOUR_DOMAIN with a valid HTTPS certificate. Vaultwarden is a lean reimplementation of the Bitwarden server written in Rust: API-compatible, but frugal enough to run on a small VPS. You connect the official Bitwarden clients (browser extension, phone app, desktop) with your server, store your credentials – end-to-end encrypted – and manage the service via a secured admin panel.

Your passwords thus live on your server, in your country, under your backup – and you pay no subscription fee for features like 2FA or attachments.

Prerequisites

• A running Traefik reverse proxy with the shared proxy network and the Let’s Encrypt resolver le – exactly the setup from the tutorial reverse proxy with Traefik. Without Traefik this recipe doesn’t work: Vaultwarden requires HTTPS.
• A subdomain, e.g. vault.YOUR_DOMAIN, whose DNS record (A/AAAA) points to your server IP – see connecting a domain to your server.
• A working backup of your server. A password manager is the place where data loss hurts most – if you haven’t yet, first set up backups with Restic.

If you want to combine several services later, the server calculator helps with the right server size.

Step by step

Step 1: Generate the ADMIN_TOKEN

Vaultwarden has an admin panel at /admin. Access to it is protected by an ADMIN_TOKEN. You should not store it in plaintext, but as a hash – then your panel password appears nowhere readable in the Compose file.

Vaultwarden brings its own command for this. We run it briefly in a throwaway container:

docker run --rm -it vaultwarden/server:1.36.0 /vaultwarden hash --preset owasp

The command asks you twice for a password (input stays invisible) and then outputs an Argon2id hash – a long string that starts like this:

Generate an Argon2id PHC string using the 'owasp' preset.

Password:
Confirm Password:

ADMIN_TOKEN='$argon2id$v=19$m=19456,t=2,p=1$FkxFEQ64Wy4zlQOWMI1fJ...$TxULe6MSND3By6GPVPKB1...'

Copy out the complete string between the quotes (including the $argon2id$… parts) – you need it in a moment. The password you entered here is your admin panel password; store it in your password manager (in the old one, for now).

Step 2: Create the compose.yaml

Create a dedicated folder and change into it:

mkdir -p ~/vaultwarden && cd ~/vaultwarden

Create the compose.yaml. Replace vault.YOUR_DOMAIN with your real subdomain and the ADMIN_TOKEN with the hash from step 1:

services:
  vaultwarden:
    image: vaultwarden/server:1.36.0
    volumes:
      - ./vw-data:/data
    environment:
      DOMAIN: "https://vault.YOUR_DOMAIN"
      SIGNUPS_ALLOWED: "true"
      ADMIN_TOKEN: "$$argon2id$$v=19$$m=19456,t=2,p=1$$FkxFE...$$TxULe..."
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.vaultwarden.rule=Host(`vault.YOUR_DOMAIN`)"
      - "traefik.http.routers.vaultwarden.entrypoints=websecure"
      - "traefik.http.routers.vaultwarden.tls.certresolver=le"
      - "traefik.http.services.vaultwarden.loadbalancer.server.port=80"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

The most important lines in detail:

• image: vaultwarden/server:1.36.0 – we deliberately pin the version instead of taking latest. That way you update in a controlled manner (see “Maintenance”). For an even smaller image there’s also :1.36.0-alpine.
• volumes: ./vw-data:/data – this is where your database (db.sqlite3), the encryption keys and the attachments live. This volume is mandatory. Without a volume Vaultwarden deliberately refuses to start, so you don’t lose your data in an ephemeral container.
• DOMAIN – the full HTTPS URL. Vaultwarden needs it for WebAuthn/2FA and invitation links, among other things. Must match your router rule exactly.
• SIGNUPS_ALLOWED: "true" – allows registration for now so you can create your first account. We turn that off again shortly.
• ADMIN_TOKEN – your hash from step 1. Important: in a Compose file every dollar sign must be doubled ($ → $$), otherwise Compose tries to interpret it as a variable. So $argon2id$… becomes $$argon2id$$….
• loadbalancer.server.port=80 – Vaultwarden listens on port 80 in the container. This line tells Traefik explicitly where to forward internally, instead of guessing the target port from the image – the same pattern as with every app behind Traefik.
• No ports: – as with every app behind Traefik, Vaultwarden is only reachable via the proxy, never directly from outside.

Step 3: Start it and the first call

Start the container:

docker compose up -d

On the first start, Vaultwarden creates the data directory and initializes the database. Take a look at the log:

docker compose logs -f vaultwarden

At the end you should see this line – it confirms the service is running:

[INFO] Rocket has launched from http://0.0.0.0:80

With Ctrl+C you leave the log view again (the container keeps running). Now open https://vault.YOUR_DOMAIN in the browser. On the first access Traefik fetches the Let’s Encrypt certificate – that can take a few seconds. After that the Bitwarden web interface appears.

Click Create account and create your first account – with your email address and a name:

In the next step you set your master password. That’s the one key that unlocks your entire vault:

Step 4: Close registration again

Once your account is set up, you want to prevent strangers from registering too – your Vaultwarden is, after all, open on the internet. Set SIGNUPS_ALLOWED to false in the compose.yaml:

    environment:
      DOMAIN: "https://vault.YOUR_DOMAIN"
      SIGNUPS_ALLOWED: "false"
      ADMIN_TOKEN: "$$argon2id$$..."

And apply the change:

docker compose up -d

Compose detects the changed environment variable and restarts the container. From now on the login page rejects new registrations. Further users (e.g. for the family) you invite specifically via the admin panel when needed – more on that shortly.

Step 5: The admin panel

Open https://vault.YOUR_DOMAIN/admin and log in with the password you entered in step 1 when generating the hash (not with the hash itself). You land in the management interface:

Here you control the service centrally:

• Users – view existing users, invite new ones (even with SIGNUPS_ALLOWED=false), deactivate accounts.
• Settings → SMTP Email Settings – enter your mail server’s credentials here so Vaultwarden can send invitations and 2FA codes by email. Without SMTP, invitation by link works too, but email-based 2FA doesn’t.
• Diagnostics – shows you whether your DOMAIN is set correctly and whether Vaultwarden is reachable from outside – handy for troubleshooting.

Step 6: Connect the clients

Now comes the real benefit. Install the official Bitwarden app or browser extension (from the respective app or add-on store). Before you log in, you switch the server:

1. In the app/extension, before logging in, open the settings for the self-hosted environment (gear icon or “Region: Self-hosted”).
2. Enter https://vault.YOUR_DOMAIN as the server URL and save.
3. Now log in with your email and your master password – the app talks to your server from now on.

The nice part: it’s the same mature clients as with commercial Bitwarden. Autofill, password generator, secure notes, attachments and 2FA storage work the same way – only the data lives on your server.

Import existing passwords: if you’re switching from another manager (or the browser’s password store), you don’t have to retype everything. Export your entries there as CSV or JSON and import them via the web interface under Tools → Import data. Vaultwarden understands the export formats of the common managers (KeePass, LastPass, 1Password, Chrome/Firefox, etc.) directly.

When things go wrong

Maintenance & backups

• Backups are non-negotiable for a password manager. Your entire vault is in the vw-data/ directory (SQLite database, keys, attachments). Back it up encrypted and off-site with Restic – add the folder ~/vaultwarden/vw-data to your backup sources. For a consistent database state, briefly run docker compose stop before the backup, or use the “Backup Database” function in the admin panel. A mere file copy while the container is running can catch an inconsistent state (SQLite writes into WAL files) – with a password manager that’s not a risk worth taking.

• Apply updates in a controlled way. Because we pinned the version, you update deliberately: before the switch read the release notes, then raise the tag in the compose.yaml (e.g. to the next 1.x) and pull anew:

  Terminal

  docker compose pull && docker compose up -d

  Afterwards check the Rocket has launched line in the log again and test a login.

• Keep registration closed. Occasionally check that SIGNUPS_ALLOWED is still false – always invite new users specifically via the admin panel.

• Rotate the ADMIN_TOKEN if it might be compromised: generate a new hash with the hash command from step 1, replace it in the compose.yaml, restart.

• Never lose the master password. There is no recovery. In a team/family setup, an emergency access can make sense – you set that up per vault in the account settings.

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: