DEV Community: serverkueche.de

Hardening Traefik: Security Headers, Rate Limit, BasicAuth & IP Allowlist

serverkueche.de — Tue, 20 Oct 2026 07:51:14 +0000

Your Traefik routes requests and fetches certificates – but it does not protect anything yet. Four middlewares change that: security headers, a rate limit, BasicAuth and an IP allowlist. We build them one at a time and measure with curl after every step what actually changed.

What are we building?

At the end you have four reusable middlewares and a chain you can attach to any service:

Middleware	Effect	Measured
`sec-headers`	HSTS, clickjacking and MIME protection	5 new response headers
`rate`	limits requests per IP	40 parallel requests → 13× `200`, 27× `429`
`auth`	BasicAuth in front of the service	without password `401`, with it `200`
`only-me`	only your IP gets in	foreign IP `403`, your own `200`

Tested with Traefik v3.7.8 on Debian 13. Important if you are migrating: in Traefik v3 the allowlist is called ipAllowList – the v2 name ipWhiteList no longer exists, and configurations using it break on upgrade.

Prerequisites

A running Traefik v3 with a proxy network and working TLS, as built in Traefik as a reverse proxy
A service behind it to practise on. We use traefik/whoami – a tiny container that echoes every request including its headers, which makes it perfect for verification
A basic grasp of Docker Compose and labels

Step by step

1. Measure the starting point

Before hardening anything, record what it looked like before. Create a test service – ~/whoami/compose.yaml, replacing YOUR_DOMAIN:

services:
  whoami:
    image: traefik/whoami:v1.12
    restart: unless-stopped
    networks: [proxy]
    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"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

mkdir -p ~/whoami && cd ~/whoami && docker compose up -d

Now look at the response headers:

curl -sI https://whoami.YOUR_DOMAIN/

HTTP/2 200
content-type: text/plain; charset=utf-8
date: Sat, 25 Jul 2026 07:01:27 GMT
content-length: 351

That is the whole truth: Traefik sets no security header at all on its own. TLS gives you an encrypted transport – it does nothing against clickjacking, MIME sniffing or accidental HTTP.

2. Set security headers

With Docker labels, middlewares are defined on any container and activated on a router. Add these labels to the test service:

      # activate
      - "traefik.http.routers.whoami.middlewares=sec-headers"
      # define
      - "traefik.http.middlewares.sec-headers.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.sec-headers.headers.stsIncludeSubdomains=true"
      - "traefik.http.middlewares.sec-headers.headers.stsPreload=true"
      - "traefik.http.middlewares.sec-headers.headers.frameDeny=true"
      - "traefik.http.middlewares.sec-headers.headers.contentTypeNosniff=true"
      - "traefik.http.middlewares.sec-headers.headers.referrerPolicy=strict-origin-when-cross-origin"
      - "traefik.http.middlewares.sec-headers.headers.permissionsPolicy=camera=(), microphone=(), geolocation=()"

docker compose up -d && sleep 5 && curl -sI https://whoami.YOUR_DOMAIN/

HTTP/2 200
content-type: text/plain; charset=utf-8
permissions-policy: camera=(), microphone=(), geolocation=()
referrer-policy: strict-origin-when-cross-origin
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
x-frame-options: DENY

Five headers more, and each has a purpose:

strict-transport-security (HSTS) tells the browser: talk to this domain over HTTPS only, for a year. That closes the gap between typing example.com and the redirect to HTTPS.
x-frame-options: DENY forbids embedding in foreign <iframe>s – the classic clickjacking protection.
x-content-type-options: nosniff stops the browser from „guessing" the content type and, say, executing an uploaded text file as a script.
referrer-policy prevents your full internal URL from being sent along when someone clicks an external link.
permissions-policy disables camera, microphone and location for this site.

🛑 preload is a one-way street

stsPreload=true is the invitation to have your domain added to the browsers' HSTS preload list (you apply for the listing separately). Once it is there, browsers enforce HTTPS for the domain and all its subdomains – even if your server has long stopped serving a certificate. Getting out takes months. Only set stsIncludeSubdomains and stsPreload if you are sure that every subdomain will permanently speak HTTPS. To start with, stsSeconds alone is enough.

Deliberately not in the list: browserXssFilter. The X-XSS-Protection header is considered obsolete and modern browsers ignore it. A contentSecurityPolicy is missing too – it is effective, but differs per application and reliably breaks interfaces when applied blindly.

3. Rate limiting against brute force and bots

This middleware limits how many requests a single IP may make:

      - "traefik.http.middlewares.rate.ratelimit.average=5"
      - "traefik.http.middlewares.rate.ratelimit.burst=10"
      - "traefik.http.middlewares.rate.ratelimit.period=1s"

average=5 with period=1s means five requests per second on average. burst=10 allows short spikes above that – web pages do load several files at once.

Activate it and verify with real load. Important: test in parallel, otherwise you are too slow to hit the limit at all:

seq 40 | xargs -P 8 -I{} curl -s -o /dev/null -w "%{http_code}\n" https://whoami.YOUR_DOMAIN/ \
  | sort | uniq -c

     13 200
     27 429

That is exactly how it should look: the first requests go through, after that Traefik answers with 429 Too Many Requests without troubling the service behind it at all.

💡 Sensible values

For a normal web interface, 5–20 requests per second with a burst of 20–50 is realistic. Set it too tight and you block real users loading a single page. After enabling it, watch the Traefik logs for 429 – if they show up in everyday use, the limit is too strict.

4. BasicAuth for services without their own login

Some tools have no login at all, or a weak one – a Traefik dashboard, a metrics endpoint, an admin interface. BasicAuth puts a hurdle in front of them before the request ever reaches the application.

First create a password hash. No extra package needed, Docker will do:

docker run --rm httpd:2.4-alpine htpasswd -nbB koch "YOUR_PASSWORD"

koch:$2y$05$IcOtS/jq6VR4haHO2Pvtl...

-B forces bcrypt (not the old MD5), -nb writes the result to standard output.

⚠️ Every $ has to be doubled in Compose

bcrypt hashes contain $ characters, and Docker Compose treats $ as a variable. So enter the hash with doubled dollar signs: $2y$05$Ic… becomes $$2y$$05$$Ic…. Forget that and parts of the hash vanish silently, making the login fail every time – docker compose config shows you what Compose really produces.

      - "traefik.http.middlewares.auth.basicauth.users=koch:$$2y$$05$$IcOtS/jq6VR4haHO2Pvtl..."

Verify – three cases, three answers:

curl -s -o /dev/null -w "%{http_code}\n" https://whoami.YOUR_DOMAIN/
curl -s -o /dev/null -u koch:wrong -w "%{http_code}\n" https://whoami.YOUR_DOMAIN/
curl -s -o /dev/null -u koch:YOUR_PASSWORD -w "%{http_code}\n" https://whoami.YOUR_DOMAIN/

401
401
200

On the 401 the browser asks for credentials itself – Traefik sends www-authenticate: Basic realm="traefik" along with it.

BasicAuth is deliberately simple: no logout, no second factor, no user management. For „nobody but me should even be able to knock here" it is exactly right; for real user accounts across several services, single sign-on is the way to go.

5. IP allowlist: only from home

Even stricter: allow requests only from certain networks. In Traefik v3 the middleware is called ipAllowList:

      - "traefik.http.middlewares.only-me.ipallowlist.sourcerange=YOUR_IP/32"

Find your public IP with curl -s https://ifconfig.me. Separate several ranges with commas, e.g. sourcerange=203.0.113.5/32,198.51.100.0/24.

The test shows both sides. With a foreign IP in the list Traefik answers:

And with your own:

⚠️ Which IP does Traefik even see?

Traefik checks the IP of the direct connection. If something sits in front of it – Cloudflare, a load balancer, another proxy – you see that component's IP, and an allowlist with your own address locks you out. What actually arrives is revealed by traefik/whoami in the X-Forwarded-For field. For such setups there is ipallowlist.ipstrategy.depth and excludedips – but first check how many proxies really sit in front.

An IP allowlist is effective but inconvenient: on mobile data or in hotel Wi-Fi you no longer get in. The more elegant variant for „only me" is a WireGuard VPN – then you allow the VPN network instead of changing public IPs.

6. Bundle middlewares into a chain

Several middlewares on one router are listed comma-separated – the order is the execution order. So you don't repeat this for every service, there is chain:

      - "traefik.http.middlewares.hardened.chain.middlewares=sec-headers,rate,auth"
      - "traefik.http.routers.whoami.middlewares=hardened"

Verify that everything applies at once:

curl -s -o /dev/null -w "%{http_code}\n" https://whoami.YOUR_DOMAIN/
curl -sI -u koch:YOUR_PASSWORD https://whoami.YOUR_DOMAIN/ | grep -i strict-transport

401
strict-transport-security: max-age=31536000; includeSubDomains; preload

Without credentials 401, with credentials you get the response and the headers. As a rule of thumb for the order: cheap rejections first. An IP allowlist drops the request without checking anything; the rate limit costs almost nothing; BasicAuth has to compute a bcrypt hash – and that is deliberately slow. So only-me, then rate, then auth.

7. The most important use case: the Traefik dashboard

Traefik ships a dashboard showing all routers, services and middlewares – genuinely useful for debugging. It is off by default, and for good reason: it reveals the complete structure of your server. This is exactly where BasicAuth pays off.

Enable the API in the Traefik stack:

    command:
      - "--api.dashboard=true"
      # … your existing parameters …

And give Traefik labels for itself. The trick is the internal service api@internal:

    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$$IcOtS/jq6VR4haHO2Pvtl..."

After docker compose up -d, check both entry points – the dashboard and the API underneath it:

curl -s -o /dev/null -w "%{http_code}\n" https://traefik.YOUR_DOMAIN/dashboard/
curl -s -o /dev/null -u admin:YOUR_PASSWORD -w "%{http_code}\n" https://traefik.YOUR_DOMAIN/dashboard/
curl -s -o /dev/null -w "%{http_code}\n" https://traefik.YOUR_DOMAIN/api/overview
curl -s -u admin:YOUR_PASSWORD https://traefik.YOUR_DOMAIN/api/overview

401
200
401
{"http":{"routers":{"total":3,"warnings":0,"errors":0},"services":{"total":5, …

The third line is the important one: the API is protected just like the interface. Had you attached the middleware only to a /dashboard path, /api/… would still be open – and with it your entire configuration readable. Because the router here matches the whole host, the login covers both.

💡 Tip

Even better than BasicAuth alone is the combination for the dashboard: only-me (IP allowlist) and dashboard-auth as a chain. Then an attacker has to be on the right network before they may even guess a password. For a dashboard you rarely need, that is the right level of hardening.

8. Define middlewares centrally (the scalable way)

So far we defined everything through labels. With five services you copy the same lines five times – and changing the HSTS duration means editing five files. Better: define them once, centrally, in the file provider.

Add two startup parameters and a mount to the Traefik stack:

    command:
      # … your existing parameters …
      - "--providers.file.directory=/dynamic"
      - "--providers.file.watch=true"
    volumes:
      # … your existing mounts …
      - ./dynamic:/dynamic:ro

Then the middlewares as YAML in ~/traefik/dynamic/middlewares.yml:

http:
  middlewares:
    sec-headers:
      headers:
        stsSeconds: 31536000
        stsIncludeSubdomains: true
        stsPreload: true
        frameDeny: true
        contentTypeNosniff: true
        referrerPolicy: strict-origin-when-cross-origin
    rate:
      rateLimit:
        average: 5
        burst: 10
        period: 1s

Restart Traefik – afterwards you attach them to any service with the suffix @file:

      - "traefik.http.routers.whoami.middlewares=sec-headers@file,rate@file"

Verified: headers and rate limit behave exactly as they did via labels (12× 200, 18× 429 for 30 parallel requests in the test). The gain: --providers.file.watch=true picks up changes to the file without a restart, and the HSTS duration now lives in exactly one place.

ℹ️ Where does a middleware come from?

Traefik appends the origin to every name: middlewares defined through labels are internally sec-headers@docker, those loaded from files are sec-headers@file. Within the same provider you may omit the suffix – across provider boundaries you may not. That is exactly what causes most „middleware not found" errors.

9. Which middleware for which service?

Not every service needs everything. The right chain depends on who should use it and what it already brings along:

Type of service	Examples	sensible chain
Public, for everyone	website, blog, status page	`sec-headers`
Public with a login	Nextcloud, Immich, Vaultwarden	`sec-headers`, `rate`
Only for you, with a login	Uptime Kuma, Grafana	`sec-headers`, `rate` (+ allowlist if possible)
Without its own login	Traefik dashboard, metrics endpoints	`only-me`, `rate`, `auth`
Dangerous if abused	Dockge, Portainer, Adminer	`only-me`, `auth` – or not public at all

Two rules behind that: no rate limit in front of services that need many parallel requests – Immich during a phone backup or a media server while streaming will otherwise run into 429. And: never put BasicAuth in front of an app that has its own login if it has a mobile app – most apps cannot cope with two stacked authentications.

For everything in the last row, the honest answer is usually not „one more middleware" but: don't put it on the open internet, reach it through WireGuard.

When things go wrong

The logs say „middleware … does not exist" and the service answers with 404. Almost always the provider suffix is missing: a middleware defined in the file provider is called name@file from the perspective of Docker labels. Without the suffix Traefik looks for it among the Docker labels – and finds nothing. The same applies the other way round for name@docker.

BasicAuth rejects the correct password. The $ characters in the bcrypt hash were interpreted as variables by Docker Compose. In Compose they have to be doubled ($$2y$$05$$…). docker compose config shows the value that really arrives.

The rate limit doesn't seem to work. Sequential curl calls are too slow: every process opens a new connection, so you stay below the limit. Test in parallel, e.g. with seq 40 | xargs -P 8 -I{} curl … – then the 429s appear.

After setting the IP allowlist you get 403 yourself. Traefik does not see your IP but that of the proxy in front of it (Cloudflare, load balancer). Check with traefik/whoami what X-Forwarded-For contains, and use ipallowlist.ipstrategy.depth for multi-stage setups.

A v2 configuration with ipWhiteList stops working after the upgrade. In Traefik v3 the middleware is called ipAllowList; the old name was removed, so the rule no longer applies. Rename every occurrence when migrating.

The browser still refuses plain HTTP even though you fixed the configuration. That is HSTS, not a bug: the browser remembers max-age and enforces HTTPS even when your server no longer offers it. A private window or a different browser helps for testing – and that is why the warning about preload exists above.

Maintenance & backups

Re-check after every Traefik update. Middlewares are configuration, and configuration ages: between v2 and v3 ipWhiteList became ipAllowList, other fields got new names. After an update a quick pass with curl -sI is worth it – do the expected headers still appear? Does the allowlist still answer 403? Two minutes that save you from silent ineffectiveness.

Back up the dynamic directory. If you follow the file provider, it holds your entire hardening. It belongs in the backup together with compose.yaml and acme.json – small, but painful to reconstruct. How to automate that is covered in Restic backups.

Allowlists age. Dynamic IP addresses of home connections change, office networks move. Take a look at your sourcerange entries once a quarter and remove anything you can no longer place – an allowlist containing strangers' addresses is worse than none.

Honest about the reach of these measures. Security headers protect your users' browsers, not your server. A rate limit slows brute force down, it does not prevent it. BasicAuth is a door with a lock, not a user concept. What these four middlewares do not replace: a hardened SSH access, a firewall, automatic updates and fail2ban or CrowdSec for the layer below. The middlewares are the layer that sits in front of your applications – not the only one.

This post first appeared on serverkueche.de.

Dockge: Manage Compose Stacks in the Browser

serverkueche.de — Tue, 20 Oct 2026 07:51:07 +0000

Anyone running several Compose stacks knows the routine: SSH in, change into the right folder, docker compose pull && up -d, check the logs, next stack. Dockge brings exactly those steps into the browser – while writing perfectly ordinary compose.yaml files that you can still touch from the CLI.

What are we building?

At the end, Dockge 1.5.0 runs behind your Traefik at https://YOUR_DOMAIN. You create stacks in the browser, edit their compose.yaml, deploy them with one click and watch the output of docker compose up live – including container logs and a Bash console per container.

The decisive difference from heavyweight Docker interfaces: Dockge does not invent a format of its own. Every stack is a folder under /opt/stacks/<name>/ with a compose.yaml and an .env. docker compose ls lists them as normal projects. You can switch Dockge off tomorrow and carry on as if it had never existed – no lock-in.

On resources: the container used around 143 MiB RAM in the test with virtually no CPU load. The image, however, is no lightweight at 1.17 GB – worth knowing if your VPS has a small system disk.

🛑 Dockge is root on your server

Dockge needs the Docker socket (/var/run/docker.sock). Anyone with access to this interface can start arbitrary containers – privileged ones included – and thereby take over the whole host. So this applies more strictly here than for any other app: reachable over HTTPS only, a long unique password, and if possible restricted to your own IP as well (see Setting up a firewall with UFW). A Dockge on the open internet with a weak password is a compromised server.

Prerequisites

A server running Debian 13 with Docker (tested on a netcup VPS with Docker 29.6.1 and Compose v5.3.1)
Docker Compose basics – Dockge does not save you the understanding, only the typing
A running Traefik with its proxy network as in Traefik as a reverse proxy
A subdomain pointing at your server (connecting a domain)

Step by step

1. Decide on the stacks directory

Dockge manages all stacks below one folder. The default is /opt/stacks, and we stick with it – it matches the convention used in the other recipes:

mkdir -p /opt/stacks /opt/dockge/data

⚠️ Host and container path must be identical

The path has to be the same inside and outside the container, i.e. /opt/stacks:/opt/stacks. Dockge calls docker compose through the host's socket – so the daemon interprets paths from the host's point of view. If you mount /opt/stacks to /app/stacks, Dockge finds the files in its own view but the daemon does not: deployments fail with „no such file or directory".

2. The Compose file for Dockge

Create /opt/dockge/compose.yaml and replace YOUR_DOMAIN:

services:
  dockge:
    image: louislam/dockge:1.5.0
    restart: unless-stopped
    environment:
      DOCKGE_STACKS_DIR: /opt/stacks
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - /opt/stacks:/opt/stacks
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dockge.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.dockge.entrypoints=websecure"
      - "traefik.http.routers.dockge.tls.certresolver=le"
      - "traefik.http.services.dockge.loadbalancer.server.port=5001"

networks:
  proxy:
    external: true

How the pieces fit together:

DOCKGE_STACKS_DIR must match the mount target exactly (step 1).
./data holds Dockge's own SQLite database: users, settings, JWT secret.
loadbalancer.server.port=5001 – inside the container Dockge listens on 5001. We publish no port to the outside; only Traefik reaches it through the proxy network.
No user: entry: Dockge has to talk to the Docker daemon through the socket and write the stack files.

Start it:

cd /opt/dockge && docker compose up -d

docker compose ps

The container ships a healthcheck, so you should see (healthy):

NAME              STATUS
dockge-dockge-1   Up 12 seconds (healthy)

A look at the logs confirms the first start:

docker logs --tail 5 dockge-dockge-1

[SERVER] INFO: Connected to the database
[SERVER] INFO: JWT secret is not found, generate one.
[SERVER] INFO: Stored JWT secret into database
[SERVER] INFO: No user, need setup
[SERVER] INFO: Listening on 5001

No user, need setup means the server is waiting for your admin account.

3. Create the admin account

Open https://YOUR_DOMAIN. Dockge redirects to /setup and asks for a username and password. The interface follows your browser's language.

After that the door is shut: there is no open registration, further accounts are created in the settings. Use a long, unique password from your password manager – see the warning above.

4. Understanding the home screen

After logging in you see every Compose project Docker knows about on this host – in the example the existing traefik stack plus the one just created:

On the left, Dockge counts active, exited and inactive. Important: the list shows all projects, but Dockge can only manage those below /opt/stacks. How to adopt existing stacks is step 7.

5. Create and deploy the first stack

Click Compose at the top. You land in the editor: on the left a form for the stack name and containers, on the right the compose.yaml – both sides are linked, so you can click or write YAML.

Give the stack a name (lowercase only – it becomes the folder and project name) and adjust the YAML. A click on Deploy runs docker compose up -d, and the real output scrolls by in the terminal pane:

The container entry shows status and published ports, with the logs running below. Each container also gets a Bash button that opens a console inside it – handy for quickly checking a configuration.

6. What happens on disk

This is the part that sets Dockge apart from heavyweight interfaces. After deploying, the server holds exactly what you would expect:

find /opt/stacks -type f

/opt/stacks/whoami-test/.env
/opt/stacks/whoami-test/compose.yaml

And Docker knows the stack as a perfectly ordinary Compose project:

docker compose ls

NAME                STATUS              CONFIG FILES
dockge              running(1)          /opt/dockge/compose.yaml
traefik             running(1)          /opt/traefik/compose.yaml
whoami-test         running(1)          /opt/stacks/whoami-test/compose.yaml

So you can SSH into the folder at any time and carry on as usual:

cd /opt/stacks/whoami-test && docker compose ps

NAME                   STATUS         PORTS
whoami-test-nginx-1    Up 35 seconds  0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

Both hold at the same time: changes in the browser are visible to the CLI, changes from the CLI show up in the browser after a reload. Dockge is a remote control, not a new system.

7. Adopt existing stacks

A stack outside /opt/stacks appears in the list but cannot be touched – Dockge says so plainly: „This stack is not managed by Dockge." There is neither an edit nor a deploy button.

To adopt it, move the folder. Assuming your stack lives in /opt/myapp:

cd /opt/myapp && docker compose down
mv /opt/myapp /opt/stacks/myapp
cd /opt/stacks/myapp && docker compose up -d

The project name is derived from the folder name – keep it the same and your containers keep their names and named volumes survive. Dockge then manages the stack fully:

💡 Tip

Don't do everything at once: move one non-critical stack, verify, then the next. I would touch your Traefik last – if that goes wrong, Dockge is unreachable too.

8. Convert `docker run` commands

Many projects only document a long docker run command. The home screen has a field for exactly that: paste the command, click Convert to Compose – and you land in the editor with finished YAML. This

docker run -d --name uptime -p 3001:3001 -v uptime-data:/app/data \
  --restart unless-stopped louislam/uptime-kuma:2.5.3

becomes:

services:
  uptime-kuma:
    container_name: uptime
    ports:
      - 3001:3001
    volumes:
      - uptime-data:/app/data
    restart: unless-stopped
    image: louislam/uptime-kuma:2.5.3
volumes:
  uptime-data:
    external: true
    name: uptime-data

Very handy – with one trap: the named volume is written as external: true, i.e. „already exists". On a fresh installation the volume does not exist yet, and the deployment fails. Either delete those two lines (then Compose creates the volume itself) or create it beforehand with docker volume create uptime-data. For the difference, see volumes vs. bind mounts.

9. Console and agents – decide deliberately

Two features you should know about before switching them on:

Console. The console menu entry is disabled by default, and that is a good thing. Dockge states why itself: it allows arbitrary commands inside the Dockge container – and that container has the Docker socket. Enabled, it means a root shell on your host in the browser. Leave it off; for the rare case, SSH is enough.

Agents (beta). Dockge can attach further servers and manage their stacks in the same interface. That is convenient if you run several machines – but the feature is marked beta, and every attached agent increases the damage if this one interface is ever compromised. To start with: one server, one Dockge.

10. Updates with one click

The Update button on a stack does exactly what you would otherwise type: pull new images and bring the stack back up. If the image is already current, nothing happens – in the test the container kept running unchanged afterwards (same start time), so it is not restarted without reason. That is convenient – and precisely why you should keep pinning your images instead of using latest. Otherwise one click turns into a jump across several major versions without you noticing. Why that matters is covered in keeping your Docker stack up to date.

When things go wrong

Traefik answers with 404 although the container is healthy. Usually traefik.http.services.dockge.loadbalancer.server.port=5001 is missing. Inside the container Dockge listens on 5001; without that line Traefik guesses. Also check that the container is attached to the proxy network.

The deployment aborts with „no such file or directory". The host and container paths of the stacks directory do not match. It must be mounted as /opt/stacks:/opt/stacks with DOCKGE_STACKS_DIR=/opt/stacks – Dockge has the host's Docker daemon do the work, and that daemon only knows host paths.

A stack is visible but all buttons are missing. Then it lives outside /opt/stacks and Dockge shows „This stack is not managed by Dockge." Move the folder as in step 7 – Dockge neither adopts it by itself nor makes a copy.

The stack name is rejected. Only lowercase letters, digits and hyphens are allowed, because they become the folder and Compose project name. My App won't do, my-app will.

After a restart the login is gone. Then ./data was not mounted persistently – that is where the database and JWT secret live. Check that /opt/dockge/data exists and is bound in the Compose file.

The interface is in the wrong language. Dockge follows the browser and falls back to English for unknown combinations; the settings let you pin the language.

Maintenance & backups

Honest about the project's state. Dockge is popular (around 24,000 stars) and still being developed – the most recent commits in the repository are from April 2026, among them container controls and a resource display. The last stable release 1.5.0, however, dates from 30 March 2025, more than a year ago. There is a nightly tag with the newer features – but it is explicitly not a release.

In practice that means: stay on 1.5.0 (completely unproblematic with Docker 29.6.1 and Compose v5.3.1 in the test), do not expect quick bug fixes, and do not make an operational decision that depends on a new version arriving tomorrow. For „manage stacks conveniently" it is enough – you just want to know what you are getting into.

Updating Dockge itself works like any other stack, but from the CLI (the interface cannot restart itself):

cd /opt/dockge && docker compose pull && docker compose up -d

Backups. Two things need saving, and both are small:

/opt/dockge/data – Dockge's database with accounts and settings
/opt/stacks – this is where the actual work lives: every compose.yaml and .env of your services

That makes /opt/stacks your central configuration location from now on – one more reason to back it up daily with Restic. The data of your applications (volumes, bind mounts) is not covered by Dockge; that still needs its own strategy.

Review access regularly. Because Dockge means root rights on the host, maintenance includes the question: who can actually reach it? The Traefik logs show who requests the login page – if unfamiliar IPs turn up there, an IP restriction or access only via WireGuard is the better answer than an even longer password.

This post first appeared on serverkueche.de.

Running WordPress Cleanly with Docker & Traefik

serverkueche.de — Tue, 20 Oct 2026 07:50:57 +0000

WordPress powers a large part of the web – and is notorious for hacked installations. The difference between "runs and is secure" and "becomes a spam cannon" lies in a clean setup and honest maintenance. This recipe delivers both: WordPress with Docker, an isolated database, HTTPS – and a clear statement of what you have to do on an ongoing basis.

What are we building?

A production-ready WordPress installation with WordPress 7.1.0 (PHP 8.5) and MariaDB 11.8 behind Traefik. The database runs in an isolated internal network with no internet access, WordPress gets its HTTPS from Traefik, and we cleanly solve the classic reverse-proxy pitfall (redirect loop / mixed content). By the end you have a running blog – and you know how to keep it secure.

ℹ️ WordPress or Hugo?

If you "only" need a website or blog without interactive features, a static site with Hugo is safer and lower-maintenance to run (no database, no attack surface). WordPress is worth it when you need its huge plugin ecosystem, editorial workflows or shop/membership features. This tutorial takes WordPress honestly, including its maintenance burden.

Prerequisites

A server with Traefik running and Docker Compose
A domain pointing at the server – YOUR_DOMAIN below
A bit more RAM than simple services need – WordPress + database + PHP run comfortably from the VPS 2000 up

Step by step

Step 1: Two containers, two networks

WordPress consists of two parts: the PHP application and a MariaDB database. A clean setup separates the two and isolates the database – it should only be reachable by WordPress and needs no internet itself. That's exactly what the two networks are for (see Understanding Docker networks): the public proxy network between WordPress and Traefik, and an internal network between WordPress and the database.

mkdir -p /opt/wordpress && cd /opt/wordpress

Step 2: The Compose file

Replace YOUR_DOMAIN and all passwords with your own values:

services:
  db:
    image: mariadb:11.8
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: YOUR_DB_PASSWORD
      MARIADB_RANDOM_ROOT_PASSWORD: "1"
    volumes:
      - db_data:/var/lib/mysql
    networks: [intern]
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      start_interval: 2s
      interval: 30s
      timeout: 5s
      retries: 5

  wordpress:
    image: wordpress:7.1.0-php8.5-apache
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: YOUR_DB_PASSWORD
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_CONFIG_EXTRA: |
        if (isset($$_SERVER['HTTP_X_FORWARDED_PROTO']) && $$_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') { $$_SERVER['HTTPS'] = 'on'; }
        define('WP_HOME', 'https://YOUR_DOMAIN');
        define('WP_SITEURL', 'https://YOUR_DOMAIN');
    volumes:
      - wp_data:/var/www/html
    networks: [proxy, intern]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.wp.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.wp.entrypoints=websecure"
      - "traefik.http.routers.wp.tls.certresolver=le"
      - "traefik.http.services.wp.loadbalancer.server.port=80"

volumes:
  db_data: {}
  wp_data: {}
networks:
  proxy:
    external: true
  intern:
    internal: true

Three details are crucial here:

depends_on: condition: service_healthy – WordPress only starts once the database reports ready via the health check. Without it the first start fails in a race condition.
intern is internal: true – the database is only on this network and therefore has no internet access; WordPress reaches it at the hostname db.
WORDPRESS_CONFIG_EXTRA – the most important part (next step).

⚠️ The reverse-proxy pitfall: detecting HTTPS

Traefik terminates TLS and talks to WordPress internally over HTTP. WordPress therefore thinks it's running insecurely and generates http:// links – which leads to mixed-content errors or a redirect loop (ERR_TOO_MANY_REDIRECTS). The line if (... HTTP_X_FORWARDED_PROTO ... === 'https') { $_SERVER['HTTPS'] = 'on'; } tells WordPress the original connection was HTTPS. Together with WP_HOME/WP_SITEURL that's the clean solution. In Compose the PHP variables must be written as $$, otherwise Docker interprets them as its own variables.

Step 3: Start

docker compose up -d

Docker starts the database first, waits for its health check and then starts WordPress. Check:

docker compose ps

NAME                    IMAGE                           SERVICE     STATUS
wordpress-db-1          mariadb:11.8                    db          Up (healthy)
wordpress-wordpress-1   wordpress:7.1.0-php8.5-apache   wordpress   Up

Verify from outside that WordPress responds with valid HTTPS (the 302 redirects to the install):

curl -sI https://YOUR_DOMAIN/ | head -1

HTTP/2 302

Step 4: The famous 5-minute install

Open https://YOUR_DOMAIN/. WordPress redirects to the install wizard. After the language selection you fill in the basics:

⚠️ Don't use “admin” as the username

Do not choose the username admin – it's the first target of every brute-force attack on WordPress. Use your own name and a strong password. That's the simplest and most effective hardening measure of all.

After clicking "Install WordPress" and the first login you land in the dashboard:

Step 5: The website is live

Your site is immediately public – with valid HTTPS from Traefik and no mixed-content errors thanks to the proxy configuration:

Step 6: Basic hardening

WordPress is functional out of the box but not optimally secured. The most important immediate measures:

Enable automatic updates: under Dashboard → Updates make sure at least security updates are applied automatically.
Delete unnecessary default content: the "Hello world!" post, the sample page and the bundled example plugin (Hello Dolly) can go.
Less is more with plugins: every plugin is additional attack surface. Only install what you really need, and only from a trustworthy source.
Protect the login further: ideally put another hurdle in front of the WordPress login (/wp-login.php). A rate-limit/BasicAuth middleware in Traefik or a 2FA plugin work well. Fail2ban can also evaluate WordPress login attempts.
Keep an eye on XML-RPC: the file xmlrpc.php is a common target for brute force and DDoS. If you don't need it, block it via a Traefik middleware or plugin.

When things go wrong

Redirect loop (ERR_TOO_MANY_REDIRECTS) or mixed-content warnings. The HTTPS detection is missing. Check that the WORDPRESS_CONFIG_EXTRA block with HTTP_X_FORWARDED_PROTO and the $$ signs is set exactly (see the warning in step 2), and restart the WordPress container.

WordPress won't start, reports "Error establishing a database connection". Usually a race condition or a password mismatch. Check that depends_on: condition: service_healthy is set and WORDPRESS_DB_PASSWORD matches MARIADB_PASSWORD exactly. Logs: docker compose logs db.

The first start fails even though everything runs later. The database needs a few seconds to initialize on the very first start. The health check covers this; without it, another docker compose up -d helps.

Media uploads fail for large files. PHP limits the upload size. Create your own uploads.ini and mount it to /usr/local/etc/php/conf.d/ with e.g. upload_max_filesize = 64M and post_max_size = 64M.

After a domain change the site points nowhere. WP_HOME/WP_SITEURL are hard-wired in the Compose file – for a new domain, change them there and restart the container (the values override the database setting).

Maintenance & backups

Honestly: WordPress is maintenance work. Unlike a static site, active code with a database runs here – core, themes and plugins get regular security updates that must be applied promptly. A neglected WordPress will reliably get hijacked. Enable automatic updates and check the update status monthly. Keep the container tag (wordpress:7.1.0-php8.5-apache) current via your normal update process.
The backup has two parts – both are mandatory. WordPress consists of a database (posts, settings, users) and files (wp_data volume: uploads, themes, plugins). A Restic snapshot of the running MariaDB volume alone is no guarantee – back up the database additionally via a dump. -T matters here (without it the command hangs on the password prompt and leaves an empty file), as does putting the password directly after -p, with no space:

docker compose exec -T db mariadb-dump -u wordpress -p'YOUR_DB_PASSWORD' --single-transaction wordpress > backup.sql

Afterwards make sure the file isn't empty (ls -l backup.sql). The dump and the wp_data volume belong in your Restic backup.

Test the restore. A backup that was never restored is just a hope – run a restore at least once as a test, so that in an emergency you know the dump and files fit together.

This post first appeared on 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.

DEV Community: serverkueche.de

Hardening Traefik: Security Headers, Rate Limit, BasicAuth & IP Allowlist

What are we building?

Prerequisites

Step by step

1. Measure the starting point

2. Set security headers

3. Rate limiting against brute force and bots

4. BasicAuth for services without their own login

5. IP allowlist: only from home

6. Bundle middlewares into a chain

7. The most important use case: the Traefik dashboard

8. Define middlewares centrally (the scalable way)

9. Which middleware for which service?

When things go wrong

Maintenance & backups

Dockge: Manage Compose Stacks in the Browser

What are we building?

Prerequisites

Step by step

1. Decide on the stacks directory

2. The Compose file for Dockge

3. Create the admin account

4. Understanding the home screen

5. Create and deploy the first stack

6. What happens on disk

7. Adopt existing stacks

8. Convert docker run commands

9. Console and agents – decide deliberately

10. Updates with one click

When things go wrong

Maintenance & backups

Running WordPress Cleanly with Docker & Traefik

What are we building?

Prerequisites

Step by step

Step 1: Two containers, two networks

Step 2: The Compose file

Step 3: Start

Step 4: The famous 5-minute install

Step 5: The website is live

Step 6: Basic hardening

When things go wrong

Maintenance & backups

Understanding Docker Compose: services, volumes, networks

What are we building?

Prerequisites

Step by step

Step 1: The first compose.yaml

Step 2: Volumes – where your data really lives

Step 3: Networks – containers talking to each other

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

Step 5: The operations toolbox

Step 6: All together – a realistic app stack

When things go wrong

Maintenance & backups

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

What are we building?

Prerequisites

Step by step

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

Step 2: Fix the two quick warnings

Step 3: Set the HSTS security header via Traefik

Step 4: Set up email sending

Step 5: Enforce two-factor authentication

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

Step 7: Check caching & PHP – the performance foundation

When things go wrong

Maintenance & backups

First steps with a netcup VPS

What are we building?

Prerequisites

Step by step

Step 1: Log in via SSH

Step 2: Update the system

Step 3: Create a sudo user

Step 4: Test the new user

When things go wrong

Maintenance & backups

The essential terminal commands for your server

8. Convert `docker run` commands