DEV Community: serverkueche.de

netcup VPS 1000 G12 benchmarked: how fast is it really?

serverkueche.de — Sun, 20 Sep 2026 17:54:20 +0000

The VPS 1000 G12 is netcup's entry-level VPS and the server most Serverküche recipes run on. But how fast is it really? We measured it thoroughly with standard tools – and show you the commands you can use to check your own server against it.

What are we building?

We benchmark the four things that matter in everyday self-hosting: CPU, memory, NVMe disk and network – each with established open-source tools (sysbench, fio, 7z, openssl, curl). All figures below come from a real VPS 1000 G12 on Debian 13. The test machine: AMD EPYC-Genoa, 4 vCore, 8 GB RAM, 256 GB NVMe.

The key figures at a glance (measured in July 2026 with sysbench 1.0.20 and fio 3.39 on a VPS 1000 G12 in netcup's Vienna data centre):

Area	Measurement (VPS 1000 G12)
CPU – 1 core (sysbench)	1,495 events/s
CPU – 4 cores (sysbench)	5,974 events/s (≈ 4× scaling)
7-Zip (`7z b`)	~27,400 MIPS total
AES-256-GCM (AES-NI)	~7.7 GB/s
RAM throughput	~30 GB/s
NVMe – 4K random read	101,000 IOPS
NVMe – 4K random write	67,000 IOPS
NVMe – sequential read	4.3 GB/s
NVMe – sequential write	3.1 GB/s
Download (Falkenstein)	~246 MB/s (about 2 Gbit/s)
Latency (Anycast resolver 1.1.1.1)	~12 ms
Steal time (in the test)	0%

Quick assessment: for an entry-level VPS these are consistently strong figures – especially the NVMe disk and the network play well above what you'd expect from the cheapest plan. But the context matters: a VPS shares the physical CPU with other customers (shared vCores). Your figures can differ depending on the neighbors' load – how you spot that is in "When things go wrong".

Prerequisites

A netcup server, e.g. your first VPS, with SSH access.
The benchmark tools. All are in the Debian package sources:

  sudo apt update
  sudo apt install -y sysbench fio p7zip-full

Some free storage space (the disk tests write a few GB temporarily) and ideally no production load during the measurement.

💡 Measure several times

A single benchmark is a momentary snapshot. Run each test two or three times and ideally at different times of day – then you see how stable the figures are.

Step by step

Step 1: Size up the server

Before you measure, look at what you're dealing with:

grep -m1 "model name" /proc/cpuinfo && nproc && free -h

model name : AMD EPYC-Genoa Processor
4
               total        used        free      shared  buff/cache   available
Mem:           7.8Gi       689Mi       3.0Gi       656Ki       4.3Gi       7.1Gi

Four vCores on an AMD EPYC-Genoa (netcup's current G12 generation) and 8 GB RAM. Also take a look at the steal time – the percentage the CPU "waits" because a neighbor on the same host is computing:

vmstat 1 3

In the st column (far right) it should ideally read 0. For us it was 0 over the whole test – no noticeable neighbor influence. High, persistent steal values would be the sign of an oversubscribed host.

Step 2: CPU

sysbench computes prime numbers – once on one core, once on all four:

sysbench cpu --cpu-max-prime=20000 --threads=1 run
sysbench cpu --cpu-max-prime=20000 --threads=4 run

1 Thread:   events per second:  1494.66
4 Threads:  events per second:  5973.69

Two things are remarkable here: the solid single-thread performance (Genoa cores are fast) and the almost perfect scaling – 4 threads deliver 3.996× a single one. That means: at the time of measurement, the four vCores were fully available, without neighbors siphoning off compute time.

A second, practical CPU test is the built-in 7-Zip benchmark (compression, uses all cores):

7z b

Tot:  ...  27425  (MIPS total)

7z b measures compression and decompression separately (each its own line) and combines both in the Tot: line into an overall rating – that's the roughly 27,400 MIPS. A good reference figure to compare the VPS with other 7-Zip results online. And because encryption runs everywhere (HTTPS, backups, VPN), the AES performance with hardware acceleration (AES-NI):

openssl speed -evp aes-256-gcm

type             16 bytes     64 bytes    256 bytes   1024 bytes   8192 bytes  16384 bytes
AES-256-GCM      89283.37k   343370.05k  1270428.16k  3164995.93k  7671136.75k  8464845.66k

openssl speed measures single-threaded by default – so the figure applies to one core. For the throughput across all cores you append -multi $(nproc). In our run a single core reached about 7.7 GB/s (7,671,136 k) on the 8 KB blocks. TLS is thus never the bottleneck on this processor anyway.

Step 3: Memory

sysbench writes a large block repeatedly through RAM and measures the throughput:

sysbench memory --memory-block-size=1M --memory-total-size=30G --threads=4 run

30720.00 MiB transferred (28727.21 MiB/sec)

Around 30 GB/s – plenty for databases, caches (Redis/Valkey) and everything that keeps many small objects in memory. RAM on this plan is, in our experience, limited more by quantity (8 GB) than by throughput.

Step 4: NVMe disk

Here the wheat separates from the chaff – the disk is the actual bottleneck for most self-hosted apps. fio measures realistically when you bypass the page cache with --direct=1 (otherwise you measure RAM, not the disk). First the 4K random IOPS decisive for databases:

# Read (4K random read)
fio --name=rr --ioengine=libaio --direct=1 --rw=randread --bs=4k \
  --numjobs=4 --iodepth=32 --size=512M --runtime=20 --time_based --group_reporting

# Write (4K random write) – same command, only --rw=randwrite
fio --name=rw --ioengine=libaio --direct=1 --rw=randwrite --bs=4k \
  --numjobs=4 --iodepth=32 --size=512M --runtime=20 --time_based --group_reporting

read:  IOPS=101k, BW=394MiB/s
write: IOPS=67.0k, BW=262MiB/s

101,000 read and 67,000 write IOPS at 4K – that's real NVMe level and the reason why Nextcloud, databases or Paperless feel noticeably smooth on this VPS. And the sequential throughput (large files, backups, video):

# Read (sequential)
fio --name=sr --ioengine=libaio --direct=1 --rw=read --bs=1M \
  --numjobs=1 --iodepth=16 --size=2G --runtime=15 --time_based

# Write (sequential) – same command, only --rw=write
fio --name=sw --ioengine=libaio --direct=1 --rw=write --bs=1M \
  --numjobs=1 --iodepth=16 --size=2G --runtime=15 --time_based

READ:  bw=4123MiB/s (4.3 GB/s)
WRITE: bw=2937MiB/s (3.1 GB/s)

4.3 GB/s reading, 3.1 GB/s writing. A restic backup or a large docker pull is thus done in seconds.

Step 5: Network

For throughput, you download a large test file from a well-connected server. We take the Hetzner speed test in Falkenstein (Germany):

curl -o /dev/null -w "%{speed_download} B/s in %{time_total}s\n" \
  https://fsn1-speed.hetzner.com/1GB.bin

246095181 B/s in 4.36s

~246 MB/s, i.e. about 2 Gbit/s – 1 GB in just over four seconds. A download from the US (Ashburn) was, due to distance, at ~36 MB/s; within Europe the connection is excellent. Finally the latency:

ping -c 5 1.1.1.1

rtt min/avg/max/mdev = 12.314/12.337/12.365/0.019 ms

~12 ms to 1.1.1.1 (Cloudflare's Anycast resolver, i.e. a nearby network node – not a purely German target), very consistent (the deviation is in the hundredths). IPv6 is active and works; a ping over IPv6 was at ~26 ms.

When things go wrong

Your figures are well below ours, especially for the CPU. A VPS shares the physical CPU. Check the steal time (vmstat 1, column st) and top (line %st). If it's persistently high, neighbors on the same host are computing right now. Measure again at a different time of day – often the difference is gone then.

The disk figures are absurdly high (e.g. "10 GB/s random read"). You're missing --direct=1 – then fio measures the RAM cache, not the NVMe. Always test with direct I/O, otherwise the numbers are worthless.

lsblk shows ROTA=1 ("rotational") for vda in the column – is that a hard disk instead of NVMe? No. That's a virtualization artifact: the virtio driver reports the virtual disk as rotational across the board. The measured 100k+ IOPS and 4 GB/s prove that real flash storage is behind it.

The download is much slower than 2 Gbit/s. Measure against a nearby, fast server (e.g. Falkenstein). A distant target or a slow counterpart limits the measurement, not your VPS. A single curl stream also doesn't always exhaust the full bandwidth.

Every run delivers different numbers. Normal – benchmarks fluctuate. Measure multiple times, discard the first ("warm") run and take the median. Also compare only the same tool versions and parameters with each other.

Maintenance & backups

Who is the VPS 1000 G12 enough for? For practically all the single services on this site – SSH, Traefik, Vaultwarden, Uptime Kuma, a small Nextcloud. It gets tight less at CPU or disk than at RAM: as soon as several heavy apps (Nextcloud + Immich + databases) run in parallel, an upgrade to the VPS 2000 (16 GB) is the most sensible next step.
Watch steal time long-term. A one-off benchmark is a momentary snapshot. Whoever wants to keep an eye on performance long-term takes CPU steal, I/O and network into a Grafana dashboard – there you see creeping degradation before it hurts.
Re-measure after changes. A server migration, a product switch or a new netcup generation changes the figures. Keep your benchmark outputs (a simple text file in the backup is enough), then you have a basis for comparison.
Stay honest: benchmark numbers age and fluctuate. They're an orientation, not a promise – the shared vCores mean the real performance always also depends on the neighbors on the host. For the entry-level price, though, the VPS 1000 G12 delivers a remarkably well-rounded performance.

This post first appeared on serverkueche.de.

HitKeep: self-host privacy-friendly web analytics

serverkueche.de — Sun, 20 Sep 2026 17:54:04 +0000

Everyone knows Google Analytics – and that's exactly the problem: it sends your visitors' data to Google, requires a cookie banner and makes you accountable to explain it. HitKeep turns that around: cookieless statistics on your server, under your domain, without a single byte ever going to third parties.

What are we building?

By the end, HitKeep 2.13.18 runs as a single container behind your Traefik, reachable at https://YOUR_DOMAIN. You get a dashboard with page views, visitors, time on page, referrers and devices – fed by a tiny JavaScript snippet you embed in your website. HitKeep works cookieless (no consent banner needed) and stores everything locally in an embedded DuckDB database. The image is a distroless image (about 68 MB to download, a good 230 MB unpacked on disk) that gets by entirely without an external database – ideal for a small VPS.

ℹ️ Note

HitKeep is "cookieless" because it recognizes visitors via a daily-changing hash instead of a set cookie. That's significantly more privacy-friendly than classic tracking, but is no substitute for legal advice. Whether you can do entirely without consent depends on your specific use – when in doubt, clarify it with a data protection officer.

Prerequisites

A server with Debian 13 and running Docker (tested on a netcup VPS).
A reverse proxy with Traefik that fetches TLS certificates via Let's Encrypt. HitKeep brings no own HTTPS server – Traefik handles the encryption. This tutorial assumes the proxy network and the resolver le described there.
A (sub)domain that points to your server (A/AAAA record). In the example we use YOUR_DOMAIN.
The website you want to measure – HitKeep measures every page into which you embed the snippet.

Step by step

Step 1: Generate a JWT secret

HitKeep signs the login sessions with a secret key. Generate a random 32-byte value – don't make one up, generate it:

openssl rand -hex 32

You get a 64-character hex string. Copy it – it goes into the configuration shortly. If this secret changes later, all open logins become invalid; so keep it stable and secret.

Step 2: Create the Compose file

Create a folder for the stack and change into it:

mkdir -p /opt/hitkeep && cd /opt/hitkeep

Create the file compose.yaml. Replace YOUR_DOMAIN with your real domain and YOUR_JWT_SECRET with the value from step 1:

services:
  hitkeep:
    image: pascalebeier/hitkeep:2.13.18
    container_name: hitkeep
    restart: unless-stopped
    environment:
      HITKEEP_PUBLIC_URL: https://YOUR_DOMAIN
      HITKEEP_JWT_SECRET: YOUR_JWT_SECRET
      HITKEEP_TRUSTED_PROXIES: 172.16.0.0/12
      HITKEEP_DB_PATH: /var/lib/hitkeep/data/hitkeep.db
      HITKEEP_DATA_PATH: /var/lib/hitkeep/data
      HITKEEP_ARCHIVE_PATH: /var/lib/hitkeep/data/archive
      HITKEEP_BACKUP_PATH: /var/lib/hitkeep/data/backups
    volumes:
      - hitkeep_data:/var/lib/hitkeep/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.hitkeep.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.hitkeep.entrypoints=websecure"
      - "traefik.http.routers.hitkeep.tls.certresolver=le"
      - "traefik.http.services.hitkeep.loadbalancer.server.port=8080"
    networks: [proxy]
volumes:
  hitkeep_data: {}
networks:
  proxy:
    external: true

The most important points in detail:

HITKEEP_PUBLIC_URL is the public address under which HitKeep is reachable. The interface later builds the tracking snippet and the links from it. It must match exactly the URL under which you call HitKeep – otherwise you end up in a login loop.
HITKEEP_TRUSTED_PROXIES is the crux behind a reverse proxy: by default (*) HitKeep trusts the X-Forwarded-For header from any sender – so every visitor could claim someone else's IP. 172.16.0.0/12 narrows that down to the Docker networks (the proxy network sits inside it, 172.19.0.0/16 in our test), so only Traefik gets to set the visitor IP. Important: the range really has to contain your proxy's IP – if it doesn't, HitKeep only ever sees Traefik's container IP.
loadbalancer.server.port=8080 tells Traefik that HitKeep listens internally on port
1. The container itself publishes no ports to the outside – access runs exclusively via Traefik.
The four _PATH variables store the database, data, archive and backups all below /var/lib/hitkeep/data – deliberately in one volume. The container runs as a non-root user (UID 65532), and that single directory is the only one the image ships with matching ownership. If you attach extra volumes for archive and backups on their own paths, Docker creates them owned by root, and HitKeep answers in the log with Initial backup run failed and permission_denied.

Step 3: Start the stack and wait for TLS

Start the container:

docker compose up -d

Check the status after a few seconds:

docker compose ps

You should see the container as healthy – HitKeep brings its own healthcheck:

NAME      IMAGE                          COMMAND     SERVICE   CREATED          STATUS                    PORTS
hitkeep   pascalebeier/hitkeep:2.13.18   "hitkeep"   hitkeep   40 seconds ago   Up 40 seconds (healthy)   7946/tcp, 8080/tcp

Traefik now fetches the Let's Encrypt certificate for your domain in the background. Check from your own machine that the tracking script is served:

curl -sI https://YOUR_DOMAIN/hk.js

Expected output (shortened) – status 200 and a text/javascript type, aggressively cached:

HTTP/2 200
content-type: text/javascript; charset=utf-8
cache-control: public, max-age=31536000, immutable

⚠️ Warning

If you get a 404 from Traefik or a certificate warning here, wait a minute (Let's Encrypt needs a moment) and check that the A/AAAA record of your domain really points to the server. As long as the certificate isn't in place, the snippet won't load in the browser either.

Step 4: Create the admin account

Open https://YOUR_DOMAIN in the browser. On the very first start, HitKeep greets you with the initial setup. Create your administrator account here – name, email address and a password. Take a long passphrase or a random password generated by a password manager; this account sees all statistics and must not hang on a weak password:

💡 Tip

This initial setup is only open on the very first call. Still: set up the admin account immediately after the start and don't leave a freshly started HitKeep wizard unsecured on the net.

Step 5: Create a website and get the tracking code

After logging in, click the plus next to Sites at the top left and create your website – as the domain, enter the domain of the site you want to measure (e.g. YOUR_WEBSITE).

Then use the </> icon below the site name to open the site settings on the Tracking tab. At the top you find the live tracking verifier waiting for the first hit, and below it, under Install HitKeep on …, the installation methods: Script tag, npm (a typed tracker for React/Vue/Angular/Astro), WordPress and Server-side. All of them report into the same dashboard; we take the script tag:

The code to embed consists of a single line. HitKeep needs no site ID in the snippet – the assignment happens automatically via the domain of the page on which the script runs:

<script async src="https://YOUR_DOMAIN/hk.js"></script>

ℹ️ Note

The difference between the tracker host and the measured domain is important: hk.js is loaded from your HitKeep domain (YOUR_DOMAIN), but the hit is assigned to the domain of the visited page (YOUR_WEBSITE). Both may be different – the site created in HitKeep only has to match the hostname of the visited page.

Automatic event tracking (outbound clicks, downloads, form submissions) is active by default. Under Advanced options you can adjust the snippet – for example enable "Web Vitals" to also measure load times (LCP, INP, CLS, FCP, TTFB), or "Collect DNT" if you also want to count visitors with "Do Not Track". From a privacy perspective the default (respect DNT) is the cleaner one. Important: these switches are not stored in HitKeep, they only write additional data- attributes into the snippet, which you then have to copy again:

<script async src="https://YOUR_DOMAIN/hk.js" data-enable-web-vitals="true"></script>

Step 6: Embed the tracking code in the website

Add the snippet line from step 5 into the <head> of your website – for a static page directly into the HTML template, for a CMS into the header area or a "Custom HTML" field. Thanks to the async attribute, the script doesn't block the page build.

Then open a page of your website in the browser. The live tracking verifier from step 5 should jump from "Waiting" to a first hit within a few seconds – that's the confirmation that the chain website → hk.js → HitKeep is in place.

Step 7: Check the dashboard

As soon as hits trickle in, the dashboard fills up. Under Dashboard you see your website's key figures – live visitors, page views, unique sessions, bounce rate, time on page and the traffic trend:

Further down, Latest Hits lists the individual calls with path, time, referrer and device – here you see at a glance which search engines and referrals your visitors come from:

With that your self-hosted statistics are in place: every call to your website lands directly in your own database, without a detour via third parties.

Step 8: More than just page views

For the start, page views and referrers are enough – but HitKeep can do considerably more, and you find the building blocks in the left navigation. A few that are worth it for most sites:

Goals: define an event as a goal – e.g. the submission of a contact form or a click on "Buy". This way you measure not only how many come, but how many do what you want.
Funnels: chain several steps (home page → product page → cart) and see at which point visitors drop off.
Events: besides the automatically captured events (outbound clicks, downloads, forms), you can send your own events from your frontend.
Web Vitals: if you enable them on the tracking tab, you see real load times of your visitors (LCP, INP, CLS) instead of synthetic lab values.
UTM: campaign parameters (utm_source, utm_medium, utm_campaign) are evaluated – handy to tell newsletter from social reach.
Reporting: have a summary sent to you regularly by email instead of having to look into the dashboard yourself (this needs the HITKEEP_MAIL_* variables with your mail server's credentials).

A single HitKeep instance also manages any number of websites: via the plus next to Sites you create more, each with its own snippet and its own dashboard. So you don't need a second container if you want to measure several projects.

When things go wrong

The live verifier stays on "Waiting" / no hits in the dashboard. Check in the browser (dev tools → Network) whether hk.js is loaded at all and the send request afterwards comes back with status 2xx. Most common causes: the snippet isn't in the HTML, the site domain created in HitKeep doesn't match the hostname of the visited page, or an ad/tracking blocker filters the call. Since you host under your own domain (first-party), most blockers don't apply – but some lists know the path hk.js.

All visitors seemingly come from a single IP, country and provider show "(Unknown)". Then HITKEEP_TRUSTED_PROXIES isn't taking effect: the range you gave doesn't contain your proxy's IP, and HitKeep only evaluates Traefik's container IP. Check which subnet the proxy sits in with docker network inspect proxy – 172.16.0.0/12 covers the usual Docker networks – and restart the stack (docker compose up -d). After that the real client IP from the X-Forwarded-For header counts again.

Traefik returns 404 or 502. A 404 usually means the router rule isn't matching – check that Host(...) contains your real domain and the container is on the proxy network. A 502 indicates the wrong port: HitKeep listens internally on 8080, so loadbalancer.server.port=8080 must be set.

After login you land on the login page again (login loop). That's almost always a mismatch in HITKEEP_PUBLIC_URL: the value must match exactly the address through which you call HitKeep (including https://, without a trailing slash). Correct the variable and restart the container.

The container won't start or isn't healthy. Look at the logs: docker compose logs -f hitkeep. A missing or empty HITKEEP_JWT_SECRET is a typical start blocker – generate one as in step 1 and enter it.

Maintenance & backups

Updates: HitKeep moves along briskly in the 2.x series – less than seven weeks passed between 2.12.0 and 2.13.18. So check the releases about monthly. For an update, set the new tag in the compose.yaml (replace 2.13.18 with the new version) and pull it:

docker compose pull && docker compose up -d

Because the data lives in volumes, your statistics are preserved. Deliberately pin the version to a fixed tag instead of latest, so a restart doesn't slip you an unplanned new major version.

Backups: Your entire statistics live in an embedded DuckDB file (hitkeep.db plus the write-ahead log hitkeep.db.wal) under /var/lib/hitkeep/data. So don't back up a single file, but the complete hitkeep_data volume regularly – cleanest with Restic. HitKeep itself drops an hourly snapshot into backups/ inside that volume and keeps the last 24; in the log you see it as Database backup completed. Because the live files are written during operation, you back them up most consistently either from those finished snapshots or from the volume while the container is briefly stopped (docker compose stop). A backup you've never restored is just a glimmer of hope: test the restoration once on a test system.

Cleanup: The database grows with the traffic. Keep an eye on the size of the volumes (docker system df -v) and plan for enough storage with a lot of traffic.

This post first appeared on serverkueche.de.

Keeping your whole Docker stack safely up to date

serverkueche.de — Sun, 20 Sep 2026 17:53:14 +0000

A self-hosted stack is never "done". Container images get security updates, apps get new features – and whoever doesn't keep up eventually runs vulnerable software. This recipe turns "I should update sometime" into a reliable routine: informed, controlled and with a safety net.

What are we building?

Not a tool, but update discipline for your entire Docker stack. By the end you have: pinned versions (never latest again), an update notifier (Diun) that tells you when something new is available, a safe rollout routine with a backup beforehand and a rollback plan – and a cleanup rhythm so old images don't clutter your disk. Tested with Diun v4.33.0 on Docker 29 / Compose v5.3.

The guiding idea is deliberately not "update everything automatically". With stateful apps (databases, Nextcloud, Immich) an unattended update in the middle of the night can trigger a migration that goes wrong – and nobody is there. The safe way is: pin → get notified → apply deliberately → verify. We treat blind auto-updates honestly at the end (step 6): they have their place, but a small one.

Prerequisites

Basic knowledge of Docker Compose – you should be able to read tags, volumes and compose.yaml.
A running stack you want to maintain (e.g. the apps behind your reverse proxy).
A working backup strategy with Restic – it's the safety net that makes updates relaxed in the first place.

Step by step

Step 1: Never `latest` again – pin versions deliberately

The most common mistake appears in countless guides: image: nextcloud:latest. The problem: latest is a moving target. A docker compose pull can pull you a new major version with breaking changes at any time, unasked – you never know what you're running, and a rollback is barely possible.

Pin every service to a fixed tag instead. Two sensible levels:

Major tag (postgres:18, nextcloud:34-apache): automatically gets patch and minor updates of the same major version on the next pull, but never a major jump. A good compromise for most services.
Exact version (vaultwarden/server:1.37.2): full control, nothing changes without your involvement. Ideal for delicate, stateful apps.

What you're running right now is shown by Compose per project:

cd ~/YOUR_APP && docker compose images

CONTAINER           REPOSITORY          TAG                 PLATFORM            IMAGE ID            SIZE                CREATED
diun-demo-whoami    traefik/whoami      v1.11.0             linux/amd64         200689790a0a        3.04MB              17 months ago

If latest appears anywhere in the TAG column, that's your first candidate to pin. Enter the specific tag into the compose.yaml – that's the foundation for everything else.

Which version is currently stable you look up at the source, not by gut feeling: the tags overview on Docker Hub (or GHCR) of the image, or the release notes on GitHub. For official images this also works via API:

curl -s "https://hub.docker.com/v2/repositories/library/postgres/tags/?page_size=20" | grep -oE '"name":"[0-9.]+"'

Take the highest stable version of the same series you want to run – pre-releases (rc, beta) stay out.

Step 2: See what's outdated – the update notifier Diun

Pinning means updates no longer come on their own. So you need someone to let you know when a new image is available. That's exactly what Diun (Docker Image Update Notifier) does – it updates nothing, it only watches and notifies. Give it its own folder:

mkdir -p ~/diun && cd ~/diun

The compose.yaml:

services:
  diun:
    image: crazymax/diun:4.33.0
    command: serve
    environment:
      - "TZ=Europe/Berlin"
      - "DIUN_WATCH_SCHEDULE=0 8 * * *"          # daily at 8 a.m.
      - "DIUN_PROVIDERS_DOCKER=true"
      - "DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT=false"
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

DIUN_PROVIDERS_DOCKER=true lets Diun discover your running containers via the Docker socket.
WATCHBYDEFAULT=false means Diun only watches containers you explicitly mark – so you don't get a flood about things that don't interest you.
DIUN_WATCH_SCHEDULE is a cron expression; once a day is plenty and spares the registry rate limits.

⚠️ The Docker socket is not a harmless read access

We mount the socket here with :ro, and that sounds reassuring – but it's only half true. The :ro merely prevents the file docker.sock from being overwritten; through the Docker API behind it you can still do anything: start containers with --privileged, mount the host filesystem, in short root on the host. Whoever has access to the socket is practically root-equivalent – regardless of the :ro. For a pure notifier like Diun this is a deliberately accepted risk; if you want to defuse it, don't attach Diun directly to the socket, but to an upstream docker-socket-proxy that only passes through the few endpoints (list containers, read images) Diun really needs.

Mark the containers Diun should keep an eye on via a label in their compose.yaml:

    labels:
      - "diun.enable=true"
      - "diun.watch_repo=true"

diun.enable=true switches on monitoring. diun.watch_repo=true lets Diun search the whole repository for newer tags (e.g. whether a 19 already exists for your postgres:18) – without this label, Diun only checks whether your exact tag got a new image. Start Diun and watch the first run:

docker compose up -d && docker compose logs -f diun

INF Found 1 image(s) to analyze provider=docker
INF New image found      image=docker.io/traefik/whoami:v1.11.0 provider=docker
INF New image found      image=docker.io/traefik/whoami:v1.12.0 provider=docker
INF New image found      image=docker.io/traefik/whoami:latest-arm64 provider=docker
INF Jobs completed       added=97 failed=0 skipped=0 unchanged=0 updated=0

The first run is just the inventory: Diun writes every tag it finds into its database as "New image found" (added). That one watched container yields 97 entries is down to watch_repo – Diun then fetches the manifest for every tag in the repository, including architecture variants like latest-arm64 or v1.10.0-armv7.

Two things follow from this that are easy to get wrong:

The first run does not notify. The option watch.firstCheckNotif defaults to false, and that applies per image tag. Everything Diun sees for the first time lands in the database silently. It only reports once something changes later on.
watch_repo costs registry requests. 97 manifest queries per run almost blow the Docker Hub limit without a login (100 requests per IPv4 address or IPv6 /64 subnet) on their own. On the second run of the same day our test ran straight into it – StatusCode: 429 and failed=36 in the log. How much budget is left – and which window the registry is currently counting in – it tells you itself:

  TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | cut -d'"' -f4)
  curl -sI -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest | grep -i "^ratelimit"

  ratelimit-limit: 100;w=3600
  ratelimit-remaining: 98;w=3600

w is the window width in seconds. Docker documents a six-hour window; our test VPS consistently got w=3600, i.e. one hour, in August 2026. So rely on the header rather than on a remembered number – and note that this query itself costs a request. Beyond that, narrow the tags down to what you actually care about – real release tags:

    labels:
      - "diun.enable=true"
      - "diun.watch_repo=true"
      - "diun.include_tags=^v1\\.1[12]\\.\\d+$$"
      - "diun.sort_tags=semver"

include_tags is a regular expression. Two pitfalls hide in the notation: the backslashes have to be doubled in YAML, and the trailing $ is written as $$ – otherwise Compose tries to substitute an environment variable. With this label, exactly the two real release tags remain out of the 97 entries:

INF Found 1 image(s) to analyze provider=docker
INF New image found      image=docker.io/traefik/whoami:v1.11.0 provider=docker
INF New image found      image=docker.io/traefik/whoami:v1.12.0 provider=docker
INF Jobs completed       added=2 failed=0 skipped=0 unchanged=0 updated=0

So that the notice doesn't just sit in the log, you attach a notification. Diun can do email, Telegram, ntfy, Gotify and many more. For Telegram – you may already have set up the bot in the Uptime Kuma tutorial – two lines in the environment block are enough:

      - "DIUN_NOTIF_TELEGRAM_TOKEN=YOUR_BOT_TOKEN"
      - "DIUN_NOTIF_TELEGRAM_CHATIDS=YOUR_CHAT_ID"

All other channels are in the Diun documentation. This is what the notice looks like – here via
ntfy in the browser, as soon as a newer version appears for one of your pinned images:

💡 Test the notification without waiting for weeks

Because the first run deliberately stays silent, you don't know after setting things up whether the notification path works at all – in the worst case you find out only after missing an important notice. So set DIUN_WATCH_FIRSTCHECKNOTIF=true in Diun's environment once, delete ./data and restart: then Diun sends notifications for the inventory too – exactly one per tag found. Channel verified, remove the variable again afterwards (otherwise the next watch_repo run floods your inbox).

Step 3: Apply an update safely (the routine)

Diun reports an update – now comes the actual discipline. Never just pull blindly. The fixed order for every service:

1. Read the release notes. On a major jump (e.g. Nextcloud 34 → 35) this is mandatory: are there breaking changes, migration steps, removed options? Two minutes here save hours of debugging.

2. Back up first. An update is the classic moment for something to break. Make a Restic backup of the data (for big jumps, additionally a netcup snapshot). Then a failure is only a setback, not data loss.

3. Bump the tag and pull. Set the new tag in the compose.yaml and fetch the image:

docker compose pull

 Image traefik/whoami:v1.12.0 Pulled

4. Restart. Compose only replaces the affected container, the volumes stay:

docker compose up -d

 Container diun-demo-whoami Recreated
 Container diun-demo-whoami Started

5. Verify. Does the container run cleanly (docker compose ps, docker compose logs), and does the app still do what it should? Stateful apps may now run a database migration – take a look at the log until it's through.

6. Have a rollback in mind. If something goes wrong, set the tag in the compose.yaml back to the old version and do docker compose up -d again. Because your data lives in the volume (not in the container), for most apps this is a clean step back. Only if the new version has already migrated the database does a tag rollback no longer help – then you need the backup from step 2. That's exactly what it's for.

💡 One app at a time

Don't update the whole stack at once. Go service by service and check each time that everything runs before moving to the next. If something breaks then, you immediately know which update was to blame.

Step 4: Don't forget the base – host, engine, hidden images

Your apps are only half the battle. Equally important:

Operating system & Docker engine. The OS and security packages of Debian you best install automatically with unattended-upgrades. The Docker engine is deliberately left out of that: unattended-upgrades by default only pulls the Debian sources (origin=Debian), not the Docker APT repo (origin=Docker, download.docker.com). So the engine isn't updated in the background and won't unexpectedly restart all your containers at night – because an engine update briefly takes running containers down. You'd better determine that moment yourself and update the engine specifically by hand when it fits:

  sudo apt update && sudo apt upgrade docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Afterwards check with docker compose ps that all stacks are up again.

If a brief container restart at night doesn't bother you, you can also let the engine come along with unattended-upgrades: allow the Docker repo in /etc/apt/apt.conf.d/50unattended-upgrades as an additional origins pattern. What matters is archive= – the Docker repo sets no Codename field, the often-recommended codename=${distro_codename} would run into the void and Docker would stay out despite the entry:

  "origin=Docker,archive=${distro_codename}";

Hidden images. Many stacks contain databases, caches and helper services (postgres, redis, mariadb, gotenberg …) that nobody thinks of. Diun watches them automatically as soon as the respective container carries the diun.enable label – so give it to all long-lived services, not just the visible main app.
Extensions of your reverse proxy. Pinned plugin versions too (e.g. the CrowdSec bouncer) or Traefik itself want to be updated deliberately.

Step 5: Clean up – reclaim storage

Every update leaves the old image behind. After a few months this adds up. What you're using is shown by:

docker system df

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          26        4         14.75GB   14.16GB (95%)
Containers      4         4         45.06kB   0B (0%)
Local Volumes   0         0         0B        0B
Build Cache     36        0         828.2MB   828.2MB

Unused, untagged ("dangling") images are removed by the safe default command:

docker image prune

Careful: this only removes dangling images. An old, still tagged version (like whoami:v1.11.0 after the update to v1.12.0) doesn't count as dangling and stays behind. You reclaim that specifically:

docker rmi traefik/whoami:v1.11.0

Untagged: traefik/whoami:v1.11.0
Deleted: sha256:200689790a0a0ea48ca45992e0450bc26ccab5307375b41c84dfc4f2475937ab

Whoever wants to clean up more radically uses docker image prune -a (removes all images no running container currently uses). That's powerful, but pulls everything anew on the next start – use it deliberately, not in cron.

The safe docker image prune -f (dangling only), on the other hand, you can run regularly without worry – e.g. weekly via a systemd timer or cron. That way no junk piles up between your update sessions in the first place, and you reclaim the storage automatically.

Step 6: Auto-update – when it's okay (and when not)

The question remains: why not everything fully automatic? The best-known tool for that is Watchtower – it pulls new images and restarts containers on its own. Two catches:

The upstream is orphaned. The official containrrr/watchtower hasn't had a release since v1.7.1 (2023-11-11) – and the repository was archived at the end of 2025 (2025-12-17), i.e. mothballed for good. Whoever uses it better reaches for a maintained fork like nickfedor/watchtower.
Auto-update is dangerous for stateful apps. Lifting a database or Nextcloud over a major jump unattended at night is the opposite of "safe".

Auto-update makes sense at most for uncritical, stateless services – and even then rather in monitor mode (WATCHTOWER_MONITOR_ONLY=true), which only reports instead of updating. For everything else, the deliberate routine from step 3 beats any automation tool. That's exactly why Diun (notify) + manual update is the recommendation here, not Watchtower (act).

💡 Safe automation for Git users: Renovate

If your compose.yaml files live in a Git repo, there's a third way that combines automation and control: Renovate (or Dependabot) detects the pinned image: tags and automatically opens a pull request that bumps the tag – complete with a link to the release notes. So the update doesn't happen secretly on the server, but as a change you review and merge before rolling it out with docker compose up -d. That way the safe "apply deliberately" step is preserved, only the tedious checking is gone.

When things go wrong

docker compose pull pulls no new image, even though a new version exists. Your tag points to a fixed version (:1.37.2) or to a major tag (:18), under which there'd only be a new major. pull only fetches what the same tag now points to. For a version jump you have to bump the tag in the compose.yaml yourself.

The app no longer starts after the update or throws database errors. Usually a breaking change or a failed migration. Check docker compose logs, compare with the release notes. Set the tag back to the old version and up -d; if the new version already migrated the data, restore the backup from step 3.

Diun reports nothing, even though updates exist. Check that the containers carry the label diun.enable=true and Diun can read the socket (DIUN_PROVIDERS_DOCKER=true, socket mounted). For newer version tags the container additionally needs diun.watch_repo=true – without it, Diun only sees changes to the exactly pinned tag. And: whatever Diun sees for the first time is only written to the database, not reported (watch.firstCheckNotif is false) – to test the notification path, set DIUN_WATCH_FIRSTCHECKNOTIF=true once.

The disk fills up, even though you regularly run docker image prune. docker image prune only clears dangling images, not the old tagged versions. Remove them specifically with docker rmi <image>:<tag> or – with care – docker image prune -a. The build cache (docker builder prune) can grow too.

On pulling you get toomanyrequests / a Docker Hub rate limit. diun.watch_repo=true on many images queries many tags. Set the watch interval less often (e.g. once daily) and narrow with diun.include_tags to relevant versions instead of scanning the whole repo.

Maintenance & backups

The rhythm. Diun reports → you read the release notes → backup → update → verify. In practice that's a manageable appointment once a month; critical security holes you patch immediately. Honestly: safe self-hosting doesn't work entirely without manual work – but 15 minutes a month is the deal.
Fast movers first. Some projects release frequently and with breaking changes – Immich, mailcow, CrowdSec, Grafana and Nextcloud. Those you look at first and more often, quiet candidates (databases, Redis) less so.
Backups are the core of this recipe. An update without a backup is a gamble; with Restic at your back, every update becomes relaxed. Before big jumps, additionally a snapshot – it brings the whole server back in one go.
Version your compose.yaml files. Whoever keeps their Compose files in a Git repo can roll back not only data but also the configuration to any earlier state – and sees in the history exactly which tag was bumped when.
Keep the tools up to date too. Diun itself and your reverse-proxy plugins belong in the update round as well – otherwise the maintainer doesn't maintain itself.

This post first appeared on serverkueche.de.

Docker volumes vs. bind mounts: where your data really lives

serverkueche.de — Sun, 20 Sep 2026 17:52:43 +0000

A container is ephemeral: delete it, and its data is gone. For your database, your Nextcloud files or your configuration to survive a docker compose down, you need volumes. This guide clears up the often confusing difference between named volumes and bind mounts.

What are we building?

No new service this time, but a solid foundation: by the end you understand why container data normally disappears, know the two ways to store it permanently, and know for each service which to use. All examples are tested with Docker 29 on Debian 13 and work with any current Docker version. You need this knowledge for every app tutorial – there, a volumes: block appears in almost every compose.yaml.

Prerequisites

A server with Docker installed
Basic understanding of Docker Compose (services, compose.yaml)
Terminal access to the server – a pure command-line exercise, no web interface

Step by step

Step 1: Why container data disappears

Everything a container writes into its own filesystem only lives as long as the container. That's intended – containers are meant to be replaceable. For anything that should persist (databases, uploads, configuration), you have to tell Docker explicitly where it lands outside the container. That's exactly what the two tools are for: named volumes and bind mounts.

Step 2: Named volumes – managed by Docker

A named volume is a storage area that Docker itself manages. You only give it a name; Docker determines the location. Create one:

docker volume create sk-demo-vol

sk-demo-vol

Now we mount the volume into a throwaway container (--rm deletes it afterwards) at /data and write a file into it:

docker run --rm -v sk-demo-vol:/data alpine:3 sh -c "echo hallo-von-serverkueche > /data/notiz.txt && ls -l /data"

total 4
-rw-r--r--    1 root     root            23 Jul 20 22:31 notiz.txt

The container is long gone – the data isn't. Where does it live? Ask Docker:

docker volume inspect sk-demo-vol --format "{{ .Mountpoint }}"

/var/lib/docker/volumes/sk-demo-vol/_data

This path belongs to Docker. You can view it as root, but shouldn't edit it directly:

cat /var/lib/docker/volumes/sk-demo-vol/_data/notiz.txt

hallo-von-serverkueche

The proof of persistence: a completely new container sees the same data:

docker run --rm -v sk-demo-vol:/data alpine:3 cat /data/notiz.txt

hallo-von-serverkueche

Remember: named volumes are the default for application data – databases, uploads, everything the app manages itself. Docker takes care of location and permissions, and the volume survives docker compose down (only down -v deletes it too).

Step 3: Bind mounts – a folder from the host

With a bind mount you mount a specific folder from your server into the container. You determine the path, and changes are immediately visible on both sides:

mkdir -p /opt/sk-demo-bind
docker run --rm -v /opt/sk-demo-bind:/data alpine:3 sh -c "echo aus-dem-container > /data/host.txt"
ls -l /opt/sk-demo-bind

total 4
-rw-r--r-- 1 root root 18 Jul 21 00:31 host.txt

The container wrote the file, and it lives directly in your host folder – without the detour through /var/lib/docker. That's the point of bind mounts: files you want to edit yourself. Classic cases are configuration files (traefik.yml, nginx.conf) or a compose.yaml that reads in a config.

💡 Tip

Rule of thumb: named volume for data the app manages (database, uploads). Bind mount for files you manage (configuration). When in doubt, named volume – it causes the fewest permission problems.

⚠️ Warning

Never blindly mount sensitive host paths into a container: not /, not /etc, no home directories – and especially not /var/run/docker.sock. Anyone who gets the Docker socket mounted can start arbitrary containers and is thus effectively root on the entire host. Always mount only the one folder the service really needs.

Step 4: Both in the `compose.yaml`

In Compose the difference looks like this. A named volume is declared at the bottom under volumes: and referenced by name above; a bind mount is simply a host path:

services:
  app:
    image: beispiel/app:1
    volumes:
      - app-daten:/var/lib/app                # named volume (Docker-managed)
      - ./config.yml:/etc/app/config.yml:ro   # bind mount (your file, read-only)

volumes:
  app-daten:

The :ro at the end makes the bind mount read-only – the container can read the configuration but not change it. For mounted configs that's a good habit.

Step 5: The trap – anonymous volumes

If you leave out the name with -v (-v /data instead of -v name:/data), or an image brings a VOLUME instruction in its Dockerfile, an anonymous volume with a random ID is created. This is what the first case looks like:

docker run --name demo -v /data alpine:3 sh -c "echo test > /data/x.txt"

We deliberately run the container here without --rm – otherwise Docker would immediately delete the anonymous volume on exit. The everyday problem: such volumes stick around, pile up unnoticed, and you can no longer figure out later which data belongs where:

docker volume ls

DRIVER    VOLUME NAME
local     9f8c1a2b3c4d5e6f70819a0b1c2d3e4f5061a2b3c4d5e6f70819a0b1c2d3e4f5
local     sk-demo-vol

The cryptic line is an anonymous volume. You can now remove the throwaway container – the anonymous volume still stays behind:

docker rm demo

Always give your volumes a name – then it stays clear what belongs to what.

Step 6: Managing volumes

The most important everyday commands:

docker volume ls           # list all volumes
docker volume inspect NAME # details, including the mountpoint
docker volume rm NAME      # delete a volume (data gone!)

We save cleaning up our demo until after the backup section – we still need sk-demo-vol there.

When things go wrong

The container writes, but the bind-mount folder on the host stays empty. You used a relative path that points somewhere other than intended, or Docker created the path anew as an empty folder. with docker run, always give bind mounts an absolute path (/opt/app/config, not config). If this host path doesn't exist yet, Docker silently creates it as an empty folder – so check with ls that you really hit the right one. In the compose.yaml, ./ paths are perfectly fine, on the other hand – they're relative to the compose.yaml and thus unambiguous. Note also: docker run -v config:/data (without / or ./ in front) is not a bind mount, but creates a named volume called config.

Permission denied as soon as the container tries to write into the mount. The process in the container runs under a different UID than the owner of the host folder – typical with bind mounts. with named volumes this rarely happens (Docker sets the permissions). With bind mounts, give the folder to the matching user (chown -R 1000:1000 /opt/app/data) or use the user: setting of the Compose in the image.

After docker compose down all data is gone. You used docker compose down -v – the -v deletes the named volumes too. for a normal restart, work without -v. Use -v deliberately only when you really want to start from scratch.

docker system prune deleted data. docker volume prune or docker system prune --volumes removes volumes that no container is currently attached to. With docker volume prune, named volumes are protected by default – only anonymous volumes are deleted; named ones only go with --all/-a. (With docker system prune, on the other hand, -a/--all controls the images, not the named volumes.) another strong argument for naming – an sk-demo-vol survives an accidental docker volume prune, an anonymous volume doesn't. Still, only run prune with volumes when all important stacks are active, or remove specifically with docker volume rm.

Maintenance & backups

Volumes are not a backup – they live on the same disk as your server. If it fails, container and volume are gone. You back up a named volume by packing its contents into an archive via a throwaway container:

mkdir -p /opt/backups
docker run --rm -v sk-demo-vol:/data -v /opt/backups:/backup alpine:3 \
  tar czf /backup/sk-demo-vol.tar.gz -C /data .

Restoring works the same way around – archive in, unpack into the volume. Create the target volume beforehand (docker volume create sk-demo-vol) and stop the associated container so nothing writes into the open volume:

docker run --rm -v sk-demo-vol:/data -v /opt/backups:/backup alpine:3 \
  tar xzf /backup/sk-demo-vol.tar.gz -C /data

This archive – and all bind-mount folders under /opt – belong in your encrypted off-site backup with Restic. That way your database survives even a total failure of the server.

In everyday use it pays to stay tidy: name volumes descriptively (nextcloud-db, not db), clean up anonymous volumes occasionally, and check with docker system df how much space your volumes take up – with databases and media services in particular, this grows noticeably over time.

Finally, tear down the demo again – now that backup and all examples are done:

docker volume rm sk-demo-vol && rm -rf /opt/sk-demo-bind /opt/backups

This post first appeared on serverkueche.de.

Self-hosting Nextcloud: your own cloud behind Traefik

serverkueche.de — Sat, 25 Jul 2026 12:16:37 +0000

Your files, your calendar, your contacts – but on your server instead of at a cloud corporation. Nextcloud is the flagship of self-hosting: a full-featured cloud you run yourself. In this recipe we set it up cleanly behind Traefik, with its own database, caching and automatic HTTPS.

What are we building?

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

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

ℹ️ Why not Nextcloud AIO?

Nextcloud also offers an "All-in-One" package (AIO). But it brings its own TLS and own ports and wants to handle the reverse-proxy part itself – that clashes with an existing Traefik. For our setup, the classic image is the right, controllable choice.

Prerequisites

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

💡 How big does the server need to be?

Nextcloud is more frugal than its reputation: for private use or a small family (1–5 users), 2 vCPU and 4 GB RAM are quite enough – the tested VPS 1000 fits. The bottleneck is memory: with too little RAM the server starts swapping and gets sluggish. Redis (we build it in shortly) relieves this noticeably. For Nextcloud Office/Collabora or many parallel users you should rather plan for 8 GB.

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

Step by step

Step 1: Create the DNS record

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

dig +short cloud.YOUR_DOMAIN

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

Step 2: Determine the proxy subnet

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

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

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

Step 3: Create the compose.yaml

Create a folder and change into it:

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

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

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

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

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

volumes:
  nc_html:
  nc_db:

networks:
  default:
  proxy:
    external: true

What matters here:

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

⚠️ CalDAV/CardDAV: the .well-known redirect

Nextcloud wants to send calendar/contact clients via /.well-known/caldav and /.well-known/carddav to /remote.php/dav/. Behind a reverse proxy, Nextcloud's own redirect doesn't work reliably – this later leads to a warning in the security check and to problems with calendar setup. The nc-dav middleware above does the redirect directly in Traefik. Important: the pattern must match the full https://… URL – redirectregex always checks the complete URL, not just the path. A pure path pattern like ^/.well-known/… therefore never matches.

Step 4: Start and run through the initial setup

Start the stack:

docker compose up -d

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

docker compose logs -f nc-app

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

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

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

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

Step 5: Set up background jobs (cron)

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

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

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

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

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

💡 occ – the command-line tool

occ is Nextcloud's admin tool. You always call it as the user www-data in the app container: docker exec -u www-data nc-app php occ <command>. Two useful cleanup commands right after installation:
docker exec -u www-data nc-app php occ db:add-missing-indices
docker exec -u www-data nc-app php occ config:system:set default_phone_region --value=DE

Step 6: Connect the clients

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

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

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

⚠️ Don't work with the admin account

The administration account from step 4 is meant for management, not for everyday use. Create a normal user account under Administration → Accounts and sync your files through it. That way your powerful admin account isn't permanently logged in on all devices – a simple but effective security gain. For family or team, create further accounts here; each gets its own encrypted area.

When things go wrong

"Access through untrusted domain" instead of the login page. Your domain isn't in trusted_domains. Check NEXTCLOUD_TRUSTED_DOMAINS in the Compose file. To set it afterwards, use occ: docker exec -u www-data nc-app php occ config:system:set trusted_domains 1 --value=cloud.YOUR_DOMAIN.

The security check reports "Your web server is not set up properly to resolve .well-known/caldav". The CalDAV/CardDAV redirect isn't working. Check the nc-dav middleware labels (step 3) and that the router includes them via ...routers.nc.middlewares=nc-dav. The regex must match the full https://… URL – redirectregex checks the complete URL, not just the path.

Warning "The 'Strict-Transport-Security' HTTP header is not set". The HSTS header is missing. Set it as a Traefik middleware and attach it to the router: traefik.http.middlewares.nc-secure.headers.stsSeconds=15552000. Attach it additionally to the nc-dav middleware on the router (...routers.nc.middlewares=nc-dav,nc-secure). The header must come from the proxy, not from Nextcloud. In part 2 we set up exactly this nc-secure middleware fully (including includeSubdomains).

Large uploads break off or end with a timeout / "413". The PHP limit is too small. Increase PHP_UPLOAD_LIMIT and PHP_MEMORY_LIMIT (step 3) and restart the container. In rare cases these variables don't take effect – then mount your own php.ini snippet into the image.

On the first start the installation aborts with "MySQL server has gone away" or "Connection refused". The app container was faster than the database. That's exactly what the healthcheck with depends_on: condition: service_healthy is for – check that both are present in your Compose file, and restart with docker compose up -d.

Maintenance & backups

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

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

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

Updates: only one major version per step. From 34 to 35, never directly to 36. Bump the image tag (nextcloud:35-apache), then docker compose pull and docker compose up -d. The container runs the necessary occ upgrade automatically on start. Always make a backup first. Bump the cron sidecar to the same version.
Check security. After setup, run the official Nextcloud Security Scan against your domain (target: grade A) and work through the warnings from the admin overview. The overview under Administration → Overview runs automatic checks and shows exactly what's still missing. Keep Nextcloud up to date – security holes are closed promptly, but only if you update.
Honest about the effort: a self-hosted cloud wants to be maintained. Reckon with an update pass roughly monthly and a regular look at the admin overview. In return, the data then really belongs to you.

This post first appeared on serverkueche.de.

Self-hosting Immich: your private photo backup behind Traefik

serverkueche.de — Sat, 25 Jul 2026 07:06:44 +0000

Thousands of photos and videos from your phone – and all of them at Google or Apple. Immich brings them back to your server: a self-hosted photo service that comes astonishingly close to Google Photos, including automatic phone upload, timeline, search and face recognition. In this recipe we set up Immich cleanly behind Traefik.

What are we building?

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

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

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

⚠️ Immich moves fast – pin the version

Immich develops rapidly. Database migrations run automatically on update and are not backward-compatible – a downgrade is no longer cleanly possible afterwards. So always pin a fixed version (here v3.1.0) instead of release or latest, and make a backup before every update. That way you decide when to update.

Prerequisites

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

💡 How big does the server need to be?

Immich is the most resource-hungry service in the Serverküche. Officially, at least 6 GB RAM (8 recommended) are required – the machine-learning service for face recognition and search in particular needs memory. The tested VPS 1000 with 8 GB RAM just meets that but has little reserve. For a large library or several users, a server with 16 GB RAM (e.g. VPS 2000) is more relaxed. On a 4 GB server, Immich only runs with ML turned off (see "When things go wrong"). And: photos need space – plan for enough disk.

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

Step by step

Step 1: Create the DNS record

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

dig +short photos.YOUR_DOMAIN

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

Step 2: Prepare the folder and .env

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

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

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

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

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

Step 3: Create the compose.yaml

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

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

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

  redis:
    image: docker.io/valkey/valkey:9
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping || exit 1"]
    networks: [default]
    restart: unless-stopped

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

volumes:
  model-cache:

networks:
  default:
  proxy:
    external: true

Important to understand:

Only immich-server is on the proxy network and carries Traefik labels. The ML service, Valkey and the database stay exclusively on the internal default network – not reachable from outside.
loadbalancer.server.port=2283 – Immich listens on port 2283 in the container.
The database is deliberately the prebuilt Immich Postgres image with the vector extension VectorChord (for image search). Don't just use a standard postgres – the extension is then missing.
POSTGRES_INITDB_ARGS and shm_size are in the official template too: --data-checksums makes Postgres write checksums when the database is created so that silent data corruption gets noticed; shm_size: 128mb raises Docker's tight 64 MB default for /dev/shm, on which larger queries would otherwise fail. The checksums only take effect on a freshly created database – on an instance that is already running, the entry changes nothing.
Valkey is the Redis successor; the service is still called redis in the Immich template for compatibility reasons.
The healthcheck on the database reports when Postgres is really ready. Via depends_on: … condition: service_healthy, immich-server only starts then – this prevents migration errors and the "database not reachable" start on the first boot.

💡 Applying changes to the .env

If you later change something in the .env, a docker compose restart is not enough – Docker only reads the environment variables when recreating the containers. Use docker compose up -d then; Compose detects the change and rebuilds the affected containers.

Step 4: Allow large uploads (Traefik timeout)

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

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

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

Step 5: Start and run through the initial setup

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

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

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

docker compose ps

All four services have to show up in the SERVICE column – immich-server, immich-machine-learning, redis and database. Under STATUS, the server, the ML service and the database read Up … (healthy); redis does too, because we adopted the healthcheck from the official template. Now wait until Immich Server is listening on http://[::1]:2283 [v3.1.0] [production] appears in the log, then open https://photos.YOUR_DOMAIN. Traefik fetches the Let's Encrypt certificate on the first access (be patient for a moment). On the very first start, Immich greets you with "Welcome to Immich" and the choice of whether you start fresh or restore a backup:

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

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

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

Step 6: Connect the phone app

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

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

After the upload, Immich keeps working in the background: it generates thumbnails, reads the capture metadata (date, location) and lets the ML service recognize faces and index the images for smart search. These jobs run for some time after the first big import – so faces and search hits only appear gradually. You see the progress under Administration → Job Queues. In the sidebar you then find the typical photo features: Explore (by people and places), the map with geolocation, sharing and albums. The memories ("a year ago") show up by themselves as soon as older shots are in the library. How to tame the ML jobs, switch to a better search model and connect the mobile app properly is covered in Optimize Immich and use it on mobile.

ℹ️ Videos & transcoding on the VPS

Immich converts videos for playback in the browser (transcoding). On a normal VPS without a graphics card this happens via the CPU – with many or long videos this is noticeably slower and maxes out cores. For a private phone backup this is usually no problem; whoever has a lot of video should choose the server correspondingly larger.

💡 More users

For the family, create further accounts under Administration → Users – each gets its own separate library. Registration from outside is off by default; new users only arise via the admin account.

⚠️ Your photos are on the internet

As soon as Immich is reachable via photos.YOUR_DOMAIN, the login page is open on the net. So set a long, unique password for the admin and all user accounts. Immich v3 has no built-in two-factor authentication – the account settings only offer a password and a PIN code for the locked folder. You only get a second factor through an upstream login service via OAuth/OIDC, for example with
Authentik (Tutorial expected in October). Whoever wants to be extra safe makes Immich reachable only via a WireGuard VPN – but for automatic phone upload, direct HTTPS reachability is usually the more practical way.

When things go wrong

Uploads of large videos abort after about a minute (error 502 or 499). Traefik's readTimeout (default 60 s) kicks in. Set it to 600s (or higher) as in step 4 and restart Traefik. This is by far the most common Immich-behind-proxy error.

The immich-machine-learning container crashes or exits with "exit 137", search and face recognition don't work. Too little RAM – the container was killed by the system (out of memory). Give the server more memory, or disable ML by removing the service immich-machine-learning from the compose.yaml. Immich then runs without face recognition and smart search, but upload and timeline work normally.

After an update the containers no longer start or report migration errors. Server, machine learning and database must run on the same version. Set the new IMMICH_VERSION in the .env and update all containers together (docker compose pull && docker compose up -d). A downgrade after a migration isn't possible – only a reset from the backup.

Immich shows "maintenance mode" / "temporarily unavailable". Immich v3 starts into a maintenance mode under certain database states. The log (docker compose logs immich-server) then contains a URL with a one-time token (…/maintenance?token=…) – through it you log into the maintenance mode and choose "restart" or end it. After that the normal interface is back.

Container won't start, "permission denied" on the database or upload directory. UPLOAD_LOCATION or DB_DATA_LOCATION have the wrong access rights or are on a network drive. Put both on a local disk and make sure Docker may write into them.

Maintenance & backups

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

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

Back up the dump together with the library folder encrypted and off-site with Restic. On top of that, Immich creates regular database dumps of its own under Administration → Settings → Database Dump Settings (they land in UPLOAD_LOCATION/backups) – you still have to back up the photos separately, and these dump jobs are not monitored: Immich does not notify you when one of them fails.

Rehearse the worst case once. A backup you've never restored is just a hope. To restore, you import the DB dump into a fresh Immich instance of the same version and place the library folder in the same spot – Immich offers the option "Restore From Backup" on the first start for this (the second button from step 5). What matters is the same version: the database state and the program must match.
Backup before every update. Because migrations aren't reversible, the backup is your only way back. Back up first, then raise IMMICH_VERSION, then docker compose pull && docker compose up -d.
Honest about the effort: Immich often brings several releases per month. You don't have to follow every one – but before a jump across several versions, read the release notes, and stick to the pinned version until you deliberately update.
Keep an eye on disk space. Photos and videos grow steadily; Immich additionally creates thumbnails and converted videos. Monitor the disk usage (e.g. with Uptime Kuma) so the server doesn't fill up.

This post first appeared on serverkueche.de.

Installing Uptime Kuma: server monitoring behind Traefik

serverkueche.de — Fri, 24 Jul 2026 21:44:39 +0000

Traefik is up – now we hang the first real app behind it. Uptime Kuma is ideal for that: tiny, immediately useful and without a database. It monitors your services and raises the alarm when one fails – from now on you notice first that something is stuck, not your users. Along the way you learn the pattern every further app repeats.

What are we building?

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

Prerequisites

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

Step by step

Step 1: The compose.yaml

Own folder, own file:

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

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

volumes:
  kuma-data:

networks:
  proxy:
    external: true

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

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

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

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

Step 2: Start and first login

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

When Kuma is ready, the log ends with Waiting for user action... – from here the service waits for the initial setup in the browser (Ctrl+C only ends the following):

Welcome to Uptime Kuma
Your Node.js version: 22.22.3
2026-09-09T10:53:28Z [SERVER] INFO: Uptime Kuma Version: 2.5.3
2026-09-09T10:53:30Z [SETUP-DATABASE] INFO: Starting Setup Database
2026-09-09T10:53:30Z [SETUP-DATABASE] INFO: Listening on:
2026-09-09T10:53:30Z [SETUP-DATABASE] INFO: -  http://localhost:3001
2026-09-09T10:53:30Z [SETUP-DATABASE] INFO: Waiting for user action...

Kuma does not create the database yet – it deliberately waits for your choice in the browser. So open https://status.YOUR_DOMAIN. Uptime Kuma 2.x first asks for the database – for a setup like ours, SQLite is the right, simplest choice (select it, click Next). Right after that you create the admin account (username + strong password).

⚠️ Create the admin account immediately

As long as no admin account exists, anyone who opens the page can create one. Do this right after the first start – not "later".

Step 3: Create the first monitor

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

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

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

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

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

Create the matching monitor for every important service.

💡 Tip

Check public services via their real domain (https://…), not via localhost. This way you simultaneously test that Traefik and the certificate work from outside – not just that the container is running.

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

Step 4: Set up notifications (email and Telegram)

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

Email (SMTP)

Choose "Email (SMTP)" as the notification type and enter your mail provider's data:

Hostname / Port: e.g. smtp.YOUR_PROVIDER.com and 587
Security: exactly two entries to pick from – None / STARTTLS (25, 587) for port 587 (Kuma negotiates STARTTLS itself) and TLS (465) for port 465
Username / Password: your SMTP credentials
From Email / To Email: which address the warning comes from and which it's sent to

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

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

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

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

⚠️ Otherwise the alarm stays silent

A configured notification does not take effect automatically. Enable it in each monitor (checkbox in the monitor form) or, in the notification dialog, turn on "Default enabled" and "Apply on all existing monitors".

If you want push messages entirely under your own control (without a Telegram server), take
ntfy – self-hosted, with its own recipe in the series. Kuma knows it as the built-in notification type Ntfy.

Step 5: A public status page (optional)

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

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

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

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

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

Retries: the service only counts as "Down" after n failed checks. 2–3 filters out individual dropouts without obscuring real outages for long.
Heartbeat Retry Interval: Kuma may check more often in the error case (e.g. every 20 seconds) to detect recovery quickly. The field only appears once Retries is greater than 0.
Resend Notification if Down X times consecutively: Kuma reminds you again every X failed checks as long as a service is down – useful so an outage at night doesn't get lost in a single mail. 0 turns resending off.

💡 Plan maintenance windows

If you plan an update with downtime, create a maintenance window under Maintenance. Kuma then pauses the alarms for the affected monitors – so you (and the status page) don't get false alarms while you're at work.

Step 7: Monitor cron jobs with a push monitor

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

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

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

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

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

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

Step 8: Secure the admin login with 2FA

Your Kuma login protects access to all monitors, the stored notification credentials and the status-page configuration – and it's publicly on the net. So enable two-factor authentication: under Settings → Security → Two Factor Authentication → 2FA Settings. Kuma first asks for your current password; after Enable 2FA the QR code appears, which you scan with an authenticator app (e.g. Aegis or 2FAS). Enter the generated code, click Verify Token and then Save – without that last click, 2FA stays inactive.

💡 Secure the recovery

Keep the TOTP secret or a second authenticator in a safe place (password manager) – in the same dialog, Show URI reveals the secret as an otpauth:// URI you can store there. If you lose your phone and have no copy, you can otherwise only get back in via the database in the kuma-data volume.

When things go wrong

Bad Gateway (502) when opening status.YOUR_DOMAIN. Almost always the port label traefik.http.services.kuma.loadbalancer.server.port=3001 is missing or has a wrong port. Traefik then reaches the container but knocks on the wrong port. Check the label and run docker compose up -d again.

404 page not found instead of Kuma. As with every app behind Traefik: traefik.enable=true set? Container on the proxy network? Is the domain in the Host(...) rule correct and does the DNS record status.YOUR_DOMAIN point to the server? The Traefik dashboard shows under "HTTP Routers" whether kuma is registered.

The interface loads, but the live update stutters / breaks off. Kuma uses WebSockets. Traefik forwards those correctly by default – if the problem still occurs, it's usually an upstream CDN/proxy (e.g. Cloudflare in "proxy" mode) that blocks WebSockets. For direct operation behind Traefik, no extra configuration is needed.

After a re-setup all monitors are gone. The kuma-data volume was deleted (e.g. by docker compose down -v). All configuration and history lives solely in this volume – that's why it's at the top of the next section.

Maintenance & backups

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

This post first appeared on serverkueche.de.

Vaultwarden: your own password manager behind Traefik

serverkueche.de — Fri, 24 Jul 2026 21:36:20 +0000

Passwords belong in a password manager – but do they have to live in the cloud of some third-party provider? With Vaultwarden you host your own, encrypted and under your control. It speaks the Bitwarden language, so you use the familiar Bitwarden apps and browser extensions – they just point at your server.

What are we building?

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

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

ℹ️ Vaultwarden ≠ Bitwarden

Vaultwarden is an unofficial, community-driven project that reimplements the Bitwarden server API. It's not affiliated with Bitwarden Inc. For private and small-team use it's excellent; the clients (apps, extensions) are the real, official ones from Bitwarden.

Prerequisites

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

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

Step by step

Step 1: Generate the ADMIN_TOKEN

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

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

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

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

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

Password:
Confirm Password:

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

Generation of the Argon2id PHC string took: 21.709159ms

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

💡 Why the detour via the hash?

You could also set the ADMIN_TOKEN as a plaintext password. The hash is safer, though: even someone who gets hold of your compose.yaml can't compute your panel password back from it. --preset owasp chooses Argon2 parameters per the current OWASP recommendation.

Step 2: Create the compose.yaml

Create a dedicated folder and change into it:

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

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

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

networks:
  proxy:
    external: true

The most important lines in detail:

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

Step 3: Start it and the first call

Start the container:

docker compose up -d

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

docker compose logs -f vaultwarden

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

[2026-08-01 23:35:51.515][start][INFO] Rocket has launched from http://0.0.0.0:80

With Ctrl+C you leave the log view again (the container keeps running).

The Vaultwarden image ships its own healthcheck, and Traefik only forwards to containers that count as healthy. Right after the start your domain therefore answers with a bare 404 page not found from Traefik for up to a minute – that's normal, not a configuration error. Just check the status in the meantime:

docker compose ps

As long as it still says (health: starting), Traefik is waiting. After the first successful healthcheck (it runs on a 60-second interval) the line looks like this:

NAME                        IMAGE                       COMMAND       SERVICE       CREATED         STATUS                   PORTS
vaultwarden-vaultwarden-1   vaultwarden/server:1.37.2   "/start.sh"   vaultwarden   2 minutes ago   Up 2 minutes (healthy)   80/tcp

Now open https://vault.YOUR_DOMAIN in the browser. On the first access Traefik fetches the Let's Encrypt certificate – that can take a few more seconds. After that the Bitwarden web interface appears.

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

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

🛑 The master password is not recoverable

Your master password is never transmitted to the server; it decrypts your vault locally. If you forget it, all passwords stored in it are lost – no one, not even you, can recover them. Choose a long, unique passphrase and keep it in a safe place (e.g. printed out in a safe).

Step 4: Close registration again

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

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

And apply the change:

docker compose up -d

Compose detects the changed environment variable and recreates the container (Container vaultwarden-vaultwarden-1 Recreated). As with the first start it then takes up to a minute until the healthcheck passes and Traefik picks up the new container – before that you see the 404 page not found again. From now on the login page rejects new registrations with Registration not allowed or user already exists. Further users (e.g. for the family) you invite specifically via the admin panel when needed – more on that shortly.

⚠️ Don't forget

An open SIGNUPS_ALLOWED: "true" is the most common misconfiguration with self-hosted Vaultwarden. Anyone who knows your domain could otherwise create an account. This step is mandatory, not an extra.

Step 5: The admin panel

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

Here you control the service centrally:

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

💡 Settings in the panel vs. environment variables

What you save in the admin panel is stored in vw-data/config.json and overrides the environment variables from the compose.yaml. Decide per setting on one way to avoid confusion. For the basic configuration (domain, token, signups) we deliberately stick with the Compose file – it's versionable and reproducible.

Step 6: Connect the clients

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

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

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

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

⚠️ Securely delete export files afterwards

An export CSV contains all passwords in plaintext. Delete the file immediately after a successful import – and empty the trash. Never leave it lying in Downloads or a cloud folder.

💡 Enable two-factor authentication

In your vault's account settings, enable 2FA (e.g. via an authenticator app). That way, even with a cracked master password, your vault isn't immediately open. For email-based 2FA, SMTP must be set up in the admin panel first.

When things go wrong

The container exits again immediately, the log says No persistent volume!. The volumes: mapping is missing. Vaultwarden then aborts with the box "It looks like you did not configure a persistent volume!" and exits with code 1, so your passwords don't end up in an ephemeral container. Add ./vw-data:/data as in step 2 and restart.

The web interface shows "You need to enable HTTPS!" or the login fails with crypto errors. Vaultwarden uses the browser's Web Crypto API, which is only available in a secure context (real HTTPS). You opened the page over http:// or with an invalid certificate. Make sure Traefik fetched a valid Let's Encrypt certificate (check the Traefik log) and that you reach the page over https://. The DOMAIN variable must also start with https://.

The admin panel rejects your password, even though it's correct. Probably the dollar signs in the ADMIN_TOKEN aren't doubled. In the compose.yaml every $ must become $$. Check with docker compose exec vaultwarden printenv ADMIN_TOKEN how the token really arrives inside the container – there it has to be a single $ again. (docker compose config won't help: it shows the file with the doubled $$.) Also remember: at login you enter the password, not the hash.

The phone app can't find the server or reports "Server URL invalid". The server URL must be the full https:// address without a trailing path (https://vault.YOUR_DOMAIN). Also check whether the domain is reachable from outside via a browser and the certificate is valid – apps are stricter about certificate errors than browsers.

Despite SIGNUPS_ALLOWED=false, someone was able to register. The setting was probably set in the admin panel and overrides the environment variable, or the container wasn't restarted after the change. Check the value under Settings → General settings in the panel and restart with docker compose up -d.

Maintenance & backups

Backups are non-negotiable for a password manager. Your entire vault is in the vw-data/ directory (SQLite database, keys, attachments). Back it up encrypted and off-site with Restic – add the folder ~/vaultwarden/vw-data to your backup sources. For a consistent database state, briefly run docker compose stop before the backup, or use the "Backup Database" function in the admin panel. A mere file copy while the container is running can catch an inconsistent state (SQLite writes into WAL files) – with a password manager that's not a risk worth taking.
Apply updates in a controlled way. Because we pinned the version, you update deliberately: before the switch read the release notes, then raise the tag in the compose.yaml (e.g. to the next 1.x) and pull anew:

  docker compose pull && docker compose up -d

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

Keep registration closed. Occasionally check that SIGNUPS_ALLOWED is still false – always invite new users specifically via the admin panel.
Rotate the ADMIN_TOKEN if it might be compromised: generate a new hash with the hash command from step 1, replace it in the compose.yaml, restart.
Never lose the master password. There is no recovery. In a team/family setup, an emergency access can make sense – you set that up per vault in the account settings.

This post first appeared on serverkueche.de.

Paperless-ngx selbst hosten: papierloses Büro mit OCR

serverkueche.de — Mon, 20 Jul 2026 21:15:45 +0000

Rechnungen, Verträge, Behördenpost – der Papierstapel wächst und wächst, und finden tust du
am Ende doch nie etwas. Paperless-ngx macht daraus ein durchsuchbares digitales Archiv: Du wirfst ein
Dokument hinein, es wird per OCR erkannt, verschlagwortet und ist über die
Volltextsuche in Sekunden wieder da. In diesem Rezept setzen wir es hinter Traefik auf.

Was bauen wir?

Am Ende läuft Paperless-ngx 2.20 hinter deinem Traefik-Proxy, erreichbar unter
https://paperless.DEINE_DOMAIN mit HTTPS. Paperless ist ein Dokumenten-Management-System:
Du fütterst es mit Scans oder PDFs, es liest den Text per OCR aus (auch aus reinen
Bild-Scans), erkennt Datum und Inhalt und legt alles durchsuchbar ab. Über Tags,
Korrespondenten und Dokumenttypen bringst du Ordnung hinein; die Volltextsuche findet
später jedes Dokument.

Der Clou ist der Consume-Ordner: Alles, was du dort ablegst (z. B. vom Netzwerk-Scanner),
wird automatisch importiert und verarbeitet. Paperless besteht aus fünf Containern –
dem Webserver, einer PostgreSQL-Datenbank, einem Redis-Broker für die
Hintergrundverarbeitung sowie Gotenberg und Tika, die Office-Dokumente in PDF
umwandeln. Die offizielle Vorlage liefert das komplette Gespann.

Der Gewinn gegenüber einem Ordner voller PDFs auf der Festplatte: Paperless macht jedes
Dokument durchsuchbar (auch eingescanntes Papier), hält Original und Archivversion
sauber getrennt und lässt sich per Regeln automatisieren. Deine Unterlagen bleiben dabei
auf deinem Server – kein Cloud-Dienst liest mit, und du bist nicht an ein proprietäres
Format gebunden.

Voraussetzungen

Ein laufender Traefik-Reverse-Proxy mit dem proxy-Netzwerk und dem Resolver le – siehe Reverse Proxy mit Traefik.
Eine Subdomain paperless.DEINE_DOMAIN mit DNS-Record auf deine Server-IP – siehe Domain mit Server verbinden.
Ein Backup. In Paperless landen deine wichtigsten Unterlagen – richte zuerst Backups mit Restic ein.

💡 Wie groß muss der Server sein?

Paperless selbst ist genügsam, aber es sind fünf Container, und die OCR-Verarbeitung ist
CPU-lastig: Beim Erkennen eines Scans läuft ein Kern für einige Sekunden bis Minuten auf
Anschlag. Für den privaten Gebrauch reichen 2 vCPU und 4 GB RAM gut; der getestete VPS
1000 (4 vCore / 8 GB) hat reichlich Luft. Beim Massenimport vieler Dokumente merkst du die
CPU-Last – dann verarbeitet Paperless die Warteschlange eben nach und nach ab.

Unsicher, welche Server-Größe reicht? Der Server-Rechner rechnet dir
RAM- und CPU-Bedarf für deine Dienste aus.

Schritt für Schritt

Schritt 1: DNS-Record anlegen

Lege paperless.DEINE_DOMAIN an (A/AAAA auf deine Server-IP) und prüfe:

dig +short paperless.DEINE_DOMAIN

Es muss deine Server-IP zurückkommen – sonst holt Traefik später kein Zertifikat.

Schritt 2: Einen Secret Key erzeugen

Paperless verschlüsselt Sitzungen mit einem geheimen Schlüssel. Der Default ist öffentlich
bekannt – bei einer Instanz im Internet ein echtes Risiko. Erzeuge einen eigenen:

head -c 50 /dev/urandom | base64

Kopiere die Ausgabe – sie kommt gleich als PAPERLESS_SECRET_KEY in die Konfiguration.

Schritt 3: Die compose.yaml anlegen

Leg das Projekt an – inklusive der beiden Bind-Mount-Ordner:

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

Die Unterordner consume und export legst du bewusst jetzt, als normaler
Benutzer an: Würde erst der Docker-Daemon sie beim Start erzeugen, gehörten sie
root – dann könnten weder du (cp in den Consume-Ordner) noch Paperless selbst
(läuft via USERMAP_UID als UID 1000) hineinschreiben.

Erstelle compose.yaml. Ersetze paperless.DEINE_DOMAIN, die Passwörter und den
PAPERLESS_SECRET_KEY:

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

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

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

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

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

volumes:
  data:
  media:
  pgdata:
  redisdata:

networks:
  default:
  proxy:
    external: true

Die wichtigsten Punkte:

Nur webserver hängt im proxy-Netz und trägt Traefik-Labels (Port 8000). Die vier Hilfsdienste (db, broker, gotenberg, tika) bleiben intern.
PAPERLESS_URL ist Pflicht hinter einem Proxy. Fehlt sie, weist Paperless den Login mit einem CSRF-/„403 Forbidden"-Fehler ab. Sie setzt zugleich die erlaubten Hosts und die vertrauenswürdigen Ursprünge.
PAPERLESS_OCR_LANGUAGE: deu stellt die Texterkennung auf Deutsch. Deutsch, Englisch und ein paar weitere Sprachen sind im Image bereits enthalten – kein Zusatzpaket nötig.
PAPERLESS_ADMIN_USER / _PASSWORD legen beim ersten Start automatisch den Superuser an, sodass du dich direkt anmelden kannst.
USERMAP_UID/GID sollten zur Kennung deines Server-Benutzers passen (per id -u bzw. id -g ermitteln, meist 1000). Sonst gibt es „Permission denied" im Consume-Ordner.
export und consume sind bewusst Ordner im Projektverzeichnis (Bind-Mounts): consume ist der Eingangskorb, export das Ziel für Backups.

Paperless nutzt insgesamt vier Speicherbereiche, die du auseinanderhalten solltest:
media enthält deine verarbeiteten Dokumente (das Herzstück!), data den Suchindex und
Hilfsdaten, consume ist der Eingangskorb und export das Backup-Ziel. Fürs Backup zählen
media und data sowie die Datenbank – genau das nimmt dir der document_exporter weiter
unten ab.

Schritt 4: Starten und anmelden

Zieh die Images (mehrere GB) und starte:

docker compose up -d
docker compose logs -f webserver

Beim ersten Start richtet Paperless die Datenbank ein (Migrationen) – das dauert einen
Moment. Prüfe, dass alle fünf Container laufen:

docker compose ps

Du solltest webserver, db, broker, gotenberg und tika mit Status running sehen
(der webserver wird nach kurzer Zeit healthy). Ist der Worker bereit (celery@… ready
im Log), ruf https://paperless.DEINE_DOMAIN auf. Es erscheint die Anmeldeseite:

Melde dich mit admin und deinem Passwort an. Du landest auf der Startseite mit einer
kurzen Willkommensmeldung und ersten Statistiken. Ganz unten links siehst du die laufende
Version – praktisch, um vor einem Update den Ausgangsstand zu kennen. Die Sprache
kannst du bei Bedarf unter Einstellungen umstellen; standardmäßig folgt Paperless der
Sprache deines Browsers:

Schritt 5: Das erste Dokument einlesen

Jetzt der Kern. Es gibt drei Wege, ein Dokument hineinzubekommen:

Über die Weboberfläche: oben rechts auf Dokumente hochladen und eine PDF- oder Bilddatei auswählen.
Über den Consume-Ordner: Leg eine Datei in ~/paperless/consume – Paperless erkennt sie automatisch, verarbeitet sie und löscht sie danach aus dem Ordner. Ideal für einen Netzwerk-Scanner, der direkt dorthin scannt.
Aus einem Postfach: Paperless kann unter E-Mail ein IMAP-Konto abrufen und Anhänge automatisch einlesen – praktisch für Rechnungen, die dir ohnehin per Mail kommen.

cp ~/eine-rechnung.pdf ~/paperless/consume/

Paperless nimmt PDFs, Bilder (JPG/PNG/TIFF) und – dank Gotenberg und Tika – auch
Office-Dateien wie Word oder Excel an. Bei einem reinen Bild-Scan liest die OCR den Text
aus und legt ihn als durchsuchbare Ebene über das Dokument; bei einem PDF mit vorhandenem
Textlayer überspringt Paperless die Erkennung und ist entsprechend schneller. Das Original
bleibt dabei unangetastet erhalten – Paperless erzeugt zusätzlich eine durchsuchbare
Archiv-Version.

Nach ein paar Sekunden (OCR braucht etwas Zeit) taucht das Dokument unter Dokumente auf –
mit einer Vorschau und dem erkannten Titel:

Ein Klick öffnet die Detailansicht: links die Metadaten (Titel, Datum, Korrespondent,
Tags) und die Reiter für Inhalt, Metadaten und Verlauf, rechts das Dokument mit einer
zoombaren Vorschau. Paperless hat aus dem Scan bereits das Datum erkannt und
schlägt es zur Bestätigung vor – genau das leistet die OCR im Hintergrund für dich:

Schritt 6: Ordnung mit Tags, Korrespondenten & Dokumenttypen

Damit die Suche später greift, vergibst du Tags (z. B. Steuer, Versicherung),
ordnest einen Korrespondenten (den Absender) und einen Dokumenttyp (Rechnung,
Vertrag …) zu. Das kannst du von Hand machen – oder Paperless über Arbeitsabläufe
automatisieren: Regeln, die eingehende Dokumente anhand ihres Inhalts automatisch
verschlagworten. So sortiert sich dein Archiv mit der Zeit von selbst.

Die Volltextsuche oben durchsucht danach nicht nur Titel und Tags, sondern den
kompletten erkannten Text – eine Suche nach Rechnungsbetrag oder einem Kundennamen findet
das passende Dokument in Sekunden. Kombiniert mit den Filtern (Korrespondent, Zeitraum,
Dokumenttyp) wird der Papierstapel endgültig zum durchsuchbaren Archiv.

Ein einfaches Beispiel für einen Arbeitsablauf: Enthält ein neues Dokument das Wort
„Stromabrechnung", vergib automatisch den Tag Energie, setz den Korrespondenten auf deinen
Stromanbieter und den Dokumenttyp auf Rechnung. Solche Regeln legst du unter
Verwaltung → Arbeitsabläufe an; sie greifen bei jedem eingehenden Dokument. Anfangs
lohnt es sich, ein paar Dokumente von Hand zu sortieren – daraus siehst du schnell, welche
Regeln sich wiederholen und automatisieren lassen. Nach ein paar Wochen landet der Großteil
deiner Post ohne dein Zutun am richtigen Platz.

💡 Scanner direkt in den Consume-Ordner

Der volle Komfort entsteht mit einem Dokumentenscanner. Richte auf dem Server eine
Netzwerkfreigabe (z. B. Samba) ein, die auf ~/paperless/consume zeigt, und stelle deinen
Scanner so ein, dass er dorthin scannt. Ab dann gilt: Blatt einlegen, Knopf drücken – wenige
Sekunden später ist das Dokument erkannt, verschlagwortet und durchsuchbar im Archiv. Für
unterwegs gibt es zudem Community-Apps (z. B. „Paperless Mobile"), die sich mit deiner
Instanz verbinden.

⚠️ Deine Unterlagen hängen im Internet

In Paperless liegen sensible Dokumente – Rechnungen, Verträge, Behördenpost. Sobald die
Instanz über paperless.DEINE_DOMAIN erreichbar ist, steht die Anmeldeseite offen im Netz.
Vergib deshalb ein langes, einmaliges Passwort, und aktiviere unter Einstellungen die
Zwei-Faktor-Authentifizierung. Wer maximale Sicherheit will, macht Paperless nur über ein
VPN erreichbar – für ein reines Privatarchiv, das nur du nutzt, ist das eine Überlegung wert.

Wenn es nicht funktioniert

Symptom: Beim Login erscheint „Forbidden (403)" oder „CSRF verification failed".

Ursache & Lösung: PAPERLESS_URL ist nicht oder falsch gesetzt. Sie muss exakt deiner
HTTPS-Adresse entsprechen (https://paperless.DEINE_DOMAIN, ohne Schrägstrich am Ende).
Nach der Korrektur docker compose up -d.

Symptom: Dateien im Consume-Ordner werden nicht verarbeitet, „permission denied".

Ursache & Lösung: Häufigste Ursache: Die Ordner wurden nicht vorab angelegt
(Schritt 3), sondern beim ersten Start vom Docker-Daemon erzeugt – dann gehören sie
root. Mit sudo chown -R $(id -u):$(id -g) ~/paperless/consume ~/paperless/export
gehören sie wieder dir. Ansonsten: USERMAP_UID/USERMAP_GID passen nicht zum
Besitzer des Ordners – ermittle deine Kennung mit id -u und id -g, trag die Werte
ein und starte neu.

Symptom: Hochgeladene Dokumente bleiben „in Bearbeitung" hängen.

Ursache & Lösung: Die Hintergrundverarbeitung läuft über Redis. Prüfe, dass der
broker-Container läuft, und sieh unter Dateiaufgaben nach der Fehlermeldung der
fehlgeschlagenen Aufgabe.

Symptom: Die Texterkennung liefert Unsinn oder erkennt nichts.

Ursache & Lösung: Falsche OCR-Sprache. Setz PAPERLESS_OCR_LANGUAGE=deu (oder
deu+eng für gemischte Dokumente). Nur installierte Sprachen funktionieren.

Symptom: Office-Dokumente (Word, Excel) werden nicht angenommen oder enden im Timeout.

Ursache & Lösung: Dafür sind Gotenberg und Tika zuständig. Prüfe, dass beide Container
laufen und PAPERLESS_TIKA_ENABLED=1 samt der beiden Endpoint-Variablen gesetzt ist.

Symptom: Beim Massenimport wird der Server sehr langsam, die CPU ist dauerhaft am Anschlag.

Ursache & Lösung: OCR ist rechenintensiv, und Paperless nutzt standardmäßig alle Kerne.
Auf kleinen Servern kannst du die Last drosseln, indem du die Zahl der Worker bzw. Threads
begrenzt (PAPERLESS_TASK_WORKERS, PAPERLESS_THREADS_PER_WORKER). Dann dauert der Import
länger, aber die Oberfläche bleibt bedienbar.

Wartung & Backups

Das saubere Backup macht der document_exporter. Er schreibt alle Dokumente, Vorschaubilder, Metadaten und den Datenbankinhalt in den export-Ordner – portabel und wieder importierbar:

  docker compose exec -T webserver document_exporter ../export

Sichere den export-Ordner anschließend verschlüsselt und off-site mit
Restic. Alternativ sicherst du die Volumes media,
data und die Datenbank direkt – der Exporter ist aber der empfohlene, umzugssichere Weg.

Beim Wiederherstellen die gleiche Version verwenden. Ein Export enthält ein Abbild passend zum Datenbank-Schema; spiel ihn nur in eine Paperless-Instanz derselben Version ein (document_importer ../export).
Updates. Vor dem Update ein Backup ziehen, dann den Image-Tag erhöhen (z. B. 2.20.15 → nächste Version), docker compose pull und docker compose up -d. Die Datenbank-Migrationen laufen beim Start automatisch. Bleib bei der stabilen 2.x-Reihe – die 3.0-Beta ist noch nicht für den Produktivbetrieb gedacht.
Backup automatisieren. Den document_exporter legst du am besten in einen täglichen Cron-Job (z. B. nachts), der anschließend den export-Ordner per Restic sichert. So hast du jeden Morgen einen frischen, wiederherstellbaren Stand – ohne daran denken zu müssen.
Ehrlich zum Aufwand: Paperless läuft danach sehr wartungsarm. Der eigentliche Aufwand ist das Einsortieren neuer Dokumente – das nimmt dir mit etwas eingerichteter Automatik aber zunehmend die Software ab. Plane einmal die grobe Tag-Struktur, dann trägt sich das Archiv weitgehend selbst.

Dieser Beitrag erschien zuerst auf serverkueche.de.

Uptime Kuma installieren: Server-Monitoring hinter Traefik

serverkueche.de — Sun, 19 Jul 2026 20:37:39 +0000

Traefik steht – jetzt hängen wir die erste echte App dahinter. Uptime Kuma ist
dafür ideal: winzig, sofort nützlich und ohne Datenbank. Es überwacht deine Dienste
und schlägt Alarm, wenn einer ausfällt – ab jetzt merkst du zuerst, dass etwas
klemmt, nicht deine Nutzer. Nebenbei lernst du das Muster, das jede weitere App
wiederholt.

Was bauen wir?

Am Ende läuft Uptime Kuma 2.4 unter https://status.DEINE_DOMAIN, abgesichert
über Traefik mit automatischem HTTPS. Du hast den ersten Monitor eingerichtet (der
prüft im Minutentakt, ob ein Dienst antwortet), eine Benachrichtigung verbunden und
optional eine öffentliche Status-Seite. Zum ersten Mal binden wir dabei einen Dienst
an, der nicht auf Port 80 lauscht – ein wichtiges Detail für alle folgenden Apps.

Voraussetzungen

Ein laufender Traefik-Reverse-Proxy samt proxy-Netzwerk und funktionierendem Let's-Encrypt-Resolver le
Ein DNS-Record status.DEINE_DOMAIN, der auf den Server zeigt

Schritt für Schritt

Schritt 1: Die compose.yaml

Eigener Ordner, eigene Datei:

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

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

volumes:
  kuma-data:

networks:
  proxy:
    external: true

Das kennst du aus dem Traefik-Tutorial – bis auf eine neue, entscheidende Zeile:

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

Uptime Kuma lauscht intern auf Port 3001, nicht auf 80. Diese Zeile sagt Traefik,
an welchen Port es die Anfragen weiterreichen soll. Ohne sie rät Traefik falsch und
du bekommst einen Bad Gateway. Merke dir das Label – jede App, die nicht auf Port
80 läuft, braucht es.

Der Rest ist das bekannte Muster: kein ports: (nur über Traefik erreichbar),
proxy-Netzwerk, Named Volume für die Daten.

Schritt 2: Starten und ersten Login

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

Wenn Kuma bereit ist, endet das Log mit dieser Zeile – ab hier nimmt der Dienst
Anfragen an (Strg+C beendet nur das Mitlesen):

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

Beim ersten Start legt Kuma seine Datenbank im Volume an – das dauert einige
Sekunden. Ruf dann https://status.DEINE_DOMAIN im Browser auf. Uptime Kuma 2.x
fragt zuerst die Datenbank ab – für ein Setup wie unseres ist SQLite die
richtige, einfachste Wahl (auswählen, auf Weiter klicken). Direkt danach legst du
das Admin-Konto an (Benutzername + starkes Passwort).

⚠️ Sofort das Admin-Konto anlegen

Solange kein Admin-Konto existiert, kann jeder, der die Seite aufruft, eines
anlegen. Erledige das direkt nach dem ersten Start – nicht „später".

Schritt 3: Den ersten Monitor anlegen

Ein Monitor ist eine wiederkehrende Prüfung. Klicke auf Neuen Monitor
hinzufügen und lege einen für Traefik selbst an:

Monitortyp: HTTP(s)
Freundlicher Name: Traefik Dashboard
URL: https://traefik.DEINE_DOMAIN
Prüfintervall: 60 Sekunden
Authentifizierung: Das Traefik-Dashboard ist per Basic-Auth geschützt (Schritt 7 des Traefik-Tutorials) – wähle deshalb unten HTTP Basic Auth als Authentifizierungsmethode und trage Benutzer und Passwort ein. Ohne Zugangsdaten bekommt Kuma nur 401 und meldet den Monitor als Down.

Speichern – nach wenigen Sekunden steht der Monitor auf Online (grün) und zeigt
die Antwortzeit.

Neben dem einfachen HTTP(s)-Check lohnt es sich, den passenden Monitortyp zu
wählen:

HTTP(s) – Keyword: prüft zusätzlich, ob ein bestimmtes Wort im Antworttext steht. So erkennst du „Server antwortet zwar, zeigt aber eine Fehlerseite".
TCP-Port: für Dienste ohne Web-Oberfläche (z. B. eine Datenbank, ein SSH-Port). Prüft nur, ob der Port offen ist.
Ping: einfachster Erreichbarkeitstest per ICMP.
Docker-Container: prüft direkt den Container-Status über den Docker-Socket – praktisch für interne Dienste ohne eigene Domain.
Push: hier ruft der überwachte Dienst Kuma regelmäßig an. Ideal für Cronjobs und Backups: meldet sich das Skript nicht rechtzeitig, schlägt Kuma Alarm („Dead man's switch").

Lege für jeden wichtigen Dienst den passenden Monitor an.

💡 Tipp

Prüfe öffentliche Dienste über ihre echte Domain (https://…), nicht über
localhost. So testest du zugleich, dass Traefik und das Zertifikat von außen
funktionieren – nicht nur, dass der Container läuft.

Beim HTTP(s)-Monitor lohnt sich zusätzlich die Option
„Zertifikatsablauf-Benachrichtigung": Kuma warnt dann rechtzeitig, bevor ein
TLS-Zertifikat ausläuft. Bei Diensten hinter Traefik erneuert Let's Encrypt zwar
automatisch – aber genau dieser Automatismus fällt gelegentlich leise aus (ein
DNS-Record wird geändert, Port 80 versehentlich zugemacht). Der Monitor ist dein
Sicherheitsnetz und meldet sich, solange noch Tage zum Reparieren bleiben, statt dass
Besucher plötzlich vor einer Zertifikatswarnung stehen.

Schritt 4: Benachrichtigungen einrichten (E-Mail und Telegram)

Ein Monitor ohne Alarm ist nur ein hübsches Diagramm. Unter Einstellungen →
Benachrichtigungen → Benachrichtigung einrichten legst du einen Kanal an. Uptime
Kuma unterstützt über 90 – wir richten die zwei häufigsten komplett ein: E-Mail
für die klassische Nachricht und Telegram für Push direkt aufs Handy.

E-Mail (SMTP)

Wähle als Benachrichtigungsdienst „E-Mail (SMTP)" und trage die Daten deines
Mailanbieters ein:

Hostname / Port: z. B. smtp.DEIN_ANBIETER.de und 587
Sicherheit: STARTTLS (Port 587) oder TLS/SSL (Port 465)
Benutzername / Passwort: deine SMTP-Zugangsdaten
Absender- / Empfänger-Adresse: von welcher Adresse die Warnung kommt und an welche sie geschickt wird

Klick auf Test – innerhalb weniger Sekunden landet eine Testnachricht im
Postfach. Erst wenn die wirklich ankommt, stimmen Zugangsdaten und Port. Speichern
nicht vergessen.

Telegram ist ideal für sofortige Push-Alarme aufs Handy – ohne eigenen Mailserver.
Du brauchst zwei Angaben:

Bot-Token: Schreib in Telegram @BotFather an, sende /newbot, vergib einen Namen – BotFather antwortet mit dem Token.
Chat-ID: Schreib deinem neuen Bot eine beliebige Nachricht, ruf dann https://api.telegram.org/bot<DEIN_TOKEN>/getUpdates im Browser auf und lies die chat.id aus der Antwort.

Trage Token und Chat-ID in die Telegram-Benachrichtigung ein (Uptime Kuma verlinkt
beide Hilfen direkt im Dialog) und klick Test – die Nachricht sollte sofort im
Chat erscheinen.

⚠️ Sonst bleibt der Alarm stumm

Eine eingerichtete Benachrichtigung greift nicht automatisch. Aktiviere sie in
jedem Monitor (Häkchen im Monitor-Formular) oder schalte im Benachrichtigungs-Dialog
„Standardmäßig aktiviert" ein und „Auf alle existierenden Monitore anwenden".

Willst du Push-Nachrichten komplett in Eigenregie (ohne Telegram-Server), kommt
später ntfy dazu – selbst gehostet, mit eigenem Rezept in der Serie.

Schritt 5: Eine öffentliche Status-Seite (optional)

Kuma kann eine Status-Seite veröffentlichen, auf der Besucher sehen, ob deine
Dienste laufen. So gehst du vor:

Statusseiten → Neue Status-Seite, dann Name (z. B. „Serverküche Status") und Slug (die URL, z. B. serverkueche) vergeben und auf Weiter klicken.
Im Editor Gruppe hinzufügen (z. B. „Dienste"), darunter über das Auswahlfeld die gewünschten Monitore hinzufügen.
Oben rechts Speichern – fertig. Öffentlich erreichbar ist die Seite dann unter https://status.DEINE_DOMAIN/status/serverkueche.

Nimm nur auf, was wirklich jeder sehen darf – interne Dienste besser weglassen.

Schritt 6: Fehlalarme vermeiden – das Alarm-Verhalten feinjustieren

Ein Monitor, der bei jedem kurzen Netzwerk-Schluckauf Alarm schlägt, wird schnell
ignoriert – und dann verpasst du den echten Ausfall. Im Monitor-Formular stellst du
das Verhalten passend ein:

Wiederholungen (Retries): Erst nach n fehlgeschlagenen Prüfungen gilt der Dienst als „Down". 2–3 filtert einzelne Aussetzer heraus, ohne echte Ausfälle lange zu verschleiern.
Heartbeat-Intervall bei Ausfall: Kuma darf im Fehlerfall häufiger prüfen (z. B. alle 20 Sekunden), um die Erholung schnell zu erkennen.
Erneut benachrichtigen: Kuma kann dich alle x Minuten erinnern, solange ein Dienst down ist – nützlich, damit ein Ausfall nachts nicht in einer einzigen Mail untergeht.

💡 Wartungsfenster einplanen

Planst du ein Update mit Downtime, lege unter Wartung ein Wartungsfenster an.
Kuma pausiert dann die Alarme für die betroffenen Monitore – so bekommst du (und die
Status-Seite) keine Fehlalarme, während du selbst am Werk bist.

Schritt 7: Cronjobs überwachen mit einem Push-Monitor

Klassische Monitore prüfen von außen, ob ein Dienst antwortet. Für Dinge, die
still im Hintergrund laufen – ein nächtliches Backup, ein Sync-Skript, ein
Cronjob – dreht der Push-Monitor das Prinzip um: Nicht Kuma fragt an, sondern
dein Skript meldet sich. Bleibt die Meldung aus, schlägt Kuma Alarm – der klassische
„Dead man's switch".

Lege einen Monitor vom Typ Push an. Kuma zeigt dir dann eine eindeutige
Push-URL:

https://status.DEINE_DOMAIN/api/push/DEIN_TOKEN?status=up&msg=OK&ping=

Diese URL rufst du am Ende deines Skripts auf – zum Beispiel nach einem erfolgreich
durchgelaufenen Backup:

# ... dein Backup-Befehl ...
curl -fsS "https://status.DEINE_DOMAIN/api/push/DEIN_TOKEN?status=up&msg=Backup+OK" > /dev/null

Stell das Prüfintervall in Kuma etwas großzügiger ein als deinen Cron-Takt (läuft
das Backup stündlich, gib Kuma z. B. 90 Minuten Toleranz). Kommt in dieser Zeit kein
curl, geht der Monitor auf Down und du wirst benachrichtigt – du erfährst also
von einem nicht gelaufenen Backup, nicht erst, wenn du es dringend brauchst.

Schritt 8: Den Admin-Login mit 2FA absichern

Dein Kuma-Login schützt den Zugang zu allen Monitoren, den hinterlegten
Benachrichtigungs-Zugangsdaten und der Status-Seiten-Konfiguration – und er hängt
öffentlich im Netz. Schalte deshalb Zwei-Faktor-Authentifizierung ein: unter
Einstellungen → Sicherheit → Zwei-Faktor-Authentifizierung. Kuma zeigt einen
QR-Code, den du mit einer Authenticator-App (z. B. Aegis oder 2FAS) scannst; zum
Aktivieren gibst du einmal den erzeugten Code ein.

💡 Wiederherstellung absichern

Bewahre das TOTP-Secret bzw. einen zweiten Authenticator an einem sicheren Ort auf
(Passwortmanager). Verlierst du dein Telefon und hast keine Kopie, kommst du sonst
nur noch über die Datenbank im kuma-data-Volume wieder hinein.

Wenn es nicht funktioniert

Symptom: Bad Gateway (502) beim Aufruf von status.DEINE_DOMAIN.

Ursache & Lösung: Fast immer fehlt das Port-Label
traefik.http.services.kuma.loadbalancer.server.port=3001 oder es steht ein
falscher Port drin. Traefik erreicht den Container dann zwar, klopft aber am
falschen Port an. Label prüfen und docker compose up -d erneut ausführen.

Symptom: 404 page not found statt Kuma.

Ursache & Lösung: Wie bei jeder App hinter Traefik: traefik.enable=true
gesetzt? Container im proxy-Netzwerk? Stimmt die Domain in der Host(...)-Regel
und zeigt der DNS-Record status.DEINE_DOMAIN auf den Server? Das Traefik-Dashboard
zeigt unter „HTTP Routers", ob kuma registriert ist.

Symptom: Die Oberfläche lädt, aber die Live-Aktualisierung ruckelt / bricht ab.

Ursache & Lösung: Kuma nutzt WebSockets. Traefik leitet die standardmäßig korrekt
weiter – tritt das Problem trotzdem auf, liegt es meist an einem davorgeschalteten
CDN/Proxy (z. B. Cloudflare im „Proxy"-Modus), der WebSockets blockt. Für den
Direktbetrieb hinter Traefik ist keine Zusatzkonfiguration nötig.

Symptom: Nach einem Neuaufsetzen sind alle Monitore weg.

Ursache & Lösung: Das kuma-data-Volume wurde gelöscht (z. B. durch
docker compose down -v). Alle Konfiguration und Historie liegt allein in diesem
Volume – deshalb steht es im nächsten Abschnitt ganz oben.

Wartung & Backups

Sichern: Das komplette Herz von Kuma ist das Volume kuma-data (eine SQLite-Datenbank). Sichere es regelmäßig – ist es weg, sind alle Monitore und die Historie weg. Das Off-Site-Backup dafür bauen wir im Restic-Tutorial.
Updates: Tag :2 bleibt bei der 2.x-Reihe und bringt Fehlerbehebungen mit docker compose pull && docker compose up -d. Vor einem Sprung auf eine neue Hauptversion (z. B. später :3) die Release-Notes lesen und vorher das Volume sichern.
Von 1.x kommend? Der Wechsel auf :2 migriert die SQLite-Datenbank beim ersten Start automatisch – das kann einen Moment dauern, und ein Zurück auf :1 ist danach nicht vorgesehen. Sichere deshalb vorher das kuma-data-Volume, dann bist du auf der sicheren Seite. Neu-Installationen (wie oben) betrifft das nicht.
Ehrliche Einschränkung: Ein Monitor, der auf demselben Server läuft wie die überwachten Dienste, kann dich nicht warnen, wenn der ganze Server ausfällt – dann ist auch Kuma offline. Ergänze für den Ernstfall einen externen Wächter. Zwei günstige Wege: ein zweites Uptime Kuma auf einem kleinen Server (oder zu Hause), das nur diese Instanz per HTTP überwacht – oder ein kostenloser externer Ping-Dienst, der deine öffentliche Status-Seite anpingt. So bekommst du auch dann eine Meldung, wenn der ganze Host weg ist – der einzige Fall, den ein lokaler Monitor prinzipbedingt nicht abdecken kann.

Damit hast du das App-Muster verinnerlicht und überwachst ab sofort alles, was du
hinter Traefik hängst. Was jede weitere App voraussetzt, sind
verschlüsselte Off-Site-Backups mit Restic –
damit deine Daten einen Servercrash überleben.

Dieser Beitrag erschien zuerst auf serverkueche.de.

netcup-Firewall im SCP einrichten (mit stateless-UDP-Kniff)

serverkueche.de — Sun, 19 Jul 2026 09:00:46 +0000

netcup bringt eine Firewall schon vor deinem Server mit – im Server Control Panel,
noch bevor ein Paket das Betriebssystem erreicht. Richtig gebaut ist sie ein starker
Schutzschild. Es gibt dabei aber einen Kniff, an dem viele scheitern: Die netcup-Firewall
ist bei UDP zustandslos. Dieses Tutorial zeigt dir eine saubere, wiederverwendbare
Firewall – und warum DNS und NTP sonst plötzlich klemmen.

Was bauen wir?

Wir bauen im netcup SCP eine Netzwerk-Firewall aus komponierbaren Policy-Templates:
ein Basis-Template (das jeder Server braucht), eins für SSH und eins für
Web (HTTP/HTTPS). Diese Bausteine weist du deinem Server nach Bedarf zu – ein
Webserver bekommt Basis + SSH + Web, ein Server ohne Website nur Basis + SSH. Am Ende ist
eingehend alles gesperrt außer dem, was du bewusst erlaubst.

Ein netcup-spezifisches Detail macht dabei den Unterschied: Bei UDP arbeitet die Firewall
zustandslos – weshalb Dienste wie DNS und NTP eine eigene Eingangs-Regel brauchen, sonst
klemmen sie plötzlich. Warum das so ist und wie das Basis-Template es löst, zeigt Schritt 2.

ℹ️ Netzwerk-Firewall ≠ Host-Firewall

Die netcup-Firewall arbeitet im Netzwerk vor dem Server und ersetzt nicht die
Firewall auf dem Server selbst (UFW). Beide
zusammen sind „Defense in Depth": Fällt eine Schicht aus oder ist falsch konfiguriert,
greift die andere. Richte ruhig beide ein.

Voraussetzungen

Ein netcup-Server, z. B. dein erster VPS.
Deine SCP-Zugangsdaten (Kundennummer + SCP-Passwort aus der netcup-Willkommensmail – andere als dein SSH-Login).
Klarheit über deinen SSH-Port: Standard ist 22, und beim SSH-Absichern bleibt er auch dabei. Hast du ihn anderweitig geändert, nimm deinen echten Port – sonst sperrst du dich beim Aktivieren aus.

Schritt für Schritt

Schritt 1: Firewall Policys im SCP öffnen

Melde dich im Server Control Panel an und öffne oben
den Menüpunkt Firewall Policys. Hier legst du wiederverwendbare Regelsätze („Policys")
an – unabhängig vom einzelnen Server. Erst später weist du sie zu.

Schritt 2: Das Basis-Template bauen

Klick auf Firewall Policy erstellen, vergib den Namen Serverküche Basis und lege über
Regel hinzufügen diese vier Regeln an – alle EINGEHEND und ACCEPT:

Beschreibung	Protokoll	Quell-Port (Src)	Ziel-Port (Dst)
DNS-Antworten (stateless)	UDP	53	beliebig
NTP-Antworten (stateless)	UDP	123	beliebig
ICMP (Ping/PMTU)	ICMP	–	–
ICMPv6 (Neighbor Discovery)	ICMPv6	–	–

Zwei Dinge, die hier den Unterschied machen:

DNS/NTP über den Src Port, nicht den Ziel-Port. Dein Server fragt DNS/NTP an (ausgehend); die Antwort kommt von Port 53 bzw. 123 zurück. Weil UDP zustandslos ist, brauchst du diese Eingangs-Regel – sonst gibt es keine Namensauflösung und keine Zeitsynchronisation, obwohl „alles andere" zu funktionieren scheint.
ICMPv6 nie vergessen. Ohne Neighbor Discovery bricht IPv6 komplett. ICMP (v4) dazu ist für Ping und die Pfad-MTU-Erkennung sinnvoll. netcups Default-Policy „Ping allow" deckt ICMP zwar schon ab – im Basis-Template steht es bewusst nochmal drin, damit dein Fundament auch dann vollständig bleibt, wenn du die netcup-Defaults einmal entfernst.

ℹ️ Sobald eine Regel da ist, sperrt netcup den Rest automatisch

Ein abschließendes „alles sperren" musst du nicht anlegen. Ohne zugewiesene Policy
ist eingehend alles erlaubt. Sobald du dem Server aber mindestens eine eigene Policy
zuweist, schaltet netcup den Default auf „block all" – ab dann ist eingehend alles
gesperrt, was keine deiner Regeln ausdrücklich erlaubt. Die Whitelist entsteht also von
selbst; ausgehend bleibt offen.

💡 Nutzt dein Server DHCP?

netcup-VPS sind in der Regel statisch konfiguriert (iface … inet static) – dann ist
hier nichts zu tun. netcups Netz betreibt zwar einen DHCP-Server, aber weil UDP zustandslos
ist, wird die DHCP-Antwort (Quell-Port 67) von der Whitelist verworfen. Ist dein
Server ausnahmsweise per DHCP konfiguriert, ergänze im Basis-Template
EINGEHEND · UDP · ACCEPT · Src 67 (für DHCPv6 zusätzlich Src 547) – sonst verliert er
bei der nächsten Lease-Erneuerung seine IP.

Schritt 3: Kleine Bausteine für SSH und Web

Statt eines großen Regel-Monolithen legst du atomare Templates an, die du frei
kombinierst. Erstelle nach demselben Muster zwei weitere Policys:

Serverküche SSH – eine Regel: EINGEHEND, TCP, ACCEPT, Ziel-Port 22.
Serverküche Web – zwei Regeln: EINGEHEND, TCP, ACCEPT, Ziel-Port 80 und 443.

Der Gewinn: Die Basis-Regeln stehen nur einmal da, nicht in jeder Policy dupliziert.
Kommt später ein Dienst dazu (z. B. ein Mailserver oder WireGuard), baust du dafür ein
weiteres kleines Template und steckst es dazu – ohne die bestehenden anzufassen.

Schritt 4: Templates dem Server zuweisen

Wechsle zu Server → deinen Server → Reiter „Firewall" und klick auf Firewall Policys
editieren. Schieb aus Verfügbare Firewall Policys die passenden nach Ausgewählte:
für einen Webserver Serverküche Basis + Serverküche SSH + Serverküche Web.

Bestätige mit Übernehmen und dann Speichern. Prüfe, dass der Schalter „Firewall
aktiv" eingeschaltet ist. Die zugewiesenen Regeln erscheinen jetzt in der Liste –
zusammen mit netcups Default-Policys (dazu unten mehr).

⚠️ Nicht aussperren

Aktiviere die Firewall nur, wenn die SSH-Regel (Port 22 bzw. dein echter Port) drin
ist. Lass während der Umstellung eine zweite SSH-Sitzung offen und öffne parallel eine
neue Verbindung, um den Zugang zu testen – erst wenn die klappt, die alte Sitzung
schließen. Kommst du gar nicht mehr rein, hilft die VNC-Konsole unter Bildschirm im SCP.

Schritt 5: Fertige Templates für gängige Dienste

Genau nach dem Muster aus Schritt 3 folgen hier fertige Vorlagen für die häufigsten
Selfhosting-Dienste. Jede ist ein eigenes kleines Template, alle Regeln sind
EINGEHEND und ACCEPT. Bau nur die, die du wirklich brauchst, und steck sie wie in
Schritt 4 zu Serverküche Basis + Serverküche SSH dazu.

ℹ️ Bei UDP-Diensten: Ziel-Port, nicht Quell-Port

Für UDP-Dienste, die du selbst anbietest (VPN, TURN, eigener DNS-Server), steht der
Port im Ziel-Port (Dst) – denn hier verbinden sich Clients zu deinem Server. Das ist
das Gegenteil der DNS/NTP-Regeln aus dem Basis-Template: Dort steht der Port im
Quell-Port (Src), weil dein Server dort der fragende Client ist, dessen Antwort
zurückkommt. TCP-Antworten sind davon nicht betroffen (der Firewall-Zustand spielt nur bei
UDP keine Rolle); ausgehend ist ohnehin alles erlaubt.

Mailserver (mailcow & Co.)

Beschreibung	Protokoll	Quell-Port (Src)	Ziel-Port (Dst)
SMTP (Mailannahme anderer Server)	TCP	–	25
Submission (STARTTLS)	TCP	–	587
Submission (implizites TLS)	TCP	–	465
IMAP (STARTTLS)	TCP	–	143
IMAPS	TCP	–	993
POP3 (STARTTLS)	TCP	–	110
POP3S	TCP	–	995
ManageSieve (Filterregeln)	TCP	–	4190

Zwei Dinge, die beim Mailserver zusätzlich dazugehören:

Web-UI und Zertifikate: mailcow braucht 80/443 für das Webinterface und den Let's-Encrypt-Abruf – dafür einfach das Serverküche Web-Template mit zuweisen.
Ausgehendes SMTP freischalten: Ein Mailserver muss auf Port 25 ausgehend zustellen können. netcup sperrt das per Default-Policy „netcup Mail block" – die musst du am Server entfernen (siehe „Wenn es nicht funktioniert"). Und ohne korrekten PTR-/Reverse-DNS-Eintrag landen deine Mails im Spam.

WireGuard-VPN

Beschreibung	Protokoll	Quell-Port (Src)	Ziel-Port (Dst)
WireGuard	UDP	–	51820

51820 ist der übliche Standard – nimm den Wert aus deinem ListenPort. Nur diese eine
eingehende Regel ist nötig; die Antworten an die Clients gehen ausgehend raus.

OpenVPN

Beschreibung	Protokoll	Quell-Port (Src)	Ziel-Port (Dst)
OpenVPN (UDP, Standard)	UDP	–	1194
OpenVPN (TCP-Fallback)	TCP	–	1194

Standard ist UDP 1194. Die TCP-Regel nur, wenn du OpenVPN bewusst über TCP betreibst
(manche legen es zusätzlich auf TCP 443, um durch restriktive fremde Netze zu kommen) –
sonst weglassen.

Zabbix-Monitoring

Hier kommt es auf die Rolle des Servers an:

Rolle	Beschreibung	Protokoll	Ziel-Port (Dst)
Überwachter Host (Zabbix-Agent)	passive Checks vom Server	TCP	10050
Zabbix-Server	Trapper (aktive Agenten/Proxies)	TCP	10051

Der Zabbix-Server braucht zusätzlich 80/443 fürs Web-Frontend (Serverküche Web).
Betreibst du aktive Checks, verbindet sich der Agent ausgehend zum Server auf 10051 –
dafür ist am Agenten-Host keine eingehende Regel nötig.

Checkmk

Rolle	Beschreibung	Protokoll	Ziel-Port (Dst)
Überwachter Host (Agent)	Agent-Controller, Pull-Modus	TCP	6556
Checkmk-Server (optional)	Agent-Receiver (Push/Registrierung)	TCP	8000
Checkmk-Server (optional)	Livestatus (verteiltes Monitoring)	TCP	6557

Im Standard-Pull-Modus holt der Checkmk-Server die Daten aktiv ab – er verbindet sich
also ausgehend zu 6556 der Agenten. Eingehend braucht deshalb nur der überwachte Host
den Port 6556. Der Checkmk-Server selbst kommt mit 80/443 (Serverküche Web) aus;
8000 und 6557 nur, wenn du Push-Modus bzw. verteiltes Monitoring nutzt.

Coturn / TURN-Server (Nextcloud Talk, Matrix)

Beschreibung	Protokoll	Quell-Port (Src)	Ziel-Port (Dst)
STUN/TURN	TCP	–	3478
STUN/TURN	UDP	–	3478
STUN/TURN über TLS	TCP	–	5349
STUN/TURN über TLS	UDP	–	5349
Medien-Relay (Audio/Video)	UDP	–	49152–65535

Die große UDP-Relay-Range ist der Standard – über sie laufen die eigentlichen
Audio-/Video-Streams. Du kannst sie in der coturn-Konfiguration (min-port/max-port)
enger fassen und die Firewall-Regel dann auf denselben, kleineren Bereich setzen.

Eigener DNS-Server (AdGuard Home, Pi-hole, Unbound)

Beschreibung	Protokoll	Quell-Port (Src)	Ziel-Port (Dst)
DNS-Anfragen	UDP	–	53
DNS-Anfragen (große Antworten/TCP)	TCP	–	53
DNS-over-TLS (DoT)	TCP	–	853

Achtung, das ist genau die Gegenrichtung zum Basis-Template: Dort erlaubt Src 53 die
Antworten auf deine eigenen DNS-Anfragen; hier erlaubt Dst 53 die Anfragen fremder
Clients an deinen DNS-Server. Beides existiert problemlos nebeneinander.

⚠️ Kein offener Resolver

Ein weltweit offener rekursiver DNS-Server wird für DNS-Amplification-Angriffe
missbraucht. Beschränke den Zugriff auf deine eigenen Netze (Quell-Adresse in der Regel
setzen) oder biete DNS ausschließlich verschlüsselt (DoT/DoH) für angemeldete Clients an –
öffne 53 nie „mal eben" für die ganze Welt.

Datenbank-Fernzugriff (nur im Notfall)

Beschreibung	Protokoll	Quell-Port (Src)	Ziel-Port (Dst)
PostgreSQL	TCP	–	5432
MySQL / MariaDB	TCP	–	3306

🛑 Datenbanken gehören nicht ins offene Internet

Eine direkt erreichbare Datenbank ist ein bevorzugtes Angriffsziel. Der richtige Weg
ist, den Port gar nicht zu öffnen und stattdessen über einen
WireGuard-Tunnel oder einen SSH-Tunnel
(ssh -L 5432:localhost:5432 …) zuzugreifen. Musst du den Port trotzdem freigeben, dann
nur mit einer auf deine feste Admin-IP eingeschränkten Quell-Adresse in der
netcup-Regel – niemals für alle.

Wenn es nicht funktioniert

Symptom: Nach dem Aktivieren geht keine Namensauflösung mehr (apt update hängt,
ping domain.de scheitert, aber ping 1.1.1.1 geht).

Ursache & Lösung: Die DNS-Antworten werden geblockt. Prüfe im Basis-Template die
Regel EINGEHEND UDP ACCEPT, Src-Port 53. Wichtig: Quell-Port, nicht Ziel-Port.

Symptom: Die Uhr driftet, oder TLS-Zertifikate werden wegen falscher Zeit abgelehnt.

Ursache & Lösung: Die NTP-Antworten fehlen. Ergänze EINGEHEND UDP ACCEPT, Src-Port 123.

Symptom: IPv6 funktioniert nicht mehr (v4 schon).

Ursache & Lösung: Es fehlt die ICMPv6-Regel. Ohne Neighbor Discovery kann der
Server über IPv6 nicht einmal seinen Nachbarn (Router) finden.

Symptom: Du kommst nach dem Aktivieren nicht mehr per SSH rein.

Ursache & Lösung: Die SSH-Regel fehlt oder nennt den falschen Port. Über die
VNC-Konsole (SCP → Bildschirm) kommst du trotzdem auf den Server; korrigiere die Policy
und speichere neu. Genau dagegen hilft die „zweite Sitzung offen lassen"-Regel oben.

Symptom: Der Server kann keine E-Mails versenden (Port 25 raus geht nicht).

Ursache & Lösung: Das ist kein Fehler deiner Policy, sondern netcups
Default-Policy „netcup Mail block" – sie sperrt ausgehendes SMTP (Port 25/465/587) als
Spam-Schutz. Für einen echten Mailversand musst du dieses netcup-Template am Server deaktivieren.

Symptom: Der Server läuft zunächst normal und ist nach ein bis zwei Wochen plötzlich
offline.

Ursache & Lösung: Nutzt der Server DHCP, wird die Lease-Erneuerung von der Whitelist
geblockt – die DHCP-Antwort kommt von UDP-Quell-Port 67, den keine Regel erlaubt, und
UDP ist zustandslos. Ergänze EINGEHEND · UDP · ACCEPT · Src 67 im Basis-Template.
Statisch konfigurierte netcup-VPS (der Standard) sind davon nicht betroffen.

Wartung & Backups

Nach jeder Änderung den Zugang testen. Firewall-Regeln sind der klassische Weg, sich selbst auszusperren. Zweite Sitzung offen halten, neue Verbindung prüfen, erst dann fertig.
Neue Dienste = neues Template. Brauchst du später einen weiteren Port (Game-Server, WireGuard-VPN über UDP, Datenbank), leg ein kleines eigenes Template an und weise es zusätzlich zu. Die bestehenden Bausteine bleiben unberührt.
Reihenfolge beachten. netcup wertet die Regeln von oben nach unten aus; die erste zutreffende Regel greift. Bei reinen ACCEPT-Regeln ist das egal – sobald du aber eigene DROP-Regeln einsetzt, achte auf die Reihenfolge relativ zu den ACCEPTs.
netcups Default-Policys kennen. „netcup Mail block" (ausgehendes SMTP auf Port 25/465/587 gesperrt) und „netcup Ping allow" sind vorgegeben. Über Default Policys wiederherstellen kommst du im Notfall auf einen bekannten, funktionierenden Grundzustand zurück, falls du dich mit eigenen Regeln ausgesperrt hast – zusammen mit der VNC-Konsole dein zweites Sicherheitsnetz.

Dieser Beitrag erschien zuerst auf serverkueche.de.

Docker Compose verstehen: Services, Volumes, Netzwerke

serverkueche.de — Fri, 17 Jul 2026 22:10:57 +0000

Im Docker-Tutorial hast du das Compose-Plugin
installiert – erklärt haben wir es noch nicht. Das holen wir jetzt nach, denn fast
jedes App-Rezept hier beschreibt eine Anwendung als compose.yaml. Wer diese
Datei liest wie einen Einkaufszettel, kann jedes folgende Tutorial anpassen, statt
nur zu kopieren.

Was bauen wir?

Wir bauen Schritt für Schritt einen kleinen Stack auf und lernen dabei die fünf
Bausteine kennen, aus denen praktisch jede compose.yaml besteht: Services
(die Container), Ports (Erreichbarkeit von außen), Volumes (persistente
Daten), Netzwerke (Container reden miteinander) und Umgebungsvariablen
(Konfiguration). Am Ende verstehst du, warum deine Daten einen down-Befehl
überleben – und wann nicht.

Getestet mit Docker Compose v5.3 (das docker compose-Plugin ohne Bindestrich –
nicht das alte docker-compose v1 mit Bindestrich).

Voraussetzungen

Ein abgesicherter Server mit installiertem Docker und Compose-Plugin
Der Benutzer ist in der docker-Gruppe (dann brauchst du kein sudo vor docker)

Schritt für Schritt

Schritt 1: Die erste compose.yaml

Eine compose.yaml beschreibt deklarativ, welche Container laufen sollen – du
sagst was du willst, nicht wie. Lege einen Projektordner an; der Ordnername
wird später zum Präfix aller Container:

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

Lege eine kleine HTML-Seite an, die wir gleich ausliefern:

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

Und jetzt die zentrale Datei compose.yaml:

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

Zeile für Zeile:

services: – die oberste Ebene. Jeder Eintrag darunter ist ein Container.
web: – ein frei wählbarer Service-Name. Merke ihn dir, er wird später auch zum Hostnamen im internen Netzwerk (Schritt 3).
image: nginx:1.31 – das Container-Image mit festem Tag. Nie latest verwenden: latest ändert sich unter dir und macht Fehler unreproduzierbar.
ports: - "8080:80" – Format HOST:CONTAINER. Port 80 im Container wird auf 8080 des Servers gelegt. Links steht immer der Server.
volumes: - ./site:...:ro – der lokale Ordner site wird ins Web-Root gehängt, :ro = read-only. Mehr dazu in Schritt 2.
restart: unless-stopped – der Container startet nach einem Reboot oder Absturz automatisch neu, außer du hast ihn selbst gestoppt. Für Server-Dienste der sinnvolle Standard. Die Alternativen: no (nie automatisch – der Default), always (startet selbst nach einem manuellen Stopp wieder, selten gewollt) und on-failure (nur nach einem Absturz mit Fehlercode). Für die allermeisten Dienste ist unless-stopped genau richtig.

Starte den Stack:

docker compose up -d

-d bedeutet detached (im Hintergrund). Beim ersten Mal lädt Docker das Image;
danach siehst du am Ende:

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

Prüfe den 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

Der Container heißt compose-demo-web-1 – Projektordner + Service + Nummer. Test:

curl localhost:8080

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

Läuft. Logs eines Dienstes siehst du mit docker compose logs web (oder -f zum
Mitlaufen).

Schritt 2: Volumes – wo deine Daten wirklich liegen

Container sind vergänglich: Löschst du einen Container, ist alles weg, was
im Container geschrieben wurde. Damit Daten das überleben, gibt es zwei Arten von
Volumes:

Bind-Mount (./site:/usr/share/nginx/html): ein Ordner von deinem Server wird in den Container gehängt. Ideal für Config-Dateien, die du selbst bearbeitest.
Named Volume (webdata:/var/lib/...): ein von Docker verwalteter Speicher. Ideal für Datenbank-Daten – performant und sauber getrennt vom Host.

In Schritt 1 haben wir ein Bind-Mount genutzt. Für datenbankartige Dienste sieht
es so aus – ändere compose.yaml testweise:

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

volumes:
  webdata:

Named Volumes müssen zusätzlich auf oberster Ebene unter volumes: deklariert
werden. Nach docker compose up -d taucht das Volume auf:

docker volume ls

DRIVER    VOLUME NAME
local     compose-demo_webdata

Der entscheidende Punkt kommt jetzt:

docker compose down
docker volume ls

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

docker compose down entfernt Container und Netzwerk – das Volume bleibt. Genau
deshalb überleben deine Datenbank-Inhalte ein Update. Merke dir das Gegenstück:

🛑 down -v löscht Daten

docker compose down -v löscht auch die Named Volumes – also alle persistenten
Daten des Stacks. Tippe das -v nie aus Reflex mit. Für ein reines Neustarten
reicht docker compose down (ohne -v).

Schritt 3: Netzwerke – Container reden miteinander

Compose legt automatisch ein Netzwerk pro Projekt an (oben gesehen:
compose-demo_default). Alle Services darin erreichen sich über ihren
Service-Namen als Hostname – kein IP-Gefummel nötig. Das ist der Grund, warum in
App-Tutorials die Anwendung ihre Datenbank einfach unter db erreicht.

Zum Beweis ein zweiter Service, der den ersten anspricht:

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

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

depends_on: - web – Compose startet web vor ping. (Achtung: das wartet nur auf den Start, nicht auf „fertig hochgefahren" – dafür gibt es Healthchecks, Schritt 4.)
command: – überschreibt den Standardbefehl des Images. ping ruft http://web auf – web ist der Service-Name aus derselben Datei.

Führe nur den ping-Service einmalig aus:

docker compose run --rm ping

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

ping hat web allein über den Namen erreicht – ganz ohne Port-Mapping. Merke:
ports: brauchst du nur, um einen Dienst von außen (dem Internet) erreichbar zu
machen. Container untereinander reden über das interne Netzwerk – später lassen
wir deshalb Datenbanken bewusst ohne ports: laufen.

Bisher lebt jedes Netzwerk innerhalb eines Compose-Projekts. Manchmal sollen aber
Container aus verschiedenen Projekten miteinander reden – das klassische Beispiel ist
ein Reverse Proxy, der vor vielen unabhängigen App-Stacks sitzt. Dafür gibt es das
externe Netzwerk: eines, das du einmalig von Hand anlegst und das danach mehrere
Compose-Projekte gemeinsam nutzen:

docker network create proxy

In der compose.yaml legst du es dann nicht neu an, sondern verweist mit external: true
auf das bereits bestehende Netzwerk:

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

networks:
  proxy:
    external: true

external: true sagt Compose: „Dieses Netzwerk existiert schon – leg es nicht an und
lösch es beim down nicht." Fehlt das Netzwerk, bricht up mit network proxy declared as external, but could not be found ab – dann hast du das docker network create
vergessen. Genau dieses Muster – ein gemeinsames proxy-Netz plus external: true – ist
die Grundlage des Traefik-Tutorials, mit dem jede App
später ihre Domain und ihr HTTPS bekommt.

Schritt 4: Konfiguration – Umgebungsvariablen, .env und Healthchecks

Fast jede Anwendung wird über Umgebungsvariablen konfiguriert. Zwei Wege:

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

Geheimnisse (Passwörter, Tokens) gehören nicht in die compose.yaml, sondern in
eine .env-Datei im selben Ordner. Compose liest sie automatisch:

echo "DB_PASSWORD=EIN_LANGES_ZUFALLSPASSWORT" > .env

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

⚠️ .env nie ins Backup-Repo pushen

Die .env enthält Klartext-Geheimnisse. Nimm sie in eine .gitignore auf, falls du
deine Compose-Dateien versionierst, und sichere sie getrennt (verschlüsselt).

So prüfst du, ob Compose deine Datei versteht und die .env-Werte richtig
einsetzt – ohne etwas zu starten:

docker compose config

config löst alle Variablen auf und gibt die fertige, normalisierte Konfiguration
aus:

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

Steht dort dein echter Wert statt ${DB_PASSWORD}, greift die .env. Brauchst
du nur einen schnellen Syntax-Check ohne die ganze Ausgabe, nimm
docker compose config --quiet – kommt nichts zurück (Exit-Code 0), ist die Datei
gültig. Genau das ist auch dein erster Griff bei YAML-Fehlern (siehe unten).

Ein Healthcheck sagt Docker, wann ein Dienst wirklich bereit ist – die Basis
dafür, dass abhängige Dienste erst dann starten:

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

Mit condition: service_healthy startet app erst, wenn der Healthcheck von db
grün ist – das häufigste „warum verbindet sich meine App nicht zur Datenbank?"
verschwindet damit. Die vier Healthcheck-Felder bedeuten: test ist der Befehl,
der im Container läuft (Exit-Code 0 = gesund), interval der Abstand zwischen
den Prüfungen, timeout wie lange eine Prüfung dauern darf, und retries
wie viele Fehlversuche in Folge nötig sind, bevor der Container als unhealthy gilt.
Den aktuellen Zustand zeigt die STATUS-Spalte von docker compose ps als
(healthy) bzw. (unhealthy).

Schritt 5: Der Betriebs-Werkzeugkasten

Diese Befehle brauchst du täglich – immer im Projektordner ausführen:

docker compose up -d        # starten / Änderungen anwenden
docker compose ps           # Status der Services
docker compose logs -f web  # Logs live mitlesen (Strg+C beendet nur das Ansehen)
docker compose exec web sh  # Shell im laufenden Container
docker compose restart web  # einen einzelnen Dienst neu starten
docker compose stop         # anhalten, ohne Container/Netzwerk zu entfernen
docker compose pull         # neue Image-Versionen holen
docker compose down         # Stack stoppen und entfernen (Volumes bleiben)

Fast alle Befehle lassen sich auf einen Service einschränken, indem du seinen
Namen anhängst (docker compose logs -f web, docker compose restart web) – ohne
Namen gelten sie für den ganzen Stack. Der Unterschied zwischen stop und down:
stop hält die Container nur an (mit start geht's weiter), down entfernt sie
samt Netzwerk (die Named Volumes bleiben in beiden Fällen).

Ein Update läuft fast immer nach demselben Muster: Tag in der compose.yaml
hochsetzen → docker compose pull → docker compose up -d. Compose ersetzt nur die
Container, deren Image sich geändert hat.

Schritt 6: Alles zusammen – ein realistischer App-Stack

So sieht das Muster aus, das dir in den App-Tutorials immer wieder begegnet: eine
Anwendung plus ihre Datenbank. Diese Datei bündelt alles aus den Schritten 1–4 –
lies sie einmal komplett, dann hast du 90 % jeder späteren compose.yaml
verstanden:

services:
  app:
    image: beispiel/app:1.4          # feste Version, kein latest
    ports:
      - "8080:3000"                  # nur die App ist von außen erreichbar
    environment:
      - TZ=Europe/Berlin
      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/app
    volumes:
      - appdata:/data                # persistente App-Daten (Named Volume)
    depends_on:
      db:
        condition: service_healthy   # startet erst, wenn db bereit ist
    restart: unless-stopped

  db:
    image: postgres:18
    environment:
      - POSTGRES_USER=app
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=app
    volumes:
      - dbdata:/var/lib/postgresql/data   # die eigentlichen Datenbank-Dateien
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    # kein ports: – die Datenbank ist NUR intern über den Namen "db" erreichbar

volumes:
  appdata:
  dbdata:

Drei Design-Entscheidungen, die du dir merken solltest:

Nur app hat ports:. Die Datenbank braucht keinen offenen Host-Port – die App erreicht sie intern über den Hostnamen db (die DATABASE_URL zeigt genau dorthin). Ein nicht veröffentlichter Port ist ein Port, den niemand aus dem Internet angreifen kann.
Zwei getrennte Named Volumes. App-Daten und Datenbank-Dateien liegen sauber getrennt – das macht spätere Backups und Restores nachvollziehbar.
Passwort nur als ${DB_PASSWORD}. Der echte Wert steht in der .env, nicht in dieser Datei. Dieselbe compose.yaml kann so gefahrlos geteilt werden.

Genau dieses Grundgerüst – App nach außen, Datenbank nur intern, Daten in Named
Volumes, Secrets in der .env – wiederholt sich in Nextcloud, Vaultwarden,
Paperless und den meisten anderen Rezepten.

Wenn es nicht funktioniert

Symptom: yaml: line 7: did not find expected key (oder ähnliche YAML-Fehler)

Ursache & Lösung: YAML ist einrückungssensibel – ausschließlich Leerzeichen,
niemals Tabs, und pro Ebene konsistent (üblich: 2 Leerzeichen). Prüfe die Datei
ohne sie zu starten: docker compose config löst alles auf und meckert genau die
falsche Zeile an.

Symptom: Error ... address already in use beim up

Ursache & Lösung: Der Host-Port (links in 8080:80) ist schon belegt. Finde den
Beleger mit sudo ss -tlnp | grep 8080 oder wähle einen anderen Host-Port. Zwei
Container dürfen sich denselben Host-Port nicht teilen.

Symptom: Eine App findet ihre Datenbank nicht (could not translate host name).

Ursache & Lösung: Als Hostname muss der Service-Name stehen (z. B. db),
nicht localhost. Innerhalb eines Containers ist localhost der Container selbst,
nicht der Nachbar-Service. Und: Beide Services müssen im selben Compose-Projekt
(derselben Datei) liegen.

Symptom: Nach docker compose down sind alle Daten weg.

Ursache & Lösung: Entweder lag das Volume nicht als Named Volume unter
volumes: vor (dann war es nur der vergängliche Container-Speicher), oder es wurde
down -v verwendet. Persistente Dienste immer mit deklariertem Named Volume fahren.

Symptom: docker-compose: command not found

Ursache & Lösung: Das ist das alte Compose v1 (mit Bindestrich). Aktuell ist
docker compose (mit Leerzeichen, Plugin). Falls es fehlt:
sudo apt install docker-compose-plugin (siehe Docker-Tutorial).

Wartung & Backups

Image-Tags pflegen: Feste Tags (nginx:1.31) bedeuten, dass du Updates bewusst durch Hochsetzen des Tags einspielst. Das ist gewollt – so entscheidest du, wann ein Update kommt, statt überrascht zu werden. Rechne mit monatlichem Draufschauen auf die Release-Notes deiner Dienste.
Was gehört ins Backup? Nicht die Container – die sind aus der compose.yaml jederzeit neu baubar. Sichern musst du die Named Volumes (bzw. Bind-Mount- Ordner), die compose.yaml und die .env. Ein durchdachtes Off-Site-Backup dieser Daten bauen wir mit verschlüsselten Restic-Backups.
Aufräumen: docker compose down beim Abbau eines Stacks; ungenutzte Images räumst du mit docker image prune weg. Named Volumes werden nie automatisch gelöscht – das ist Absicht.

Dieser Beitrag erschien zuerst auf serverkueche.de.

DEV Community: serverkueche.de

netcup VPS 1000 G12 benchmarked: how fast is it really?

What are we building?

Prerequisites

Step by step

Step 1: Size up the server

Step 2: CPU

Step 3: Memory

Step 4: NVMe disk

Step 5: Network

When things go wrong

Maintenance & backups

HitKeep: self-host privacy-friendly web analytics

What are we building?

Prerequisites

Step by step

Step 1: Generate a JWT secret

Step 2: Create the Compose file

Step 3: Start the stack and wait for TLS

Step 4: Create the admin account

Step 5: Create a website and get the tracking code

Step 6: Embed the tracking code in the website

Step 7: Check the dashboard

Step 8: More than just page views

When things go wrong

Maintenance & backups

Keeping your whole Docker stack safely up to date

What are we building?

Prerequisites

Step by step

Step 1: Never latest again – pin versions deliberately

Step 2: See what's outdated – the update notifier Diun

Step 3: Apply an update safely (the routine)

Step 4: Don't forget the base – host, engine, hidden images

Step 5: Clean up – reclaim storage

Step 6: Auto-update – when it's okay (and when not)

When things go wrong

Maintenance & backups

Docker volumes vs. bind mounts: where your data really lives

What are we building?

Prerequisites

Step by step

Step 1: Why container data disappears

Step 2: Named volumes – managed by Docker

Step 3: Bind mounts – a folder from the host

Step 4: Both in the compose.yaml

Step 5: The trap – anonymous volumes

Step 6: Managing volumes

When things go wrong

Maintenance & backups

Self-hosting Nextcloud: your own cloud behind Traefik

What are we building?

Prerequisites

Step by step

Step 1: Create the DNS record

Step 2: Determine the proxy subnet

Step 3: Create the compose.yaml

Step 4: Start and run through the initial setup

Step 5: Set up background jobs (cron)

Step 6: Connect the clients

When things go wrong

Maintenance & backups

Self-hosting Immich: your private photo backup behind Traefik

What are we building?

Prerequisites

Step by step

Step 1: Create the DNS record

Step 2: Prepare the folder and .env

Step 3: Create the compose.yaml

Step 4: Allow large uploads (Traefik timeout)

Step 5: Start and run through the initial setup

Step 6: Connect the phone app

When things go wrong

Maintenance & backups

Installing Uptime Kuma: server monitoring behind Traefik

What are we building?

Prerequisites

Step by step

Step 1: The compose.yaml

Step 2: Start and first login

Step 1: Never `latest` again – pin versions deliberately

Step 4: Both in the `compose.yaml`