DEV Community: 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 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.1.2 ... and finally Initializing finished, followed by the Apache start. If restarting appears repeatedly instead, take a look at the "When things go wrong" section. With Ctrl+C you leave the log view again (the container keeps running).

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

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

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

Step 5: Set up background jobs (cron)

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

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

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

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

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

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

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

Step 3: Create the compose.yaml

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

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

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

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

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

volumes:
  model-cache:

networks:
  default:
  proxy:
    external: true

Important to understand:

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

💡 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

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

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

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

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

Step 6: Connect the phone app

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

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

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

ℹ️ 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 and enable two-factor authentication in the account settings. Whoever wants to be extra safe makes Immich reachable only via a 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. Alternatively, Immich can generate automatic DB dumps under Administration → Job queues – you still have to back up the photos separately.

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

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

Prerequisites

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

Step by step

Step 1: The compose.yaml

Own folder, own file:

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

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

volumes:
  kuma-data:

networks:
  proxy:
    external: true

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

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

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

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

Step 2: Start and first login

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

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

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

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

⚠️ 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 choose HTTP Basic Auth as the authentication method below and enter the user and password. Without credentials, Kuma only gets 401 and reports the monitor as Down.

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

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

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

Create the matching monitor for every important service.

💡 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" is also worth it: Kuma then warns in good time before a TLS certificate expires. For services behind Traefik, Let's Encrypt renews automatically – but this very automation occasionally fails silently (a DNS record is changed, port 80 accidentally closed). The monitor is your safety net and reports in while there are still days to fix it, instead of visitors suddenly facing a certificate warning.

Step 4: Set up notifications (email and Telegram)

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

Email (SMTP)

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

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

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

Telegram 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 "Enabled by default" and "Apply on all existing monitors".

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

Step 5: A public status page (optional)

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

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 interval on failure: Kuma may check more often in the error case (e.g. every 20 seconds) to detect recovery quickly.
Resend notification: Kuma can remind you every x minutes as long as a service is down – useful so an outage at night doesn't get lost in a single mail.

💡 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. Kuma shows a QR code you scan with an authenticator app (e.g. Aegis or 2FAS); to activate, you enter the generated code once.

💡 Secure the recovery

Keep the TOTP secret or a second authenticator in a safe place (password manager). 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.

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

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

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

ℹ️ 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.36.0 /vaultwarden hash --preset owasp

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

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

Password:
Confirm Password:

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

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

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

networks:
  proxy:
    external: true

The most important lines in detail:

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

Step 3: Start it and the first call

Start the container:

docker compose up -d

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

docker compose logs -f vaultwarden

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

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

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

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

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

🛑 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 restarts the container. From now on the login page rejects new registrations. Further users (e.g. for the family) you invite specifically via the admin panel when needed – more on that shortly.

⚠️ 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 data. 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 won't start, the log says something like Running without a persistent volume is not recommended. The volumes: mapping is missing. Vaultwarden deliberately refuses to start without a data directory 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 config how the token actually arrives (Compose shows the resolved value there). 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.