DEV Community: serverkueche.de

Understanding Docker Compose: services, volumes, networks

serverkueche.de — Sat, 26 Sep 2026 06:07:52 +0000

In the Docker tutorial you installed the Compose plugin – but we didn't explain it yet. We're catching up on that now, because almost every app recipe here describes an application as a compose.yaml. Anyone who reads this file like a shopping list can adapt every following tutorial instead of just copying it.

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:

[+] up 2/2
 ✔ Network compose-demo_default Created                                     0.0s
 ✔ Container compose-demo-web-1 Started                                     0.2s

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.

Which of the two to pick when – and what that means for permissions, migrations and backups – is explored in Docker volumes vs. bind mounts.

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

[+] down 2/2
 ✔ Container compose-demo-web-1 Removed                                     0.2s
 ✔ Network compose-demo_default Removed                                     0.2s
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:

🛑 down -v deletes data

docker compose down -v also deletes the named volumes – i.e. all the stack's persistent data. Never type the -v out of reflex. For a plain restart, docker compose down (without -v) is enough.

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.22.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 --ipv6 --subnet fd00:cafe::/64 proxy

The --ipv6 belongs there as soon as a reverse proxy with a public domain sits behind the network: without IPv6 in the network, Docker replaces the source address of IPv6 visitors with the bridge gateway's, and the logs then show 172.x.x.x instead of the real IP. More on that in Reverse proxy with Traefik.

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.

What Compose sets up under the hood along the way – the bridge driver, the built-in DNS and containers that deliberately get no internet at all – is taken apart in
Understanding Docker networks.

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}

⚠️ Never push .env to a backup repo

The .env contains plaintext secrets. Add it to a .gitignore if you version your Compose files, and back it up separately (encrypted).

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
networks:
  default:
    name: compose-demo_default

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:

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.
Two separate named volumes. App data and database files live cleanly separated – that makes later backups and restores traceable.
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

yaml: line 7: did not find expected key (or similar YAML errors). YAML is indentation-sensitive – spaces only, never tabs, and consistent per level (common: 2 spaces). Check the file without starting it: docker compose config resolves everything and complains about exactly the wrong line.

Error ... address already in use on up. The host port (left in 8080:80) is already taken. Find the occupant with sudo ss -tlnp | grep 8080 or choose a different host port. Two containers cannot share the same host port.

An app can't find its database (could not translate host name). The hostname must be the service name (e.g. db), not localhost. Inside a container, localhost is the container itself, not the neighboring service. And: both services must be in the same Compose project (the same file).

After docker compose down all data is gone. Either the volume wasn't declared as a named volume under volumes: (then it was only the ephemeral container storage), or down -v was used. Always run persistent services with a declared named volume.

docker-compose: command not found. That's the old Compose v1 (with a hyphen). The current one is docker compose (with a space, plugin). If it's missing: sudo apt install docker-compose-plugin (see Docker tutorial).

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.

This post first appeared on serverkueche.de.

Hardening & optimizing Nextcloud: clear every warning (part 2)

serverkueche.de — Sat, 26 Sep 2026 06:07:26 +0000

Your Nextcloud is running – but the admin overview shows yellow warnings, there's no working email and no second factor protects your accounts. In this second part we turn "running" into "cleanly secured and snappy": we work through every warning until the overview is green.

What are we building?

By the end, the security & setup overview of your Nextcloud shows no more warnings. Concretely, we build on the installation from part 1 and add: the missing HSTS security header via Traefik, a configured maintenance window, working email sending (for password resets and notifications), enforced two-factor authentication and brute-force protection that sees the real attacker IPs – the basis for Fail2ban.

Everything is tested against Nextcloud 34.0.4 behind Traefik v3.7 on Debian 13 with PHP 8.5. This is legwork, but exactly the legwork missing in 90% of all Nextcloud guides – and it makes the difference between "somehow online" and "properly operated".

Prerequisites

A running Nextcloud set up as in self-hosting Nextcloud (part 1): classic nextcloud image behind Traefik, with MariaDB, Redis and a cron sidecar. The container names from part 1 (nc-app, nc-db, nc-redis, nc-cron) and the Compose folder ~/nextcloud are the basis here.
SSH access to the server and the command-line tool occ – we call it as in part 1 in the app container: docker exec -u www-data nc-app php occ <command>.
A Traefik reverse proxy with the proxy network and the resolver le as in the tutorial reverse proxy with Traefik – we attach the security headers as a Traefik middleware.

💡 Keeping occ in hand

occ is Nextcloud's admin tool. Because the containers in part 1 got fixed names (container_name), you address the app container directly – no matter which directory you're in:
docker exec -u www-data nc-app php occ status
You should see installed: true and your version. We won't abbreviate this prefix (docker exec -u www-data nc-app php occ …) in the following – so you can copy every command directly. Only the few docker compose … commands (like the container restart in step 3) you still run from the ~/nextcloud folder.

Step by step

Step 1: Read the admin overview as a stock-take

Log in as administrator and open Administration → Overview. At the top is the "Security & setup warnings" section. Right after a standard installation it looks like this:

Nextcloud distinguishes three levels: yellow warnings (⚠, you should fix), blue notices (ℹ, usually optional) and silently passed checks. On our fresh instance there are three warnings and a few notices:

⚠ Maintenance window start is not set (step 2)
⚠ MIME-type migrations available (step 2)
⚠ HTTP headers – the Strict-Transport-Security header is missing (step 3)
ℹ Email test – no mail server configured yet (step 4)
ℹ Two-factor configuration – 2FA is available but not enforced (step 5)

You also get the same report on the command line – handy to check progress in between without clicking through the web interface:

docker exec -u www-data nc-app php occ setupchecks

The command outputs each check with ✓, ⚠ or ✗. We now work through exactly this list from top to bottom.

Step 2: Fix the two quick warnings

Two warnings are done with one command each.

Set the maintenance window. Nextcloud runs compute-intensive cleanup jobs once daily (previews, activities, calendar repeats). Without a defined time window they run at some point – even in the middle of the day. Set a start time when hardly anyone works. The value is a full hour in UTC; 1 sets the start to 01:00 UTC – the check afterwards reports the window from 1:00 to 7:00 UTC:

docker exec -u www-data nc-app php occ config:system:set maintenance_window_start --type=integer --value=1

To verify, the setup check afterwards confirms:

✓ Maintenance window start: Maintenance window to execute heavy background jobs is between 1:00 UTC and 7:00 UTC

Run MIME-type migrations. Occasionally Nextcloud learns new file types (e.g. for better icons and previews). This migration does not run automatically on updates because it can take a while on large instances. On a fresh cloud it's done in seconds:

docker exec -u www-data nc-app php occ maintenance:repair --include-expensive

You see a list of repair steps performed (including Repair mime types). Afterwards the check reports Mimetype migrations available: None. Two fewer warnings.

ℹ️ And the blue notices?

The notices "AppAPI deploy daemon" and "Server-ID configuration" you can ignore on a normal single-server installation. The first concerns only the installation of external "Ex-Apps" via a Docker daemon, the second only setups spread across several PHP servers. You need neither here – that's why they stay notices and not warnings.

Step 3: Set the HSTS security header via Traefik

The third warning is the most important: the Strict-Transport-Security header (HSTS) is missing. It instructs the browser to address this domain exclusively over HTTPS – even when someone types http:// or an attacker tries to redirect the connection. Without HSTS, a small time window for downgrade attacks stays open.

Because our Nextcloud sits behind Traefik, we set the header in the proxy, not in Nextcloud – that's where it belongs, since Traefik terminates the TLS. In the compose.yaml of your Nextcloud (from part 1), add the middleware nc-secure and attach it to the router. Concretely, two places change in the labels block of nc-app.

First, extend the router line with nc-secure:

      - "traefik.http.routers.nc.middlewares=nc-dav,nc-secure"

Second, define the header middleware (right by the other nc-app labels):

      - "traefik.http.middlewares.nc-secure.headers.stsSeconds=15552000"
      - "traefik.http.middlewares.nc-secure.headers.stsIncludeSubdomains=true"

stsSeconds=15552000 is 180 days – the minimum value Nextcloud requires. Apply the change and reload only the app container:

docker compose up -d nc-app

After a few seconds, check from your own machine that the header is really delivered:

curl -sS -I https://cloud.YOUR_DOMAIN/ | grep -i strict-transport

You should see exactly this:

strict-transport-security: max-age=15552000; includeSubDomains

In the admin overview the HTTP-header warning thus turns green: "Your server is correctly configured to send security headers." The remaining headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy …) Nextcloud delivers itself – only HSTS had to come from the proxy.

⚠️ preload is a one-way street

stsIncludeSubdomains=true extends the HTTPS requirement to all subdomains of cloud.YOUR_DOMAIN (not to siblings like www.YOUR_DOMAIN – the header always applies only to the host that delivers it). Deliberately not set is stsPreload=true: with it you'd signal that you want the domain entered into the browsers' HSTS preload list – and such an entry can only be undone with weeks of lead time. If you ever deliberately want that: the preload list only accepts max-age ≥ 31536000 (1 year) – with the 15552000 above the flag would be ineffective anyway. Only set preload when really every service under the domain permanently speaks HTTPS; the header is fully functional without it.

Step 4: Set up email sending

Without working mail sending, Nextcloud can send no password resets, no share notifications and no security warnings – and the "Email test" notice stays. We catch up on that.

Open Administration → Basic settings and scroll to the "Email server" section. Enter your mail provider's credentials:

Send mode: SMTP
Encryption: SSL/TLS (port 465) or STARTTLS (port 587) – never unencrypted
From address: e.g. cloud @ YOUR_DOMAIN
Server address: host and port of your provider
Authentication: enable and store username/password

At the top, under Personal information, enter an email address for your admin account (the test mail goes there). Then click "Send test email". If the mail arrives, Nextcloud confirms it with a green message:

💡 App password instead of account password

If your mail provider itself uses two-factor authentication (Gmail, Mailbox.org, many others), your normal login password does not work here. Create a dedicated app password in your provider's account and enter that. It can also be revoked specifically without changing your main password.

Step 5: Enforce two-factor authentication

A stolen password is the most common way accounts get taken over. A second factor (a time-based code from an authenticator app, TOTP) makes the password alone worthless. Nextcloud already brings the matching provider – we just have to enable it and make it mandatory.

First enable the TOTP app (it's included):

docker exec -u www-data nc-app php occ app:enable twofactor_totp

On current images it is active out of the box, in which case the command only answers:

twofactor_totp already enabled

That's not an error – "available" simply isn't "mandatory" yet. That's exactly why the overview keeps showing the notice until we switch on the requirement in a moment.

Each user then sets up their second factor themselves – under Personal settings → Security → "TOTP (Authenticator app)". On enabling, Nextcloud shows a QR code you scan with an app like Aegis, andOTP or Google Authenticator. Additionally, the app "Two-Factor Backup Codes" is recommended – the one-time codes save you if the phone is lost.

So that nobody "forgets" the safeguard, you enforce 2FA for the administrators. On the web you find that under Administration → Security → "Enforce two-factor authentication", on the command line it works like this:

docker exec -u www-data nc-app php occ twofactorauth:enforce --on --group=admin

🛑 Don't lock yourself out

As soon as enforcement is active, every member of the group must set up a second factor on the next login. So set up your own second factor first and keep the backup codes safe before you arm the requirement. If something does go wrong, you lift the enforcement again via the command line: docker exec -u www-data nc-app php occ twofactorauth:enforce --off. A single stuck factor you remove with … php occ twofactorauth:disable USER totp.

Step 6: Brute-force protection with real IPs – basis for Fail2ban

Nextcloud throttles failed logins out of the box: after several failed attempts it delays further requests from the same IP. But this protection stands and falls with Nextcloud seeing the real client IP – and not the internal IP of Traefik. That's exactly what the TRUSTED_PROXIES setting from part 1 does.

Whether it works you see under Administration → Security in the "brute-force allow list" box (in the screenshot above). There stands your current, correctly recognized public IP:

Your current IP address is recognized as "YOUR_IP". This address is currently not throttled.

If a 172.x.x.x address from the Docker network appears there instead, TRUSTED_PROXIES isn't taking effect – then the brute-force protection would lump all users together and, in doubt, ban Traefik itself. In that case, back to part 1, step 2/3.

Hard bans with Fail2ban. The built-in throttling only delays; whoever wants to really ban attackers combines Nextcloud with Fail2ban. Nextcloud logs every failed attempt in the JSON log – and thanks to TRUSTED_PROXIES with the real IP:

{"level":2,"time":"2026-07-18T08:14:05+00:00","remoteAddr":"203.0.113.47","user":"--","app":"no app in context","method":"POST","url":"/login","message":"Login failed: USER (Remote IP: 203.0.113.47)"}

This log lives in the Nextcloud volume. You find the path on the host like this:

docker inspect -f '{{ range .Mounts }}{{ if eq .Destination "/var/www/html" }}{{ .Source }}{{ end }}{{ end }}' nc-app

Below it is the file data/nextcloud.log. At that you point a Fail2ban filter that matches on remoteAddr, plus a jail following the pattern from the Fail2ban tutorial. This way, after a few failed attempts, the attacker IP goes straight into the firewall – before the request even reaches Nextcloud.

Step 7: Check caching & PHP – the performance foundation

Finally, we make sure the performance basis is in place. Much of this part 1 already set up automatically via the REDIS_HOST variable – checking doesn't hurt anyway, because this is exactly where a Nextcloud gets sluggish or snappy.

Nextcloud uses three cache roles. Check all three:

docker exec -u www-data nc-app php occ config:system:get memcache.local
docker exec -u www-data nc-app php occ config:system:get memcache.distributed
docker exec -u www-data nc-app php occ config:system:get memcache.locking

Expected:

\OC\Memcache\APCu
\OC\Memcache\Redis
\OC\Memcache\Redis

Local cache (APCu): keeps frequently used data in the RAM of the PHP process – the most noticeable accelerator in everyday use.
Distributed cache (Redis): shares cache data across processes, important once the app and cron containers interact.
File locking (Redis): prevents two accesses from changing the same file simultaneously and corrupting it. The reason we built in Redis at all in part 1.

If the interplay fits, docker exec -u www-data nc-app php occ setupchecks reports the line ✓ Memcache: Configured. (Passed checks aren't shown by the web overview – only warnings and notices appear there, which is why you check this via CLI.)

OPcache – PHP's bytecode cache – is already sensibly preconfigured in the official nextcloud image (including opcache.interned_strings_buffer=32). So you don't have to adjust anything here; the formerly notorious OPcache warning no longer appears at all with current images. You can check it if needed like this:

docker exec -u www-data nc-app php -i | grep opcache.interned_strings_buffer

With that, the overview is warning-free:

💡 Generate previews proactively

If your users store many photos, the app "Preview Generator" is worth it: an occ cron job generates thumbnails in advance instead of computing them slowly on the fly on first open. If you add it, limit the maximum preview size via occ config:system:set preview_max_x --value=2048 (and preview_max_y), otherwise the storage demand grows quickly.

When things go wrong

After the Traefik restart, the HSTS header doesn't appear in the curl output. Usually the middleware isn't on the router. Check that the line traefik.http.routers.nc.middlewares names both middlewares (nc-dav,nc-secure) and that the two nc-secure header labels are in the nc-app block. Then docker compose up -d nc-app. Traefik only picks up changed labels when recreating the container.

The email test fails ("There was a problem sending the email"). Almost always port/encryption or authentication. Combine SSL/TLS with port 465 or STARTTLS with port 587 – not crosswise. If your provider uses 2FA, you need an app password (see step 4). Details are in the Nextcloud log: docker exec -u www-data nc-app php occ log:tail 20.

You can't get in yourself after enforcing 2FA. You hadn't set up a second factor yet. Lift the requirement via the command line, set up your factor calmly and arm it again afterwards: docker exec -u www-data nc-app php occ twofactorauth:enforce --off.

In the brute-force box a 172.x.x.x address appears instead of your real IP. TRUSTED_PROXIES doesn't match the actual proxy subnet. Determine it with docker network inspect proxy -f '{{(index .IPAM.Config 0).Subnet}}' and enter the value in the nc-app environment (part 1, step 2). Otherwise the brute-force protection bans the proxy in an emergency and thus all users.

After a reboot, Nextcloud reports "Redis went away" or gets very slow. The app container started before Redis. Make sure nc-redis is in depends_on (part 1) and runs with restart: unless-stopped – then Docker catches the start-order case itself.

Maintenance & backups

Check the overview after every update. New Nextcloud versions bring new checks. After every upgrade take a look at Administration → Overview or run occ setupchecks – this way you catch new warnings early.
Use the official security scan regularly. The Nextcloud Security Scan checks your domain from outside and assigns a grade. With HSTS and current versions, A/A+ is the realistic target; if the grade drops, an update is usually overdue.
Keep an eye on second factors. Keep the backup codes separate from the phone. If a user loses their device, you remove their factor with occ twofactorauth:disable USER totp, after which they set it up anew.
Clean up app passwords. Every connected client (desktop, phone) gets its own app password. Under Personal settings → Security you see all devices and can specifically revoke individual ones on loss.
The hardening replaces no backup. All of this protects against foreign access, not against data loss. The consistent backup of a database dump and data directory stays mandatory – see the maintenance section in part 1 and backups with Restic. Honest about the effort: firmly plan the monthly update pass with a quick look at the overview – then your cloud stays green permanently.

This post first appeared on serverkueche.de.

First steps with a netcup VPS

serverkueche.de — Sat, 26 Sep 2026 06:07:02 +0000

You've ordered your first netcup server – congratulations! Before we fire up the kitchen, let's set the system up cleanly.

What are we building?

By the end of this tutorial, your VPS runs a current Debian 13 with all security updates, and you work with your own user with sudo rights instead of permanently as root. That's the foundation for all the other recipes in the Serverküche – from hardening SSH to your first application.

💡 Tip

All commands are written for Debian 13. On Ubuntu they work almost identically.

Prerequisites

An ordered netcup server with the credentials from your customer account
A terminal on your machine (Linux/macOS) or an SSH client like PuTTY (Windows)

Not sure which server size you even need? The server calculator estimates the RAM and CPU you'll need for your planned services and suggests a matching netcup plan. How the plans differ – VPS, VPS Lite or root server – is covered in the server comparison.

Step by step

Step 1: Log in via SSH

Log in with your server's IP address as root. You'll find the IP and the password in the credentials from your customer account:

ssh root@YOUR_SERVER_IP

On the very first login, SSH asks whether you want to trust the server:

The authenticity of host 'YOUR_SERVER_IP (YOUR_SERVER_IP)' can't be established.
ED25519 key fingerprint is SHA256:...
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Answer yes – your machine remembers the server from now on. After that you land on a prompt like root@v2200123456789012345:~#: netcup assigns a v plus a long number as the hostname, so yours will look different.

Step 2: Update the system

Freshly delivered images are rarely up to date. So the first thing to do is fetch all updates – security updates in particular should never wait:

apt update && apt upgrade -y

apt update fetches the current package lists, apt upgrade -y installs all available updates without prompting. Debian 13 ships apt 3 for this: instead of the long package list of earlier versions you get the affected packages in columns and a terse summary below them:

Upgrading:
  bsdutils  libblkid1  liblastlog2-2  libmount1  libsmartcols1  libuuid1  login  mount  util-linux

Summary:
  Upgrading: 9, Installing: 0, Removing: 0, Not Upgrading: 0
  Download size: 2223 kB
  Space needed: 33.8 kB / 239 GB available

How many packages pile up on your machine depends on how old the delivered image is – the line that matters is Summary:, which tells you at a glance what gets upgraded, installed and removed.

⚠️ Warning

Reboot the server after a kernel update (reboot) so the changes take effect. On a fresh Debian there's no automation for this yet – the safest bet is a reboot right after the first big update. Debian does not create the marker file /var/run/reboot-required (which indicates a pending reboot) on kernel updates by default – the hook that creates it only arrives with the package from automatic updates.

Step 3: Create a sudo user

Don't work as root permanently: a typo with full rights can wreck the entire system, and having your own user is the prerequisite for disabling root login completely later. Create a user – we'll call it koch ("cook") here, but you can pick any name:

adduser koch

You'll be asked for a password and a few optional details (you can skip the details with Enter). After that, give the user sudo rights:

usermod -aG sudo koch

Step 4: Test the new user

Check in a new terminal session (keep the root session open!) that login and sudo work:

ssh koch@YOUR_SERVER_IP
sudo whoami

After entering your password, sudo whoami should return root. From now on you continue working with this user.

When things go wrong

ssh: connect to host … port 22: Connection timed out. Usually the IP was mistyped or the server isn't fully provisioned yet. Check the IP in your customer account and whether the server is shown as "online" there. Wait a few minutes after ordering.

Permission denied, please try again on root login. Wrong password – often a copy-paste issue with invisible trailing spaces, or a different keyboard layout. Copy the password without surrounding spaces directly from the credentials.

WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!. The server was reinstalled and has a new host key – SSH rightly raises the alarm. If you reinstalled it, remove the old entry with ssh-keygen -R YOUR_SERVER_IP and reconnect. If you didn't reinstall, investigate before you connect.

sudo: command not found as the new user. On minimal images the package is sometimes missing. Install it as root: apt install sudo. Then check that the user is in the group: groups koch must contain sudo – otherwise repeat step 3 and log out and back in once.

Maintenance & backups

Updates: You should schedule sudo apt update && sudo apt upgrade at least weekly – or automate security updates with unattended-upgrades.
Snapshots: Create a snapshot in the netcup Server Control Panel (SCP) before bigger changes. It's your safety line while you don't have a proper backup strategy yet – but a snapshot does not replace a backup outside the server.
Credentials: Keep the root password safe (password manager). Via the VNC console in the SCP you can still reach the server even when SSH is stuck.

You'll find both in the server overview of the SCP: the VNC console is under the "Screen" tab (called "Bildschirm" if your panel is set to German), and the remaining snapshot quota is shown in the status block.

This post first appeared on serverkueche.de.

The essential terminal commands for your server

serverkueche.de — Fri, 25 Sep 2026 05:55:48 +0000

Whoever runs their own server lives (at least occasionally) in the terminal. This article is your toolbox: the commands you really need – once for debugging when the server suddenly crawls, and once for daily work. Not a dry manual, but the selection that has proven itself in everyday use.

What are we building?

No setup this time, but a battle-tested reference. We go through two toolboxes:

Debugging performance – when the server gets sluggish: top, htop, btop, ctop, iotop, nload, ncdu and kill. With these you find out what is eating the resources, and intervene.
Daily work – the commands you type constantly: ls, cd, nano, wget, curl, dig, tmux, history, sudo, scp, rsync, dd and ssh-agent.

All examples ran on a real Debian 13 server; the outputs shown are real. The interactive full-screen tools (top, htop, btop, ctop, nload, ncdu) we additionally show you in a picture, so you recognize the interface – the copyable single commands stay deliberately as text to type out.

Prerequisites

A server you can log into via SSH – e.g. from First steps with the netcup VPS.
A user with sudo rights to install packages.
No fear of the command line – we'll shed that together here.

💡 Install first, then use

top, kill, ls, curl, dig, scp, dd and ssh-agent are usually already there on Debian. The more comfortable tools you install in one go:
sudo apt update && sudo apt install -y htop btop iotop nload ncdu tmux rsync
ctop is not in the package sources – we'll fetch it directly as a ready-made file in the corresponding section.

Step by step

First the debugging toolbox – the commands for the moment the server is stuck. Then the tools for daily work.

top and htop: the first look

top is present on every Linux and shows the running processes live, sorted by CPU load. For a quick look it's enough:

top

At the top you see load average, memory and the process list. The most important – and most cryptic – line is %Cpu(s). Its eight values tell you what the CPU is busy with:

us (user) – normal programs in userspace (your apps, container processes).
sy (system) – the kernel itself (system calls, drivers, network stack).
ni (nice) – userspace processes with lowered priority (started via nice).
id (idle) – idling. High id = plenty of headroom, low id = the CPU is maxed out.
wa (io-wait) – the CPU is waiting for the disk. Consistently high means: your bottleneck is the disk, not the compute power (then continue with iotop, see below).
hi (hardware interrupts) – time for hardware interrupts (devices reporting in).
si (software interrupts) – time for software interrupts (often network processing).
st (steal) – only on VPS/virtual servers: compute time the hypervisor "stole" from your VM because other guests ran on the same host. Consistently high st means the host is oversubscribed – a reason to question the plan or provider.

With q you quit the view. But top is spartan – the successor htop is much more readable: colored bars per CPU core, mouse operation and easy sorting.

htop

At the top, watch the CPU bars (one bar per core) and the Mem bar. In the list you sort with F6 by a column (e.g. %MEM), search a process with F3 and end it with F9. Exactly here you find the service that's currently slowing everything down.

btop: the fancy system monitor

btop (version 1.3.2 in the test) goes one step further: CPU, memory, disk I/O and network in one pretty, mouse-operable dashboard – all at a glance.

btop

For the daily health check, btop is our favorite because you see network and disk right along and don't need several tools. Quit with q. Esc does not quit – it opens the main menu (options, help, quit); a second Esc closes it again.

ctop: monitor Docker containers live

If your server runs with Docker, you want to know which container draws how much. htop only shows processes – ctop shows containers. It's not in the package sources, so we fetch the ready-made file (version 0.7.7):

sudo curl -L -o /usr/local/bin/ctop https://github.com/bcicen/ctop/releases/download/v0.7.7/ctop-0.7.7-linux-amd64
sudo chmod +x /usr/local/bin/ctop

We deliberately download the file with a full path and make it executable – no blind curl … | bash. Then you simply start it:

ctop

You get one row per container with CPU, RAM, network and disk I/O, updated live. With Enter on a container you open a menu to stop, restart or show logs – ideal when a single service runs amok.

iotop and nload: disk and network

Sometimes the problem isn't the CPU but the disk. iotop shows which process is currently reading and writing (needs root):

sudo iotop

Sorted by write/read rate you immediately spot the I/O hog – often a backup, a database or a log gone out of control. For the network, nload does the same: incoming and outgoing throughput in real time, with a small graph.

nload

With the arrow keys you switch between the network interfaces (or you specify the desired one directly, e.g. nload eth0). Handy to check whether a large upload is running – or whether unexpected traffic is clogging the connection.

ncdu: find the storage hog

The most common cause of a broken server is a full disk. The rough overview is given by df:

df -h /

Filesystem      Size  Used Avail Use% Mounted on
/dev/vda4       251G   11G  230G   5% /

df tells you that it's getting tight, but not where. That's what ncdu does – an interactive directory analyzer that shows you which folders take up the space:

sudo ncdu /

ncdu scans and lists the largest directories at the top. With the arrow keys you navigate in, with d you delete specifically (careful!). This is how you find the huge log file or the forgotten backup folder in seconds.

kill: end hanging processes

If in htop or top you found the PID (process ID) of the culprit, you end it with kill:

kill 12345

That sends a polite "please quit" (signal TERM) that allows the process to clean up properly. If it doesn't react, the hard variant follows:

kill -9 12345

-9 (signal KILL) ends immediately and mercilessly. Use it only as a last resort – the process can no longer save any data. If you only know the name, pkill nginx helps, which hits all matching processes.

That ends the debugging box. Now the tools for daily work.

ls, cd and nano: navigate and edit

The basic framework of every terminal session. cd changes the directory, ls lists the contents. Most useful is ls with options:

ls -lh

-l shows details (permissions, owner, size, date), -h makes the sizes readable (4.0K instead of 4096). With ls -la you also see hidden files (those starting with .). For editing configuration files, nano is the most beginner-friendly editor:

sudo nano /etc/hosts

At the bottom are the shortcuts: Ctrl+O saves ("Write Out"), Ctrl+X quits. No cryptic vim – exactly right to quickly change a line.

wget, curl and dig: fetch data and check the network

wget downloads files – ideal for downloads:

wget https://YOUR_SOURCE/file.tar.gz

curl is the Swiss Army knife for HTTP. Especially valuable: viewing only the response headers to check what a server returns:

curl -I https://example.com

HTTP/2 200
date: Sat, 18 Jul 2026 09:55:49 GMT
content-type: text/html
server: cloudflare

Status 200 means "all ok", 301/302 are redirects, 404 "not found". For DNS questions, dig is the tool – e.g. to check whether your domain points to the right server:

dig +short example.com A

172.66.147.243
104.20.23.154

+short delivers only the pure answer (the IP address). Without the switch you see the full report including response time – indispensable before Traefik can fetch a certificate (see connecting a domain to your server).

tmux: the session that never breaks off

The most important tool for remote maintenance. If you start a long command (update, backup, compiling) over SSH and your connection breaks, normally your process dies too. tmux solves that: it keeps your session alive on the server, whether or not you're connected.

tmux

You land in a tmux session and work normally. If the connection breaks off (or you deliberately close with Ctrl+B, then D – "detach"), everything keeps running. On the next login you attach again:

tmux attach

tmux can do much more (split windows, several panes). The shortcuts all begin with the "prefix" Ctrl+B. A compact overview of all shortcuts is on the tmux cheatsheet – worth printing out.

scp, rsync and dd: copy and transfer

scp copies files over SSH – from the local machine to the server and back:

scp file.txt YOUR_USER@YOUR_SERVER_IP:/opt/target/

For anything beyond single files, rsync is superior: it transfers only changes, can resume, and synchronizes entire directory trees. Always test first with -n (dry run) before you really copy:

rsync -avn /source/ /target/

sending incremental file list
created directory /target
./
file.txt
sub/
sub/more.txt

sent 136 bytes  received 59 bytes  390.00 bytes/sec
total size is 11  speedup is 0.06 (DRY RUN)

-a preserves permissions and timestamps, -v is verbose, -n only shows what would happen. If it looks good, you leave out the -n. rsync also works over SSH (rsync -av /source/ user@server:/target/) and is thus the backbone of many backup scripts.

dd, finally, copies raw, block by block – e.g. to write a boot image onto a USB stick. It's powerful and merciless (more on that below):

sudo dd if=image.iso of=/dev/sdX bs=4M status=progress

history, sudo and ssh-agent: the little helpers

history shows your most recently typed commands with a number – handy to find a long command from yesterday again:

history | grep docker

With !123 you run the command with number 123 again, with Ctrl+R you search interactively backwards. sudo runs a single command with administrator rights – always only as much privilege as needed:

sudo systemctl restart docker

ssh-agent, finally, remembers your SSH key password for the session so you don't have to retype it on every connection:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

After that you log in without entering the passphrase again – until you log out. More on secure SSH keys is in hardening SSH.

When things go wrong

dd overwrote the wrong disk – data gone. dd doesn't ask and isn't mockingly called "disk destroyer" for nothing. Check the target (of=) always beforehand with lsblk, and never confuse sda with sdb. There's no undo – when in doubt, read it three times.

kill -9 ended a service, but the database is corrupted afterwards. -9 gives the process no chance to close cleanly. Always first use kill without -9 and give the process a few seconds. Only when it really hangs does the hard variant follow.

rsync copied (or deleted) much more than expected. The trailing slash decides: rsync -a /source/ copies the contents of source, rsync -a /source copies the folder along with it. And --delete deletes everything in the target that's missing in the source. Test with -n first, always.

A tool reports "command not found". The package isn't installed. Install it (see tip box above) or check the name. Some tools like iotop additionally need sudo to see any data at all.

After tmux, on the next login "everything is gone". You started a new session instead of attaching. tmux ls lists running sessions, tmux attach -t 0 attaches you to the first. Just tmux on its own creates a fresh one every time.

Maintenance & backups

These commands are your backup tool. rsync, scp and dd are the foundation of every backup strategy. For real, encrypted off-site backups you build on this – see backups with Restic, which internally uses the same logic.
Help yourself. Every command brings its own docs: man rsync opens the manual, rsync --help shows the options compactly. For brief practical examples tldr is worth it, which instead of pages-long man pages shows the three or four most common use cases. There is no package called tldr in Debian 13 (apt answers with Package 'tldr' has no installation candidate) – the command lives in the tealdeer package. Install it with sudo apt install -y tealdeer, then run tldr --update once (it downloads the example collection, otherwise you only get Page cache not found). After that, tldr rsync shows the typical invocations on half a page.
Stay current. Keep the tools fresh via sudo apt update && sudo apt upgrade; ctop you update by downloading the new release file again. The versions are named deliberately (state of the test) – newer ones generally work just the same.
Honest about the effort: you don't have to memorize this reference. Bookmark it and come back when the server is stuck. After a few weeks the most important moves stick on their own.

This post first appeared on serverkueche.de.

Hardening SSH access

serverkueche.de — Fri, 25 Sep 2026 05:55:29 +0000

After the initial setup we harden the SSH access – the most important door to your server.

What are we building?

By the end you log in with an SSH key instead of a password, and neither root login nor password login is possible from outside. This makes the automated password-guessing attacks that hit every publicly reachable server around the clock run completely into the void. Tested with OpenSSH 10.0p2 on Debian 13.

Prerequisites

A set-up server with a sudo user
Access to the VNC console in the netcup SCP as a safety line in case you lock yourself out

Step by step

Step 1: Generate an SSH key pair

If you don't have a key yet, generate an Ed25519 key pair on your own machine (not on the server!):

ssh-keygen -t ed25519

You can accept the suggested storage location with Enter. Set a passphrase – it protects the key if your machine falls into the wrong hands:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/YOUR_USER/.ssh/id_ed25519):
Created directory '/home/YOUR_USER/.ssh'.
Enter passphrase for "/home/YOUR_USER/.ssh/id_ed25519" (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/YOUR_USER/.ssh/id_ed25519
Your public key has been saved in /home/YOUR_USER/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:... koch@your-laptop

The Created directory line only appears if you didn't have a ~/.ssh yet. After that comes the "randomart image", a small ASCII graphic of the fingerprint – you can ignore it. What matters are the two files: ~/.ssh/id_ed25519 (private, stays with you) and ~/.ssh/id_ed25519.pub (public, goes on the server).

Step 2: Transfer the public key

ssh-copy-id appends your public key to the ~/.ssh/authorized_keys file of your server user – with the correct file permissions:

ssh-copy-id koch@YOUR_SERVER_IP

The server asks for the user's password one last time here – after this it won't again:

/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/home/YOUR_USER/.ssh/id_ed25519.pub"
/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
koch@YOUR_SERVER_IP's password:

Number of key(s) added: 1

Now try logging into the machine, with: "ssh 'koch@YOUR_SERVER_IP'"
and check to make sure that only the key(s) you wanted were added.

Number of key(s) added: 1 is the success message. On a second run you get WARNING: All keys were skipped because they already exist on the remote system. instead – then the key is already in place. Test right afterwards that key login works:

ssh koch@YOUR_SERVER_IP

You should now be logged in without a server password (only the passphrase of your key may be requested). Only once that works do we continue – in the next step we disable password login.

Step 3: Disable password login and root login

Open the SSH server configuration:

sudo nano /etc/ssh/sshd_config

Set (or uncomment) these two lines:

PermitRootLogin no
PasswordAuthentication no

PermitRootLogin no blocks direct root login completely, PasswordAuthentication no allows only key logins.

⚠️ Warning

On cloud images there are often extra files under /etc/ssh/sshd_config.d/ that override these settings. Check with grep -r PasswordAuthentication /etc/ssh/sshd_config.d/ and adjust any matches as well.

Step 4: Test the configuration and restart SSH

Check the configuration for syntax errors before you restart – a typo would otherwise take the SSH service down:

sudo sshd -t

No output means: all good. Then apply it:

sudo systemctl restart ssh

🛑 Caution

Test key login now in a second terminal session before you close the first – otherwise you might lock yourself out.

To verify: sudo systemctl status ssh should show active (running), and a login attempt as root must now be rejected with Permission denied (publickey).

When things go wrong

SSH keeps asking for the password despite ssh-copy-id. Usually the file permissions on the server are wrong: SSH ignores authorized_keys if group or others may write to ~/.ssh. The log on the server (sudo journalctl -u ssh --since -5min) then shows Authentication refused: bad ownership or modes for directory /home/koch/.ssh. Fix it with chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys, and also check that you're connecting with the right user (koch@…, not root@…).

Permission denied (publickey) – and you can't get in at all anymore. Password login was disabled before the key worked. No drama: open the VNC console in the netcup SCP, log in locally there, set PasswordAuthentication yes, restart SSH and start again at step 2.

After the restart the SSH service no longer starts. Syntax error in the sshd_config – a mistyped PasswordAuthentification is enough (that's why you always run sshd -t before restarting). Log in via the VNC console; sudo sshd -t then names file, line and option: /etc/ssh/sshd_config: line 125: Bad configuration option: PasswordAuthentification, followed by /etc/ssh/sshd_config: terminating, 1 bad configuration options.

The settings seem to take effect, but password login still works. A file under /etc/ssh/sshd_config.d/ (often 50-cloud-init.conf) overrides your values. sudo sshd -T | grep -i passwordauthentication shows the actually effective setting – adjust matches in the extra files and restart SSH.

Maintenance & backups

Back up the private key: Without ~/.ssh/id_ed25519 you can only reach the server via the VNC console. Back up the key encrypted (e.g. in a password manager) or add a second key from another device to authorized_keys.
Keep an eye on logins: sudo journalctl -u ssh --since today shows you all login attempts. OpenSSH 10 logs the individual connections under the name sshd-session, for example as Connection closed by authenticating user root 203.0.113.10 port 50718 [preauth]. Failed attempts on port 22 are normal and, thanks to the key requirement, harmless – you can automatically ban such bots later with Fail2ban.
Updates: OpenSSH gets its security updates through the normal apt upgrade – so keep the server up to date, ideally automated.

This post first appeared on serverkueche.de.

Connecting a domain to your server (DNS basics)

serverkueche.de — Fri, 25 Sep 2026 05:55:07 +0000

So far you only reach your server via its IP address. For real services you need a domain – and not just for looks: without a publicly resolving domain, Traefik can't fetch a TLS certificate from Let's Encrypt later. This tutorial connects your domain to the server and explains the three terms beginners get stuck on: A record, TTL and propagation.

What are we building?

By the end, your domain (YOUR_DOMAIN) points to your server IP via an A record (IPv4) and – if your server has IPv6 – an AAAA record, including www. You can verify this yourself with dig and understand why a change isn't always visible immediately. Optionally you also set up reverse DNS (PTR) – important as soon as your server sends emails. This lays the foundation for all publicly reachable services.

Prerequisites

A set-up server with a known public IP address
A registered domain (at netcup, another registrar, or included in your hosting package)
Access to the DNS management of your domain (at netcup: the customer account CCP)

Step by step

Step 1: Find the server IP

Connect via SSH and display the public IP addresses:

ip -4 addr show scope global
ip -6 addr show scope global

The IPv4 address is after inet (e.g. 203.0.113.10), any IPv6 address after inet6 (does not start with fe80::, that would only be link-local). If Docker is already running on the server, private addresses from 172.16.0.0/12 on docker0/br-… show up as well – container networks that don't belong in DNS. You need the one on eth0. Alternatively you'll find both in the netcup Server Control Panel (SCP) in the server overview.

💡 Tip

Note down both addresses. If your server has no global IPv6 address, you simply don't create an AAAA record later – that's perfectly fine.

Step 2: Create A and AAAA records

Open the DNS management of your domain. There you enter resource records – the mapping of names to addresses. Create:

Type	Host / Name	Value
`A`	`@`	`YOUR_SERVER_IPV4`
`A`	`www`	`YOUR_SERVER_IPV4`
`AAAA`	`@`	`YOUR_SERVER_IPV6` (only if available)
`AAAA`	`www`	`YOUR_SERVER_IPV6` (only if available)

@ stands for the domain itself (YOUR_DOMAIN), www for the subdomain www.YOUR_DOMAIN.
A points to an IPv4 address, AAAA to an IPv6 address. The name "AAAA" comes from an IPv6 address being four times as long as an IPv4 address.
For individual services you can later create specific subdomains (e.g. cloud, git) – following the same pattern.

⚠️ Warning

For A/AAAA enter only the bare IP – no http://, no slash, no port. For redirects to other names there would be CNAME, but for "domain → own server" the A/AAAA record is the right and most robust way.

Step 3: Understand TTL and propagation

Every record has a TTL (Time To Live) in seconds – e.g. 3600 (one hour). It tells resolvers worldwide how long they may cache the answer before asking again.

From this follows the notorious propagation: if you change a record, some resolvers see the new value immediately, others only after the old TTL expires. "DNS propagating" means nothing more than these caches expiring one by one. In everyday use, reckon with minutes up to an hour, occasionally longer.

💡 Before planned migrations

If you want to change an IP soon, lower the TTL one or two days beforehand to e.g. 300 (5 minutes). Then the actual switch takes effect almost immediately later. Raise it again after the migration.

Step 4: Verify with dig

Wait a few minutes, then check from your own machine where the domain points. dig is the standard tool for that; on Debian and Ubuntu it lives in the bind9-dnsutils package:

sudo apt install bind9-dnsutils

Then query the A record:

dig +noall +answer YOUR_DOMAIN A

This is what a correct answer looks like (example for this site's real domain):

serverkueche.de.    3600    IN  A   152.53.246.100

The number 3600 is the remaining TTL – it counts down while the answer sits in a cache – followed by the target IP. For IPv6, query the AAAA record the same way:

dig +short YOUR_DOMAIN AAAA

2a0a:4cc0:c0:939c::1

+short returns just the bare values, for IPv4 too:

dig +short YOUR_DOMAIN

152.53.246.100

If your correct server IP appears, the domain is connected. Also check www:

dig +short www.YOUR_DOMAIN

With its own A record for www (step 2), exactly one line with the same IP as the apex comes back. If www instead points to the main domain via CNAME – also common and perfectly fine – dig +short prints the CNAME target first and then its IP, as on this site:

serverkueche.de.
152.53.246.100

Either way, what counts is the last line: it has to carry your server's IP.

Step 5: Set reverse DNS (PTR) – optional but recommended

The A record answers the question "Which IP belongs to this name?". Reverse DNS – the PTR record – answers the opposite direction: "Which name belongs to this IP?". For a plain website you don't need this. But as soon as your server sends emails – even if only notifications from Nextcloud, Gitea & co. – it's practically mandatory: the receiving mail servers reject mail from IPs without a matching PTR or treat it as spam. The PTR is only the first of four DNS building blocks – SPF, DKIM and DMARC join it as soon as you really send mail; those are covered by the
email deliverability tutorial.

The crucial difference from the previous records: you enter the PTR not at your DNS provider, but where the IP address is managed – i.e. at your VPS provider. At netcup you'll find it in the Server Control Panel (SCP) in the Netzwerk (Network) tab – there's a Reverse DNS field per address (IPv4 and IPv6). Enter a hostname there that points to the same server via an A record – either directly YOUR_DOMAIN or your own name like server.YOUR_DOMAIN (shown as an example in the screenshot) – and click Save.

💡 Forward and reverse must match

For the PTR to count as "clean" (forward-confirmed rDNS, FCrDNS), the name entered there must point back to the same IP via an A/AAAA record. For YOUR_DOMAIN and www this is already satisfied by step 2. If you use your own name like server.YOUR_DOMAIN, first create an A/AAAA record for it as in step 2 – otherwise the reverse direction doesn't match.

If you have IPv6, set the PTR for both addresses – IPv4 and IPv6. The IPv6 PTR is easily forgotten, and that's exactly what some mail servers trip over after all.

You can check the result with dig and the -x option (reverse lookup) – for IPv6 do the same with YOUR_SERVER_IPV6:

dig +short -x YOUR_SERVER_IPV4

Exactly the hostname you just entered should come back – with a trailing dot:

server.YOUR_DOMAIN.

If nothing comes back, or still the provider's default name (at netcup something like v220….bestsrv.de), the PTR is not (correctly) set yet – or, as with every DNS entry, the change still needs some time.

When things go wrong

dig returns no IP or a wrong (old) one. Usually still propagation. Query a public resolver specifically to bypass your local cache: dig +short YOUR_DOMAIN @1.1.1.1. If it already shows the correct value, only your local/provider cache hasn't expired yet – wait.

The domain resolves, but to the wrong IP – e.g. a registrar's parking page. Often an old A record or a redirect/parking setting still exists. Remove contradictory entries; per name and type there should be exactly one value (deliberate exceptions aside).

IPv4 works, IPv6 (AAAA) leads to timeouts. You entered an AAAA record even though the server has no working IPv6 address. Browsers then prefer IPv6 and run into a timeout. Remove the AAAA record until the server really supports IPv6.

In some interfaces the value is stored with a trailing dot (YOUR_DOMAIN.) and you're unsure. The trailing dot (root of the DNS hierarchy) is normal and correct – many DNS managers add it automatically. No reason to worry.

Emails sent from the server land in spam or are rejected (the mail log shows e.g. does not resolve to address or no PTR record). The reverse-DNS entry (PTR) is missing or doesn't match the sender hostname. Set the PTR as described in step 5 at the VPS provider and make sure it points to the same name that also resolves via the A/AAAA record.

Maintenance & backups

DNS is low-maintenance. Once set correctly, the A/AAAA record rarely changes. Exception: a server migration – then the TTL trick from step 3 applies.
Document your records. Keep track somewhere of which names (@, www, cloud, …) point to which IP. With several services you otherwise lose the overview.
No classic backup needed, but a screenshot or export of your DNS zone doesn't hurt in case you switch providers.
Carry reverse DNS along on an IP change. If the server gets a new IP (migration, new product), you have to reset the PTR at the VPS provider – it's tied to the IP, not the domain.

This post first appeared on serverkueche.de.

Installing Docker on Debian

serverkueche.de — Fri, 25 Sep 2026 05:54:05 +0000

Docker is the foundation for almost every application tutorial in the Serverküche. We install it from the official Docker repository – not from the Debian package sources.

What are we building?

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

Prerequisites

A hardened server with a sudo user

Step by step

Step 1: Set up the repository key

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

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

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

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

Step 2: Add the Docker package source

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

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

Step 3: Install Docker

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

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

Check that the service is running:

sudo systemctl status docker

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

sudo docker run --rm hello-world

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

Finally, check which versions actually got installed – that's the information every bug report will ask you for:

docker --version
docker compose version

Docker version 29.7.2, build a7dcaa6
Docker Compose version v5.4.0

The exact patch numbers keep moving; what matters is that the Engine is on 29.x and Compose on v5.x – that's what the Compose recipes here build on.

Step 4: Use Docker without sudo

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

sudo usermod -aG docker $USER

💡 Tip

The group membership only takes effect after you log out and back in (end the SSH session and reconnect).

⚠️ Security note

Members of the docker group effectively have root rights on the server – only add your own admin user, no shared or unprivileged accounts.

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

When things go wrong

E: Package 'docker-ce' has no installation candidate. The package source from step 2 is missing or malformed – apt only knows the name from the Debian packages' dependencies and finds no package behind it. Check the contents of /etc/apt/sources.list.d/docker.list – it must contain your Debian version (e.g. trixie) – and then run sudo apt update again.

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock. The docker group membership hasn't taken effect yet. End the SSH session and reconnect; groups must then include docker. If not, repeat step 4.

Conflicts during installation with already-present packages. Another Docker variant is already installed (docker.io, podman-docker, …). Remove the old packages first: sudo apt remove docker.io docker-doc docker-compose podman-docker containerd runc – existing containers/images are preserved.

docker compose reports docker: unknown command: docker compose. The Compose plugin is missing – Docker was probably installed differently earlier. Run sudo apt install docker-compose-plugin. Note: the old docker-compose (with a hyphen) is a different, outdated tool.

Maintenance & backups

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

This post first appeared on serverkueche.de.

Setting up a firewall with UFW

serverkueche.de — Fri, 25 Sep 2026 05:53:26 +0000

By default, your server accepts connections on all open ports. A firewall turns that around: it blocks everything and only lets through what you explicitly allow. UFW ("Uncomplicated Firewall") does this with a few, readable commands – the perfect first line of defense.

What are we building?

By the end, UFW runs on your Debian 13 with the base rule "block all incoming", with only SSH (your access) plus HTTP/HTTPS (ports 80/443, which you'll need later for Traefik) open. Outgoing connections stay allowed. The key part: we proceed in a way that ensures you don't lock yourself out.

Prerequisites

A hardened server with a sudo user
You know which port your SSH runs on (default: 22)

Step by step

Step 1: Install UFW

sudo apt update
sudo apt install -y ufw

Check which version you got:

sudo ufw version

ufw 0.36.2
Copyright 2008-2023 Canonical Ltd.

Right after installation UFW is still inactive – and that's intended: a packet filter that goes live without any allowances would lock you out. sudo ufw status confirms it with Status: inactive.

Step 2: Define the base rules

First the default direction: deny everything incoming, allow everything outgoing.

sudo ufw default deny incoming
sudo ufw default allow outgoing

Default incoming policy changed to 'deny'
(be sure to update your rules accordingly)
Default outgoing policy changed to 'allow'
(be sure to update your rules accordingly)

These rules don't take effect yet – UFW is still inactive. So the exceptions come now, before we switch it on.

Step 3: Allow SSH – first, or you'll lock yourself out

🛑 Allow SSH first, then activate

If you enable UFW with the "deny incoming" rule without having allowed SSH first, the next command cuts your own connection – and you can no longer get in via SSH. This order is non-negotiable.

If your SSH runs on the default port 22 (and openssh-server is installed), there's a ready-made profile for it:

sudo ufw allow OpenSSH

If you changed the SSH port (e.g. to 2222), allow exactly that port instead:

sudo ufw allow 2222/tcp

Step 4: Allow HTTP and HTTPS

For the later reverse proxy with Traefik you need the web ports. Open them right away:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

UFW confirms each rule with Rules updated and Rules updated (v6) (the IPv6 variant).

Step 5: Activate the firewall and check it

Now switch it on:

sudo ufw enable

Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Check the result:

sudo ufw status verbose

Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), disabled (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
22/tcp (OpenSSH)           ALLOW IN    Anywhere
80/tcp                     ALLOW IN    Anywhere
443/tcp                    ALLOW IN    Anywhere
22/tcp (OpenSSH (v6))      ALLOW IN    Anywhere (v6)
80/tcp (v6)                ALLOW IN    Anywhere (v6)
443/tcp (v6)               ALLOW IN    Anywhere (v6)

Status: active and your three allowances – done. To be safe, test in a second SSH session that you can still connect before closing the first one.

The disabled (routed) in the Default line is normal on a fresh Debian: UFW only filters forwarded traffic if IP forwarding is enabled in the kernel at all. Once you install Docker later – which turns on net.ipv4.ip_forward – it will read deny (routed) instead. Both are fine, they just describe different starting points.

When things go wrong

After ufw enable you can no longer get in via SSH. The SSH rule was missing or targeted the wrong port. Connect via the console in the netcup SCP (VNC, independent of SSH), allow your SSH port there (sudo ufw allow …) and test again. That's exactly what step 3 warns about.

ERROR: Could not find a profile matching 'OpenSSH'. The OpenSSH profile only exists if openssh-server is installed. Use the port number instead: sudo ufw allow 22/tcp (or your port). sudo ufw app list shows the available profiles.

A Docker container is reachable from outside even though UFW doesn't open the port. Not your mistake – Docker bypasses UFW. Docker writes its rules directly into iptables and inserts them ahead of the UFW chains. A published container port (ports: in the compose.yaml) is thus open, no matter what UFW says. The clean solution is a second firewall layer in front of the server – at netcup the firewall in the SCP as an upstream perimeter. On the host it also helps to bind container ports only to 127.0.0.1 instead of 0.0.0.0.

Maintenance & backups

View and delete rules: sudo ufw status numbered numbers all rules; sudo ufw delete 3 removes rule 3. That's how you tidy up when a service goes away.
New services: For every additional public port, one targeted rule – never "just open everything". What doesn't need to be open stays closed.
No backup needed, but note down your allowances (or keep them in the same document as your DNS records). The rule set is retyped in seconds.
Know the limits: UFW protects the host, but not against the Docker gap above. An upstream perimeter firewall like the netcup firewall in the SCP complements UFW into two layers that secure each other – ideal once containers with open ports are running.

This post first appeared on serverkueche.de.

Self-hosting Jellyfin: your own media server behind Traefik

serverkueche.de — Fri, 25 Sep 2026 05:52:37 +0000

Netflix, Spotify and Google Photos in one – only on your own server and without a monthly fee: Jellyfin streams your movie, series and music collection to any device. In this recipe we hang Jellyfin behind Traefik and put the library on netcup's Local Block Storage so you don't run out of space.

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.

ℹ️ Honest about transcoding

Jellyfin re-encodes videos on demand live into a format your end device understands (transcoding) – that costs a lot of CPU. netcup servers are pure CPU machines without a graphics card, so real hardware transcoding (via a GPU) doesn't exist there. On a root server with dedicated cores (RS 1000), software transcoding works well for one or two parallel streams; but the royal road remains Direct Play – more on that below.

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.

💡 No block storage booked?

Then skip this step and simply create the library under ~/jellyfin/media – all the following commands work the same, only the path is different. You can add the block storage later at any time and move the data.

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.

🛑 Check first, then partition

The device names can differ per server. If you accidentally partition the system disk, your server is toast. Identify the device unambiguously by its size before you continue. When in doubt, create a snapshot first.

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

💡 Audiobooks belong elsewhere

Jellyfin can do music – but it is awkward for audiobooks and podcasts: it does not sync your listening position across devices, and it knows nothing about chapter marks or a sleep timer. If you want both, use Audiobookshelf for those; the two services run side by side on the same server without trouble.

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 the label Traefik guesses the port from the image – which works out for the Jellyfin image, because it exposes exactly one port. Don't rely on that: as soon as an image brings several ports, Traefik picks the wrong one and you get 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:

Set the server name and the preferred display language. Pre-filled is the container's hostname – a random hex string like df7c7caa7bcd. The server shows up under this name in the apps later, so a speaking name is worth it.
Create an administrator account – set a long, unique password, because the login page is publicly on the net.
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!). Matching that, the directory picker only shows container paths: besides the root /, the three mounted folders /media, /config and /cache. Repeat this for serien and musik.
Set the metadata language and country.
Configure remote access: "Allow remote connections to this server" stays on – otherwise you lock yourself out from the outside. There's nothing else to do on this page; Traefik takes care of the route from outside.
Click Finish. Jellyfin sends you to the login page, where you sign in with the account you just created.

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:

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

Enter the returned range (e.g. 172.19.0.0/16) there – the field accepts CIDR notation. The setting only takes effect after a restart, which the interface points out right below the field:

  docker compose restart

You can check whether it worked under Dashboard → Activity: before, every login showed Traefik's container IP (172.19.0.2 or similar), afterwards it shows the real IP of the device you signed in from.

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.

⚠️ Hardware transcoding needs a GPU

The hardware acceleration selectable in Jellyfin (VAAPI, QSV, NVENC) requires a graphics unit under /dev/dri. Standard VPS and root servers at netcup are KVM machines without a passed-through GPU – leave hardware acceleration off there, it would only produce errors. Instead plan with dedicated CPU cores and Direct Play.

When things go wrong

502 Bad Gateway on access, even though the container is running. Traefik reaches the container but hits the wrong port. Jellyfin listens on 8096 – check the label traefik.http.services.jellyfin.loadbalancer.server.port=8096 for typos. If a 504 Gateway Timeout comes back after a few seconds instead, the port isn't the problem, the network is: then networks: [proxy] is missing and Traefik is running against an address it can't reach at all.

The libraries stay empty, even though files are there. Almost always a permission problem. The container runs as 1000:1000 (step 4), so the media must belong to that user: sudo chown -R 1000:1000 /mnt/media. And: in Jellyfin the container path must be entered (/media/filme), not the host path. Afterwards start "Scan all libraries" under Dashboard → Scheduled Tasks.

Video stutters/buffers, docker stats shows Jellyfin at ~100% CPU. It's transcoding. Under Dashboard → Playback the activity monitor shows whether it says "Transcode" instead of "Direct Play". Set the client quality to original, change exotic codecs to a widely supported format, or give the server more (dedicated) cores.

After a reboot the library is gone and Jellyfin shows empty folders. The block storage wasn't mounted – usually a missing or wrong fstab entry (step 2). Check with df -h /mnt/media and sudo mount -a. The line must use the UUID, not /dev/vdb1.

The login page loads, but the app can't find the server / links point to an internal address. JELLYFIN_PublishedServerUrl is missing or wrong. Set it in the compose.yaml to https://jellyfin.YOUR_DOMAIN and restart with docker compose up -d (a restart isn't enough for the environment change to take effect).

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.

This post first appeared on serverkueche.de.

Setting up the netcup firewall in the SCP (with the stateless-UDP trick)

serverkueche.de — Fri, 25 Sep 2026 05:52:00 +0000

netcup comes with a firewall in front of your server – in the Server Control Panel, before a packet even reaches the operating system. Built correctly, it's a strong shield. But there's a trick many people fail at: the netcup firewall is stateless for UDP. This tutorial shows you a clean, reusable firewall – and why DNS and NTP otherwise suddenly get stuck.

What are we building?

In the netcup SCP we build a network firewall from composable policy templates: a base template (that every server needs), one for SSH, and one for web (HTTP/HTTPS). You assign these building blocks to your server as needed – a web server gets base + SSH + web, a server without a website only base + SSH. By the end, everything inbound is blocked except what you deliberately allow.

A netcup-specific detail makes the difference: for UDP the firewall works statelessly – which is why services like DNS and NTP need their own inbound rule, otherwise they suddenly get stuck. Why that is and how the base template solves it is shown in step 2.

ℹ️ Network firewall ≠ host firewall

The netcup firewall works in the network in front of the server and does not replace the firewall on the server itself (UFW). Both together are "defense in depth": if one layer fails or is misconfigured, the other kicks in. Feel free to set up both.

Prerequisites

A netcup server, e.g. your first VPS.
Your SCP credentials (customer number + SCP password from the netcup welcome email – different from your SSH login).
Clarity about your SSH port: the default is 22, and it stays that way when hardening SSH. If you changed it elsewhere, use your real port – otherwise you lock yourself out when activating.

Step by step

Step 1: Open Firewall Policies in the SCP

Log into the Server Control Panel and open the Firewall Policies menu item at the top. Here you create reusable rule sets ("policies") – independent of the individual server. You only assign them later.

Step 2: Build the base template

Click Create firewall policy, give it the name Serverküche Base and, via Add rule, create these four rules – all INBOUND and ACCEPT:

Description	Protocol	Source port (Src)	Destination port (Dst)
DNS replies (stateless)	UDP	53	any
NTP replies (stateless)	UDP	123	any
ICMP (ping/PMTU)	ICMP	–	–
ICMPv6 (Neighbor Discovery)	ICMPv6	–	–

Two things that make the difference here:

DNS/NTP via the Src Port, not the destination port. Your server queries DNS/NTP (outbound); the reply comes back from port 53 or 123. Because UDP is stateless, you need this inbound rule – otherwise there's no name resolution and no time synchronization, even though "everything else" seems to work.
Never forget ICMPv6. Without Neighbor Discovery, IPv6 breaks completely. ICMP (v4) on top is useful for ping and path MTU discovery. netcup's default policy "Ping allow" does already cover ICMP – it's deliberately in the base template again so your foundation stays complete even if you ever remove the netcup defaults.

ℹ️ As soon as one rule exists, netcup blocks the rest automatically

You do not need to create a final "block everything". Without an assigned policy, everything inbound is allowed. But as soon as you assign the server at least one of your own policies, netcup switches the default to "block all" – from then on everything inbound is blocked that none of your rules explicitly allows. So the whitelist arises on its own; outbound stays open.

💡 Does your server use DHCP?

netcup VPS are usually configured statically (iface … inet static) – then there's nothing to do here. netcup's network does run a DHCP server, but because UDP is stateless, the DHCP reply (source port 67) is discarded by the whitelist. If your server is exceptionally configured via DHCP, add INBOUND · UDP · ACCEPT · Src 67 to the base template (for DHCPv6 additionally Src 547) – otherwise it loses its IP at the next lease renewal.

Step 3: Small building blocks for SSH and web

Instead of one big rule monolith, you create atomic templates that you freely combine. Create two more policies following the same pattern:

Serverküche SSH – one rule: INBOUND, TCP, ACCEPT, destination port 22.
Serverküche Web – two rules: INBOUND, TCP, ACCEPT, destination port 80 and 443.

The gain: the base rules appear only once, not duplicated in every policy. If a service is added later (e.g. a mail server or WireGuard), you build another small template for it and plug it in – without touching the existing ones.

Step 4: Assign templates to the server

Switch to Server → your server → "Firewall" tab and click Edit firewall policies. Move the appropriate ones from Available firewall policies to Selected: for a web server Serverküche Base + Serverküche SSH + Serverküche Web.

Confirm with Apply and then Save. Check that the "Firewall active" switch is turned on. The assigned rules now appear in the list – together with netcup's default policies (more on those below).

⚠️ Don't lock yourself out

Only activate the firewall if the SSH rule (port 22 or your real port) is in it. During the switch, keep a second SSH session open and open a new connection in parallel to test access – only once that works do you close the old session. If you can't get in at all, the VNC console under Display in the SCP helps.

Step 5: Ready-made templates for common services

Exactly following the pattern from step 3, here are ready-made templates for the most common self-hosting services. Each is its own small template, all rules are INBOUND and ACCEPT. Build only the ones you really need and plug them, as in step 4, into Serverküche Base + Serverküche SSH.

ℹ️ For UDP services: destination port, not source port

For UDP services you offer yourself (VPN, TURN, your own DNS server), the port is in the destination port (Dst) – because here clients connect to your server. That's the opposite of the DNS/NTP rules from the base template: there the port is in the source port (Src), because your server is the querying client whose reply comes back. TCP replies aren't affected by this (the firewall state only matters for UDP); outbound is allowed anyway.

Mail server (mailcow & co.)

Fits mailcow and Stalwart.

Description	Protocol	Source port (Src)	Destination port (Dst)
SMTP (mail acceptance from others)	TCP	–	25
Submission (STARTTLS)	TCP	–	587
Submission (implicit TLS)	TCP	–	465
IMAP (STARTTLS)	TCP	–	143
IMAPS	TCP	–	993
POP3 (STARTTLS)	TCP	–	110
POP3S	TCP	–	995
ManageSieve (filter rules)	TCP	–	4190

Two things that additionally belong to a mail server:

Web UI and certificates: mailcow needs 80/443 for the web interface and the Let's Encrypt retrieval – just assign the Serverküche Web template along with it.
Enable outbound SMTP: a mail server must be able to deliver on port 25 outbound. netcup blocks outbound SMTP (ports 25/465/587) with the default policy "netcup Mail block" – you have to take it off the server, i.e. deactivate that netcup template in the assignment (see "When things go wrong"). No support ticket needed. And without a correct PTR/reverse-DNS entry your mails land in spam.

WireGuard VPN

Fits set up a WireGuard VPN.

Description	Protocol	Source port (Src)	Destination port (Dst)
WireGuard	UDP	–	51820

51820 is the usual default – use the value from your ListenPort. Only this one inbound rule is needed; the replies to the clients go out outbound.

OpenVPN

Description	Protocol	Source port (Src)	Destination port (Dst)
OpenVPN (UDP, default)	UDP	–	1194
OpenVPN (TCP fallback)	TCP	–	1194

The default is UDP 1194. The TCP rule only if you deliberately run OpenVPN over TCP (some additionally put it on TCP 443 to get through restrictive foreign networks) – otherwise leave it out.

Zabbix monitoring

Here it depends on the server's role:

Role	Description	Protocol	Destination port (Dst)
Monitored host (Zabbix agent)	passive checks from the server	TCP	10050
Zabbix server	trapper (active agents/proxies)	TCP	10051

The Zabbix server additionally needs 80/443 for the web frontend (Serverküche Web). If you run active checks, the agent connects outbound to the server on 10051 – for that, no inbound rule is needed on the agent host.

Checkmk

Role	Description	Protocol	Destination port (Dst)
Monitored host (agent)	agent controller, pull mode	TCP	6556
Checkmk server (optional)	agent receiver (push/registration)	TCP	8000
Checkmk server (optional)	Livestatus (distributed monitoring)	TCP	6557

In the default pull mode, the Checkmk server fetches the data actively – so it connects outbound to 6556 of the agents. Inbound, therefore, only the monitored host needs port 6556. The Checkmk server itself gets by with 80/443 (Serverküche Web); 8000 and 6557 only if you use push mode or distributed monitoring.

Coturn / TURN server (Nextcloud Talk, Matrix)

Description	Protocol	Source port (Src)	Destination port (Dst)
STUN/TURN	TCP	–	3478
STUN/TURN	UDP	–	3478
STUN/TURN over TLS	TCP	–	5349
STUN/TURN over TLS	UDP	–	5349
Media relay (audio/video)	UDP	–	49152–65535

The large UDP relay range is the default – the actual audio/video streams run over it. You can narrow it in the coturn configuration (min-port/max-port) and then set the firewall rule to the same, smaller range.

Jitsi Meet (video conferencing)

Goes with Jitsi Meet: your own video conferences (Tutorial expected in November).

Description	Protocol	Source port (Src)	Destination port (Dst)
Media (video bridge)	UDP	–	10000

This is the policy people forget most often, because without it Jitsi looks entirely normal: the web interface arrives over 443 and is already covered by the base and web templates, the participant list fills up, and only once somebody speaks do you notice that nothing arrives. Audio and video do not go through the reverse proxy but straight to UDP 10000 – and because the netcup firewall is stateless for UDP, that path needs an inbound rule of its own.

A rule in the other direction is not needed: with Jitsi the destination port stays fixed at 10000, unlike coturn with its large relay range.

Your own DNS server (AdGuard Home, Pi-hole, Unbound)

Description	Protocol	Source port (Src)	Destination port (Dst)
DNS queries	UDP	–	53
DNS queries (large replies/TCP)	TCP	–	53
DNS-over-TLS (DoT)	TCP	–	853

Careful, this is exactly the opposite direction to the base template: there Src 53 allows the replies to your own DNS queries; here Dst 53 allows the queries of foreign clients to your DNS server. Both exist side by side without problems.

⚠️ No open resolver

A globally open recursive DNS server is abused for DNS amplification attacks. Restrict access to your own networks (set the source address in the rule) or offer DNS exclusively encrypted (DoT/DoH) for registered clients – never open 53 "just quickly" for the whole world.

Remote database access (emergency only)

Description	Protocol	Source port (Src)	Destination port (Dst)
PostgreSQL	TCP	–	5432
MySQL / MariaDB	TCP	–	3306

🛑 Databases don't belong on the open internet

A directly reachable database is a preferred attack target. The right way is to not open the port at all and instead access it via a WireGuard tunnel or an SSH tunnel (ssh -L 5432:localhost:5432 …). If you must open the port anyway, then only with a source address restricted to your fixed admin IP in the netcup rule – never for everyone.

When things go wrong

After activating, name resolution stops working (apt update hangs, ping domain.de fails, but ping 1.1.1.1 works). The DNS replies are being blocked. Check the rule in the base template INBOUND UDP ACCEPT, Src port 53. Important: source port, not destination port.

The clock drifts, or TLS certificates are rejected due to the wrong time. The NTP replies are missing. Add INBOUND UDP ACCEPT, Src port 123.

IPv6 no longer works (v4 does). The ICMPv6 rule is missing. Without Neighbor Discovery, the server can't even find its neighbor (router) over IPv6.

After activating, you can no longer get in via SSH. The SSH rule is missing or names the wrong port. Via the VNC console (SCP → Display) you can still reach the server; correct the policy and save again. That's exactly what the "keep a second session open" rule above helps against.

The server can't send emails (outbound port 25 doesn't work). That's not an error in your policy, but netcup's default policy "netcup Mail block" – it blocks outbound SMTP (ports 25/465/587) as spam protection. For real mail sending you have to disable this netcup template on the server.

The server initially runs normally and is suddenly offline after one or two weeks. If the server uses DHCP, the lease renewal is blocked by the whitelist – the DHCP reply comes from UDP source port 67, which no rule allows, and UDP is stateless. Add INBOUND · UDP · ACCEPT · Src 67 to the base template. Statically configured netcup VPS (the default) aren't affected.

Maintenance & backups

Test access after every change. Firewall rules are the classic way to lock yourself out. Keep a second session open, check a new connection, only then finish.
New services = new template. If you later need another port (game server, WireGuard VPN over UDP, database), create a small template of your own and assign it additionally. The existing building blocks stay untouched.
Mind the order. netcup evaluates the rules top to bottom; the first matching rule wins. For pure ACCEPT rules that doesn't matter – but as soon as you use your own DROP rules, watch the order relative to the ACCEPTs.
Know netcup's default policies. "netcup Mail block" (outbound SMTP on ports 25/465/587 blocked) and "netcup Ping allow" are predefined. Via Restore default policies you can, in an emergency, get back to a known, working baseline if you locked yourself out with your own rules – together with the VNC console, your second safety net.

This post first appeared on serverkueche.de.

unattended-upgrades: automatic security updates for Debian

serverkueche.de — Thu, 24 Sep 2026 13:03:11 +0000

"Remember to install updates weekly" – this sentence from the maintenance sections of the other tutorials is the first one people forget. That's exactly why the server now takes it over itself: unattended-upgrades installs security updates automatically. That closes the most dangerous gap in self-hosting – the server that runs unpatched for months.

What are we building?

By the end, your Debian 13 automatically pulls security updates daily and installs them without your involvement. You decide whether and when the server reboots for necessary kernel updates, and you know how to verify that the automation really kicks in. What gets automated are security updates and the conservative stable point releases; larger upgrades of your other software stay deliberately in your hands.

Prerequisites

A hardened server with an active firewall

Step by step

Step 1: Install the package

sudo apt update
sudo apt install -y unattended-upgrades apt-listchanges

apt-listchanges shows the changelogs on updates – useful if you later do check manually what changed.

Step 2: Enable the automation

The simplest way to switch on the daily run:

sudo dpkg-reconfigure -plow unattended-upgrades

Choose Yes in the dialog. That creates the file /etc/apt/apt.conf.d/20auto-upgrades with this content:

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";

The 1 means "daily": update package lists and run unattended upgrades. It's triggered via the systemd timers apt-daily.timer (package lists) and apt-daily-upgrade.timer (upgrade run) – no separate cron job needed.

Step 3: Define what gets updated

Take a look at /etc/apt/apt.conf.d/50unattended-upgrades:

sudo nano /etc/apt/apt.conf.d/50unattended-upgrades

On Debian 13, three sources are active in the Origins-Pattern block by default:

Unattended-Upgrade::Origins-Pattern {
  "origin=Debian,codename=${distro_codename},label=Debian";
  "origin=Debian,codename=${distro_codename},label=Debian-Security";
  "origin=Debian,codename=${distro_codename}-security,label=Debian-Security";
};

The two Debian-Security lines ensure timely security updates – the actual purpose. The first line (label=Debian) covers the conservative stable updates that only arrive with Debian point releases; so it's not a risky rolling update, but well-seasoned. If you really want only security updates, comment out the first line with //.

Two options are worth setting explicitly here. Clean up old kernels/packages automatically, otherwise /boot eventually fills up (Remove-Unused-Kernel-Packages is already the default in code, but only appears commented out in the file – set explicitly, the decision is documented):

Unattended-Upgrade::Remove-Unused-Kernel-Packages "true";
Unattended-Upgrade::Remove-Unused-Dependencies "true";

And the most important point – the automatic reboot:

Unattended-Upgrade::Automatic-Reboot "true";
Unattended-Upgrade::Automatic-Reboot-Time "04:00";

⚠️ Automatic reboot – decide deliberately

Some security updates (especially kernel) only take effect after a reboot. With Automatic-Reboot "true" the server then reboots on its own – always set an Automatic-Reboot-Time when you do: without it, the server reboots immediately after the upgrade run (the code default is "now"; the 02:00 in the example file is only a commented-out suggestion). Choose a time with low usage. If you want no automatic reboots, leave the option at "false" and reboot yourself when /var/run/reboot-required exists. Both are defensible – it just has to be a deliberate decision.

What does that reboot actually depend on? unattended-upgrades only reboots if the marker file /var/run/reboot-required exists. A bare Debian 13 does not create it on kernel updates – on Ubuntu that hook lives in a helper package that doesn't exist in Debian. The unattended-upgrades package, however, ships its own kernel hook, so there is nothing for you to build. A quick check:

dpkg -S /etc/kernel/postinst.d/unattended-upgrades

unattended-upgrades: /etc/kernel/postinst.d/unattended-upgrades

The hook runs after every kernel installation, sets /var/run/reboot-required and also records the triggering package in /var/run/reboot-required.pkgs. That makes both Automatic-Reboot and the manual check of the file reliable.

On a Debian without unattended-upgrades the file is never created – there, a missing /var/run/reboot-required tells you nothing about whether a reboot is pending (see First steps with a netcup VPS).

Step 4: Do a dry run

Test what unattended-upgrades would do, without a real installation:

sudo unattended-upgrade --dry-run --debug

In the debug output, this line is decisive (on a fresh Debian 13, shortened):

Allowed origins are: origin=Debian,codename=trixie,label=Debian, origin=Debian,codename=trixie,label=Debian-Security, origin=Debian,codename=trixie-security,label=Debian-Security
[...]
No packages found that can be upgraded unattended and no pending auto-removals

The Debian-Security sources must appear there. If something is listed, the configuration applies; if the run finds nothing to do (as above), there's simply no security update pending right now.

When things go wrong

The dry run reports No packages found that can be upgraded unattended. Usually perfectly normal – no security update is currently pending. Check the configuration anyway via the Allowed origins are: line in the --debug run. If no security origins appear there, the Origins-Pattern from step 3 isn't right.

Updates come, but the server never reboots despite a kernel update. Usually Automatic-Reboot is set to "false" (default) – then set it to "true" and give it an Automatic-Reboot-Time (step 3). If the option is right, check the marker file: without /var/run/reboot-required the reboot never triggers. The package's kernel hook is what sets it – dpkg -S /etc/kernel/postinst.d/unattended-upgrades must report it (step 3).

/boot fills up, updates fail. Old kernels pile up. Set Remove-Unused-Kernel-Packages "true" (step 3); clean up once with sudo apt autoremove --purge.

A package is stubbornly held back (kept back). unattended-upgrades doesn't install updates that would remove other packages. You resolve such cases deliberately by hand with sudo apt upgrade and check what happens.

Maintenance & backups

Still check anyway: automation doesn't replace attention. Take a monthly look at the log /var/log/unattended-upgrades/unattended-upgrades.log and occasionally run sudo apt update && sudo apt upgrade for the non-security-critical updates.
Plan for reboots: if you use automatic reboots, make sure your services survive a reboot cleanly (restart: unless-stopped in Docker Compose if you run containers).
No dedicated backup needed, but note whether you enabled automatic reboots – it later explains why the server was briefly gone at night.

This post first appeared on serverkueche.de.

Setting up Traefik: reverse proxy with automatic HTTPS

serverkueche.de — Thu, 24 Sep 2026 13:02:32 +0000

This is the most important building block of the Serverküche. A reverse proxy takes in all requests on ports 80 and 443 and distributes them to the right container based on the domain – and Traefik fetches the HTTPS certificates fully automatically from Let's Encrypt. From here on, every further app gets its domain and its TLS with a few lines of labels, without you ever touching a certificate by hand again.

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:

Entrypoint – the port on which the request arrives (web = 80, websecure = 443).
Router – decides based on a rule (usually Host(...)) whether this request belongs to an app.
Middleware (optional) – modifies the request along the way (e.g. HTTPS redirect, basic auth, security headers).
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 rough idea of how HTTPS works – Traefik does the work for you, but the background helps when a certificate gets stuck
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).

⚠️ No resolving domain, no certificate

Let's Encrypt only issues certificates for domains it can reach. Check beforehand with dig +short YOUR_DOMAIN that your server IP comes back. If the record still points nowhere, certificate issuance fails – that's the most common Traefik error of all.

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 --ipv6 --subnet fd00:cafe::/64 proxy

Check:

docker network ls | grep proxy

ace6d528b14b   proxy     bridge    local

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

Why --ipv6? A Docker network without IPv6 does accept IPv6 visitors, but Docker then cannot rewrite the connection onto the container directly and routes it through a helper process. That process replaces the source address with the bridge gateway's: in Traefik and in every app behind it you then see 172.x.x.x instead of the real address. Over IPv4 you never notice, over IPv6 you always do – and a domain with an AAAA record is reached over IPv6 by most browsers. The range fd00:cafe::/64 is private (ULA) and only visible internally; you can pick any other range out of fd00::/8.

⚠️ If the proxy network already exists without IPv6

You cannot retrofit this – the network has to be created anew, and for that no container may still be attached to it. So first shut down all stacks (docker compose down in every project folder, Traefik last), then:
docker network rm proxy
docker network create --ipv6 --subnet fd00:cafe::/64 proxy
Afterwards bring everything back up, Traefik first. You check the result with docker network inspect proxy | grep EnableIPv6 – it has to say true. No data is lost in the process; volumes are not attached to the network.

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

🛑 acme.json needs 600

Without chmod 600 acme.json, Traefik skips the Let's Encrypt resolver: the container does start, but issues no valid certificate – you land on Traefik's self-signed emergency certificate. The log then reads permissions 644 for /acme.json are too open, please use 600. The file contains your private keys – only the owner may read it.

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.

💡 Test with the staging server first

Let's Encrypt has strict rate limits for production certificates. While you're still building, add --certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory as a test. This delivers test certificates (shown as insecure in the browser) without a limit. Once everything works, remove the line, empty acme.json (> acme.json) and restart Traefik – then the real certificate comes.

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.

💡 An empty log is a good sign

Traefik v3 writes only errors at the default log level. So an empty log output means: everything is running. If you want to see more during setup (every detected router, every ACME request), add --log.level=INFO to the command block and restart.

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.12
    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: 7854060e86a8
IP: 127.0.0.1
IP: ::1
IP: 172.19.0.3
RemoteAddr: 172.19.0.2:45224
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.

⚠️ Staging first, then production

Let's Encrypt has hard rate limits on production certificates (a few per domain per week). Only switch to production once routing and challenge demonstrably work with staging – otherwise you lock yourself out of the domain for hours.

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"

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 – that toolbox gets built out in
Hardening Traefik.

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).

💡 Tip

Only arm HSTS with stsSeconds once HTTPS runs reliably and permanently. The browser remembers the setting stubbornly – a broken certificate would then be hard to work around for the full duration.

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

"Certificate invalid" in the browser, or the Traefik log shows ACME errors. The three usual reasons: (1) The DNS record doesn't point to the server yet – check dig +short YOUR_DOMAIN. (2) Port 80 isn't reachable from outside (firewall/netcup firewall) – the HTTP challenge needs it. (3) You hit the rate limit of the production CA – switch to the staging server (tip in step 3), test, then go back.

404 page not found when calling the app domain. Traefik doesn't know the route. Check: Does the container have traefik.enable=true? Is it on the proxy network? Is the domain in the Host(...) rule exactly right (incl. subdomain)? The dashboard (step 7) shows under "HTTP Routers" whether the router was registered.

The browser shows Traefik's self-signed emergency certificate; the log reads permissions 644 for /acme.json are too open, please use 600. Traefik is running but skipped the ACME resolver – hence no real certificate. Run chmod 600 acme.json (step
2) and restart the container.

No app is routed; the Traefik log repeats client version 1.24 is too old. Minimum supported API version is 1.40. Your Traefik version is too old for your Docker engine – the Docker provider can no longer query the socket. Current Docker (Engine 29, API level ≥ 1.40) needs Traefik ≥ v3.6; that's why this tutorial uses traefik:v3.7. Reproduced against Docker 29: v3.5.6 runs into exactly this error, v3.6.25 talks to the socket cleanly again. So older tags like v3.3 or v3.5 no longer work with new Docker – bump the image tag and run docker compose up -d again.

Basic auth on the dashboard is rejected immediately / the router is missing. In the compose.yaml, the $ characters of the hash must be doubled ($$). Check the hash once more outside with htpasswd -nbB.

Gateway Timeout or Traefik doesn't reach the container. Usually the app is on the wrong network, or Traefik doesn't know which one is meant. providers.docker.network=proxy in Traefik and networks: [proxy] on the app must match.

502 Bad Gateway, even though the container is running. Traefik reaches the container but hits the wrong port. If the app doesn't listen on 80, it needs the label traefik.http.services.<name>.loadbalancer.server.port=<real-port>. This exact case meets you with the first app in the next tutorial (Uptime Kuma on 3001).

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.

This post first appeared on serverkueche.de.