In short

Problem: After I switched on Traefik GeoBlock, Claude’s connector to Home Assistant stopped working, while Home Assistant itself was fine for everyone at home.

Solution: The connector calls from Anthropic’s servers in the US, and GeoBlock only allowed my own countries. One allowedIPAddresses entry with the provider’s published IP range fixed it.

Tested with: Traefik 3, GeoBlock plugin (PascalMinder) 0.3.8, Home Assistant with an MCP server for Claude

In Hardening Traefik I put GeoBlock in front of every service: only visitors from the countries my family lives in get through, everyone else gets a 403. It worked exactly as planned. A bit too well, as it turned out: it also locked out a visitor I wanted, my own AI assistant.

This is a short story about a security measure that does its job, breaks something you need, and how to find out which one it was.

1. The symptom

I use Claude with a connector to Home Assistant, so I can ask about sensors, automations and logs in plain language. Shortly after the hardening, the connector couldn’t reach Home Assistant anymore. Every attempt failed.

At the same time, Home Assistant was perfectly fine: the dashboard loaded at home, the app on my phone worked, automations ran. Only this one client was affected.

2. What I checked first (and why it misled me)

A connector that signs in with OAuth has plenty of parts that can break, so that’s where you look first:

• Sign-in and tokens: an expired token or a broken OAuth setup would explain a failing client. But reconnecting doesn’t help when the requests are blocked before they arrive.
• Home Assistant logs: nothing. No failed login, no error from the MCP integration, not even a request.
• The URL: it opens fine in the browser.

The empty Home Assistant log was the real clue, and it’s easy to read it the wrong way. “No errors” sounded like “nothing wrong in Home Assistant”. It actually meant: the requests never arrived. Something in front of Home Assistant was answering them. And “it works in my browser” proved nothing, because my browser comes from an allowed country.

3. The real cause: Traefik GeoBlock did its job

Claude’s connectors don’t run in my browser or on my phone. They call my server from Anthropic’s infrastructure, which sits in the US. For GeoBlock that’s just another request from a country that isn’t on the list.

Two logs show it. GeoBlock writes every denied request to its own file. A line looks like this (example address):

INFO: GeoBlock: 2026/10/16 09:14:52 geoblock@docker: request denied [203.0.113.17] for country [US] due to: country is not allowed

And the Traefik access log shows the 403 with an empty backend ("-" after the router name). That dash means the request never reached the service (again an example line):

203.0.113.17 - - [16/Oct/2026:09:14:52 +0000] "POST /api/webhook/… HTTP/1.1" 403 0 "-" "-" 4711 "homeassistant@docker" "-" 1ms

The log is full of scanners from all over the world, so the connector’s requests don’t stand out by themselves. Compare the denied addresses with the range Anthropic publishes for its outgoing traffic, and they do.

4. The fix: allow the published IP range

GeoBlock has an option for exactly this: allowedIPAddresses. Addresses in this list are let through no matter which country they come from. One more label on the Traefik container:

      # Claude connectors call from Anthropic's published outbound range
      # source: https://platform.claude.com/docs/en/api/ip-addresses
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowedIPAddresses[0]=160.79.104.0/21"

Then recreate the container so Traefik reads the new labels:

docker compose up -d traefik

The range above is the one Anthropic lists at the time of writing. Check Anthropic’s IP address page for the current one before you copy it. The same approach works for any other service that has to reach you from abroad, as long as its provider publishes its IP ranges.

5. How to verify

1. Check that Traefik picked up the label:
   docker inspect traefik --format '{{ index .Config.Labels "traefik.http.middlewares.geoblock.plugin.geoblock.allowedIPAddresses[0]" }}'
2. Use the connector once (in my case: ask Claude for a sensor value).
3. Make sure the range no longer shows up as denied:
   grep -E '\[160\.79\.1(0[4-9]|1[01])\.' traefik-logs/geoblock.log | tail
   No new lines after the restart means GeoBlock lets the connector through.

What I learned

• “Works in my browser” is no test for a geo-block. Ask where the failing client really calls from.
• An empty application log is a finding, not a dead end: the request was stopped earlier.
• Before switching on an allow list, write down every service that calls in from outside: AI connectors, webhooks, monitoring, push services. Each one needs a deliberate exception or a different path.

The full GeoBlock and CrowdSec setup is in Hardening Traefik: geo-blocking, CrowdSec and single sign-on.

In short

Problem: Every login through a new Authentik OAuth2/OpenID provider fails with invalid_request: “The request is otherwise malformed”.

Solution: The provider was created through the API, and its grant_types list was empty. Set it to authorization_code and refresh_token, then test the authorize URL with curl.

Tested with: Authentik 2026.8, WordPress with the OpenID Connect Generic plugin 3.11

I add most apps to Authentik through the admin interface. For this blog I wanted to script it, so I created the OAuth2 provider with a single API call. The call succeeded, the application showed up, the WordPress plugin was configured with the right client ID, secret and endpoints. And then not a single login worked.

The fix turned out to be one field. Finding it took longer than it should have, because the error message points in the wrong direction.

1. The symptom: “request is otherwise malformed”

Clicking “Login with OpenID Connect” in WordPress sent me to Authentik, and Authentik sent me straight back with an error page instead of a login form:

invalid_request
The request is otherwise malformed

No username prompt, no password prompt. Authentik refused the request before the login flow even started.

2. What I checked first (and why it misled me)

“Malformed request” sounds like the client sent something wrong. So I went through the usual suspects on the WordPress side:

• Redirect URI: character by character against the provider. Authentik uses strict matching, so a missing slash or a different query string is enough to break it. It matched.
• Client ID: copied again, no stray spaces.
• Scopes: openid email profile, all three available in the provider.
• Endpoints: taken from the provider’s .well-known/openid-configuration.

Everything was correct. The request from WordPress was fine. The problem was on the Authentik side, and the browser error doesn’t tell you that.

3. The real cause: an empty grant_types list

The Authentik server log had the more useful message. With Docker Compose:

docker compose logs server --since 10m | grep -i grant

It said “Invalid grant_type for provider”. Every OAuth2 provider in Authentik has a list of allowed grant types. When you create a provider in the admin interface, the form fills in sensible defaults. The API doesn’t: grant_types is an optional field, and if you leave it out, the provider is saved with an empty list. An empty list means no grant type is allowed, so not even the normal authorization code flow works.

My API call looked roughly like this (shortened):

curl -X POST https://id.example.com/api/v3/providers/oauth2/ \
  -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provider for My Blog",
    "client_type": "confidential",
    "authorization_flow": "<flow uuid>",
    "invalidation_flow": "<flow uuid>",
    "redirect_uris": [
      {"matching_mode": "strict",
       "url": "https://blog.example.com/wp-admin/admin-ajax.php?action=openid-connect-authorize"}
    ],
    "signing_key": "<certificate uuid>",
    "property_mappings": ["<openid>", "<email>", "<profile>"]
  }'

Every required field is there, so the API accepts it without a warning. The one field that decides whether anyone can log in is the one that’s missing.

4. The fix

Set the grant types on the existing provider. A login flow for a website needs authorization_code, and refresh_token if the app renews its tokens:

curl -X PATCH https://id.example.com/api/v3/providers/oauth2/<provider id>/ \
  -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grant_types": ["authorization_code", "refresh_token"]}'

You can also open the provider in the admin interface and save it there with both grant types ticked. For new providers, add the line straight to the create call:

    "grant_types": ["authorization_code", "refresh_token"],

While you’re at it, compare the token lifetimes too (access_token_validity, refresh_token_threshold) with a provider you created in the interface. API-created providers don’t always get the same values, and it’s easier to keep all providers alike.

5. How to verify (without a browser)

You don’t need to click through the login to test a provider. Call the authorize endpoint with curl and look at where Authentik sends you:

curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' \
  "https://id.example.com/application/o/authorize/?client_id=<client id>&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fblog.example.com%2Fwp-admin%2Fadmin-ajax.php%3Faction%3Dopenid-connect-authorize"

• Working: a 302 to Authentik’s own login flow, for example /if/flow/default-authentication-flow/….
• Broken: a 302 back to your app’s redirect URI with error=… in the URL. The error name tells you what Authentik didn’t like.

What I learned

• “Malformed request” in the browser doesn’t mean the client is wrong. Read the identity provider’s server log before you change anything in the app.
• The admin interface and the API don’t create the same object. The interface fills in defaults, the API stores exactly what you send.
• A curl test of the authorize URL checks a provider in seconds, without logging in.

How the blog login is set up end to end is in Single sign-on for WordPress with Authentik. All provider fields are described in the official Authentik documentation.

In short

Problem: A Nextcloud container starts in a minute. Making it fast, reachable over HTTPS, free of admin warnings and safe to back up takes a lot more than docker run nextcloud.

Solution: One compose project with Nextcloud, PostgreSQL, Redis and a cron container, published through Traefik, logins through Authentik, documents in the browser with the built-in Collabora server, and a nightly backup in maintenance mode.

Tested with: Nextcloud 35 (official nextcloud:35 image, PHP 8.5), PostgreSQL 16, Redis, Traefik 3.7, Authentik, Docker Compose on a small home server

Nextcloud is the service in my homelab that the whole family actually uses: files, calendars, contacts, notes and, since recently, Office documents. That makes it the one I least want to break. This article walks through my configuration: the containers, the settings that matter behind a reverse proxy, single sign-on, Nextcloud Office, the maintenance after updates, and how I back it up. It builds on my Traefik article; if you don’t have a reverse proxy yet, start there.

1. The stack at a glance

The tag nextcloud:35 is a deliberate choice. It follows minor and patch releases of version 35, so my update script (it runs docker compose pull && docker compose up -d three times a week) picks up security fixes on its own. A new major version never arrives by surprise. Nextcloud can only upgrade one major version at a time, and I want to read the release notes and have a fresh backup before that step.

2. The .env file

Everything that differs between installations, and every password, lives in a .env file next to the compose file. Make it readable only for its owner: chmod 600 .env.

NEXTCLOUD_IMAGE_TAG=nextcloud:35
NEXTCLOUD_HOSTNAME=cloud.example.com
NEXTCLOUD_URL=https://cloud.example.com
NEXTCLOUD_TIMEZONE=Europe/Berlin

NEXTCLOUD_DB_NAME=nextcloud
NEXTCLOUD_DB_USER=nextcloud
NEXTCLOUD_DB_PASSWORD=change-me-long-random

NEXTCLOUD_REDIS_PASSWORD=change-me-too

# only used on the very first start
NEXTCLOUD_ADMIN_USERNAME=admin
NEXTCLOUD_ADMIN_PASSWORD=change-me-as-well

A good way to create the passwords: openssl rand -base64 32. The admin user and password are only read when Nextcloud installs itself on the first start. Changing them later in .env does nothing.

3. Database, Redis and cron

networks:
  nextcloud-network:
  proxy:
    external: true

volumes:
  nextcloud-app:
  nextcloud-postgres:
  redis-data:

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - nextcloud-postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${NEXTCLOUD_DB_NAME}
      POSTGRES_USER: ${NEXTCLOUD_DB_USER}
      POSTGRES_PASSWORD: ${NEXTCLOUD_DB_PASSWORD}
    networks:
      - nextcloud-network
    healthcheck:
      test: ["CMD", "pg_isready", "-q", "-d", "${NEXTCLOUD_DB_NAME}", "-U", "${NEXTCLOUD_DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 60s

  redis:
    image: redis
    restart: unless-stopped
    command: ["redis-server", "--requirepass", "${NEXTCLOUD_REDIS_PASSWORD}"]
    volumes:
      - redis-data:/data
    networks:
      - nextcloud-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  nextcloud-cron:
    image: ${NEXTCLOUD_IMAGE_TAG}
    restart: unless-stopped
    entrypoint: /cron.sh
    volumes:
      - nextcloud-app:/var/www/html
      - /srv/nextcloud/data:/var/www/html/data
    networks:
      - nextcloud-network

A few details that are easy to miss:

• The database and Redis are only in nextcloud-network. They have no published ports and Traefik can’t see them. Only Nextcloud talks to them.
• Health checks matter here. Nextcloud waits for service_healthy (see below), so it never starts its install or upgrade step against a database that is still booting.
• The cron container uses the same image and the same volumes as Nextcloud, but runs /cron.sh, which calls cron.php every 5 minutes. After the first start, switch Nextcloud from AJAX to cron: occ background:cron (or Administration settings → Basic settings).

4. The Nextcloud container

  nextcloud:
    image: ${NEXTCLOUD_IMAGE_TAG}
    restart: unless-stopped
    volumes:
      - nextcloud-app:/var/www/html
      - /srv/nextcloud/data:/var/www/html/data
    environment:
      TZ: ${NEXTCLOUD_TIMEZONE}
      POSTGRES_HOST: postgres
      POSTGRES_DB: ${NEXTCLOUD_DB_NAME}
      POSTGRES_USER: ${NEXTCLOUD_DB_USER}
      POSTGRES_PASSWORD: ${NEXTCLOUD_DB_PASSWORD}
      REDIS_HOST: redis
      REDIS_HOST_PORT: 6379
      REDIS_HOST_PASSWORD: ${NEXTCLOUD_REDIS_PASSWORD}
      NEXTCLOUD_ADMIN_USER: ${NEXTCLOUD_ADMIN_USERNAME}
      NEXTCLOUD_ADMIN_PASSWORD: ${NEXTCLOUD_ADMIN_PASSWORD}
      NEXTCLOUD_TRUSTED_DOMAINS: ${NEXTCLOUD_HOSTNAME}
      # behind the reverse proxy
      OVERWRITEHOST: ${NEXTCLOUD_HOSTNAME}
      OVERWRITEPROTOCOL: https
      OVERWRITECLIURL: ${NEXTCLOUD_URL}
      TRUSTED_PROXIES: 172.16.0.0/12
      # big uploads and Office
      PHP_MEMORY_LIMIT: 8G
      PHP_UPLOAD_LIMIT: 8G
    networks:
      - nextcloud-network
      - proxy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 90s
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

Two storage locations. The named volume nextcloud-app holds the application itself, including config/config.php and the apps you install from the app store (custom_apps). The user files go to a bind mount on a big disk (/srv/nextcloud/data here). Keeping them apart lets me put the data on a separate SSD and back the two up differently. Just don’t forget the volume: config.php contains the instance’s secret and password salt, and without it a restore of the data alone is much harder.

The reverse proxy settings. Nextcloud only sees plain HTTP from Traefik on port 80. Without these four variables it builds wrong links, refuses logins from the “untrusted” host name or shows every visitor with Traefik’s IP address:

172.16.0.0/12 covers Docker’s default network ranges, where Traefik lives. Put in what docker network inspect proxy shows on your host, and don’t add more than that: every range you trust can fake client IPs.

5. Publishing it through Traefik

    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.nextcloud.rule=Host(`cloud.example.com`)"
      - "traefik.http.routers.nextcloud.entrypoints=websecure"
      - "traefik.http.routers.nextcloud.tls.certresolver=letsencrypt"
      - "traefik.http.routers.nextcloud.middlewares=nextcloud-dav,nextcloud-wellknown,nextcloud-compress,nextcloud-hsts"
      - "traefik.http.services.nextcloud.loadbalancer.server.port=80"

      # CalDAV/CardDAV discovery for phones and calendar apps
      - "traefik.http.middlewares.nextcloud-dav.redirectregex.permanent=true"
      - "traefik.http.middlewares.nextcloud-dav.redirectregex.regex=https?://([^/]*)/.well-known/(card|cal)dav"
      - "traefik.http.middlewares.nextcloud-dav.redirectregex.replacement=https://$${1}/remote.php/dav/"

      # all other .well-known URLs (webfinger, nodeinfo, ...)
      - "traefik.http.middlewares.nextcloud-wellknown.redirectregex.permanent=true"
      - "traefik.http.middlewares.nextcloud-wellknown.redirectregex.regex=https?://([^/]*)(/.well-known[^#]*)"
      - "traefik.http.middlewares.nextcloud-wellknown.redirectregex.replacement=https://$${1}/index.php$${2}"

      - "traefik.http.middlewares.nextcloud-compress.compress=true"
      - "traefik.http.middlewares.nextcloud-hsts.headers.stsSeconds=15552000"

The two redirects fix the most common warning in the admin overview (“Your web server is not properly set up to resolve /.well-known/caldav”). They also let phones find calendars and contacts when you only type the host name. The $$ is needed because Compose would otherwise read ${1} as a variable.

HSTS (the stsSeconds line) tells browsers to use only HTTPS for this host for the next 180 days, which removes another admin warning. In my setup, a general security header middleware on the websecure entrypoint sets HSTS for every service anyway (see the hardening article). I keep the line here so the Nextcloud stack still gets it if I ever change that.

You don’t need a buffering middleware for big uploads, by the way. Traefik has no request size limit by default, and the Nextcloud clients upload large files in chunks anyway.

6. Logging in with Authentik

Like most of my services, Nextcloud uses single sign-on with Authentik. I use the official app OpenID Connect user backend (user_oidc). The setup on the Authentik side (an OAuth2/OpenID provider plus an application) is the same as in my WordPress SSO article. The redirect URI for Nextcloud is https://cloud.example.com/apps/user_oidc/code.

Then, in the Nextcloud container:

alias occ='docker compose exec -u www-data nextcloud php occ'

occ app:install user_oidc

occ user_oidc:provider Authentik \
  --clientid="<client id from Authentik>" \
  --clientsecret="<client secret from Authentik>" \
  --discoveryuri="https://id.example.com/application/o/nextcloud/.well-known/openid-configuration" \
  --scope="openid email profile" \
  --mapping-uid=preferred_username \
  --mapping-display-name=name \
  --mapping-email=email \
  --unique-uid=0

The last two options are the important ones. --mapping-uid=preferred_username with --unique-uid=0 makes the Nextcloud user name equal to the Authentik user name, instead of a long hash. So an Authentik user anna lands in the existing Nextcloud account anna with all her files, and the paths stay readable.

The login page now shows a “Log in with Authentik” button. The normal Nextcloud login stays available below it. I keep it on purpose: if Authentik is down, the local admin account still works. Desktop and mobile clients log in through the browser, so they use SSO too.

7. Nextcloud Office without an extra container

For opening .docx, .xlsx and .odt files in the browser I use Nextcloud Office with the built-in CODE server (Collabora Online Development Edition). It runs inside the Nextcloud container: no extra container, no extra host name, no extra certificate. For a household with a handful of users that’s plenty.

occ app:install richdocumentscode   # the built-in Collabora server (on ARM: richdocumentscode_arm64)
occ app:install richdocuments       # the Nextcloud Office app
occ richdocuments:activate-config

After that, Administration settings → Office should say that the built-in server is used. The WOPI URL points to https://cloud.example.com/custom_apps/richdocumentscode/proxy.php?req=.

Also check that the Office app version fits your Nextcloud major version. The app store sometimes keeps an older, incompatible version installed after an upgrade; occ app:update --all fixes that.

8. Clean admin overview after an update

After a major upgrade, Administration settings → Overview usually shows a few new warnings. These are the commands I needed, roughly in this order (with a fresh backup):

# new database indices that came with the upgrade (takes seconds to minutes)
occ db:add-missing-indices

# only if the overview suggests it; can take a while on big instances
occ maintenance:repair --include-expensive

# phone numbers in profiles without a country code
occ config:system:set default_phone_region --value="DE"

# run heavy background jobs at night (hour in UTC, 1 = 01:00-05:00)
occ config:system:set maintenance_window_start --type=integer --value=1

# the same checks as the admin overview, on the command line
occ setupchecks

Memory caching is configured automatically by the official image: APCu for the local cache and Redis for file locking, as soon as REDIS_HOST is set. You can check it with occ config:system:get memcache.locking.

9. Backups

Nextcloud is backed up every night by a script on the host, not inside the stack. The order matters:

1. occ maintenance:mode --on, so no file or database row changes during the copy
2. pg_dump of the database into a plain SQL file (never copy the live database files)
3. rsync of the data folder into a dated snapshot, with a bandwidth limit so the disks stay usable
4. a copy of config/, custom_apps/ and themes/ from the app volume, plus the compose file and .env
5. occ maintenance:mode --off, in a trap, so it also happens when one step fails

On a normal night, maintenance mode lasts a few minutes. Unchanged files are hard-linked between snapshots, so 14 days of history cost little more than one copy. How the snapshots, the database dumps and the offline copy work together is in my backup article.

10. When something doesn’t work

The most useful commands for the rest:

# the newest errors from Nextcloud's own log
occ log:tail 20

# what the admin overview would complain about
occ setupchecks

# which labels (and so which Traefik middlewares) the container really has
docker inspect nextcloud-nextcloud-1 --format '{{json .Config.Labels}}'

What I learned

• Pin the major version. nextcloud:35 gives me automatic security fixes, and the big upgrade happens when I decide, with a backup.
• The reverse proxy settings are not optional. Most strange Nextcloud problems behind Traefik came down to OVERWRITEPROTOCOL or TRUSTED_PROXIES.
• Check what is really running. A label that is overwritten by a later one raises no error. docker inspect shows the truth, the compose file only shows the intention.
• The app volume belongs in the backup. For a long time I only backed up the data folder and the database. Without config.php, that’s a much harder restore.
• SSO via OIDC, not forward-auth. The sync clients keep working, and the local login is my emergency exit.

In short

Problem: A container that quietly stops, a disk that fills up, a service that answers with the wrong page: on a home server you usually find out when someone in the family says “it doesn’t work”.

Solution: Home Assistant watches the Docker host the same way it watches the rest of the house: one entity per container, host metrics, HTTP checks from the outside, backup status, and a handful of automations that send a Telegram message when something is wrong.

Tested with: Home Assistant 2026.10, the Portainer integration, my own SSH Linux Management add-on (MQTT), about 25 containers on one Docker host, Telegram and the Companion app for notifications

Home Assistant already knows how to tell me when a window is open or a battery is low. So instead of running a separate monitoring stack for my server, I let Home Assistant watch that too. Everything ends up in the same place: one dashboard, one notification channel, and automations I already know how to write. This article shows the two integrations I use to get the Docker host into Home Assistant, the alerts built on top of them, and what I learned along the way.

1. Two integrations, two jobs

Home Assistant runs in a VM, the containers on the host next to it. To see inside the host, I use two integrations, because each one is good at something different:

For the alerts below I use the Portainer status sensors for containers and the SSH add-on for everything about the host. If you only want one, start with Portainer: it’s a built-in integration and gives you the most per container.

2. The Portainer integration

If Portainer already runs on your Docker host, this is the quickest start:

1. In Portainer, open your user profile → Access tokens → Add access token, and copy the token.
2. In Home Assistant: Settings → Devices & services → Add integration → Portainer, enter Portainer’s URL and the token.
3. Home Assistant creates one device per container, with entities like binary_sensor.<container>_status, sensor.<container>_memory_usage, sensor.<container>_restart_count and update.<container>_image_update_available.

One thing Portainer doesn’t do: when you delete a container, its device stays in Home Assistant as “unavailable”. Remove it by hand (Settings → Devices, the device, Delete), or your dashboards and automations slowly fill with dead entities.

3. The SSH add-on: host metrics without root

For the host itself (disk, CPU, RAM, VMs) I wrote a small Home Assistant add-on, SSH Linux Management. It opens one outbound SSH connection to the host and publishes what it finds through MQTT discovery, so the entities appear in Home Assistant without any YAML:

• Docker: the remote Docker socket is forwarded through the SSH connection. No Docker TCP port is opened, and container changes arrive instantly through Docker’s event stream.
• Host metrics: CPU, memory and disk use per mount point (I watch / and the Nextcloud data disk).
• VMs: libvirt VMs as switches with a reboot button, through virsh over the same connection.
• The SSH account is not root: it’s a normal user in the docker (and libvirt) group, and the host key is pinned on the first connection.

A lesson from running it: the first versions named each Docker entity after the container’s ID. Every docker compose up after an update creates a new container with a new ID, so Home Assistant got a new entity each time, and after a few weeks I had switch.…_traefik, …_traefik_2 up to …_traefik_5. Version 0.11.0 keys the entities on the container name and removes discovery entries for containers that are gone. If you write your own MQTT discovery: choose the unique_id from something that survives a recreate.

4. Alert: a container stopped

The most important automation is also the simplest: if any container’s status sensor is off for two minutes, send a message that names it. The two minutes keep normal restarts (updates, a recreate) from sending false alarms:

alias: System - Docker - Container Down Alert
description: A watched container is not running for 2 minutes → Telegram + push.
mode: parallel
max: 10
triggers:
  - trigger: state
    entity_id:
      - binary_sensor.traefik_status
      - binary_sensor.crowdsec_status
      - binary_sensor.authentik_server_status
      - binary_sensor.nextcloud_nextcloud_1_status
      - binary_sensor.vaultwarden_status
      - binary_sensor.zigbee2mqtt_status
      # … one line per container you care about
    to: "off"
    for:
      minutes: 2
actions:
  - action: telegram_bot.send_message
    data:
      title: "🔴 Docker container down"
      message: "{{ trigger.to_state.attributes.friendly_name }} has not been running for 2 minutes."
  - action: notify.mobile_app_your_phone
    data:
      title: "🔴 Docker container down"
      message: "{{ trigger.to_state.attributes.friendly_name }} has not been running for 2 minutes."

• mode: parallel: if Docker itself restarts, several containers stop at once. Each one should get its own message, not just the first.
• to: "off", not “not on”: a sensor that turns unavailable (Portainer unreachable, container deleted) doesn’t fire. That’s on purpose: it prevents a flood of alerts when Portainer restarts, but it also means a deleted container is silently dropped from monitoring.

5. Running isn’t the same as working: HTTP checks

A container can be “running” while the service inside answers with an error page, or while the reverse proxy in front of it sends traffic nowhere. So every ten minutes Home Assistant also calls the public addresses, the way a visitor would, and checks the HTTP status code. The calls are shell_command entries in configuration.yaml:

shell_command:
  curl_check_nextcloud: "curl -s -o /dev/null -w '%{http_code}' --max-time 10 https://cloud.example.com/status.php"
  curl_check_traefik: "curl -s -o /dev/null -w '%{http_code}' --max-time 10 https://traefik.example.com/dashboard/"

The automation runs each command, reads the status code from the response, and compares it with what that service should answer:

triggers:
  - trigger: time_pattern
    minutes: "/10"
actions:
  - action: shell_command.curl_check_traefik
    response_variable: traefik
  - if:
      - condition: template
        value_template: "{{ traefik.stdout not in ['302', '401'] }}"
    then:
      - action: telegram_bot.send_message
        data:
          title: "🔴 Traefik dashboard check failed"
          message: "Expected a login (302/401), got {{ traefik.stdout }}."

• Check for the right answer, not just any answer. My Traefik dashboard and wiki sit behind single sign-on, so they must answer with a redirect to the login (302) or 401. A 200 would mean they’re suddenly open to everyone. The check catches a broken login, not just a broken service.
• Plan for maintenance. My nightly Nextcloud backup puts it into maintenance mode, which answers with 503. Between 02:55 and 04:30 the automation ignores exactly that code for Nextcloud, and only that one.

6. Disk space and the host

A full disk is the classic reason for a whole server to fail at once: databases stop writing, containers crash, logs can’t be written to explain why. The SSH add-on’s disk sensors make this a two-line trigger:

triggers:
  - trigger: numeric_state
    entity_id:
      - sensor.ssh_host_myserver_host_disk_use
      - sensor.ssh_host_myserver_host_disk_use_data
    above: 85
actions:
  - action: telegram_bot.send_message
    data:
      message: "⚠️ {{ trigger.to_state.attributes.friendly_name }} is at {{ trigger.to_state.state }} % used."

85 % gives me days, not minutes, to react. The same sensors go on the dashboard as gauges, next to CPU and memory.

7. Backups and updates

• Backups: a script on the host writes the state of every backup job into a JSON file every five minutes. The SSH add-on reads that file and creates a sensor per job plus one “backup problem” binary sensor. If that is on for ten minutes (a job failed, a snapshot is older than 26 hours, the backup disk isn’t mounted), I get a message with the reason. The details are in my backup article.
• Updates: an automation runs my Docker update script over SSH three times a week at 04:00 (docker compose pull and up -d per stack). The container alert above is the safety net: if an update breaks a container, I know before breakfast. For the reverse proxy, a pinned major version keeps that risk small (see my Traefik article).
• Version changes: for Zigbee2MQTT I also store the last known version in an input_text helper and send a message when it changes, with a reminder to read the release notes. I added it after an update changed how some devices behaved and I only noticed days later.

8. The dashboard

A “Server” view on my main dashboard shows the host gauges (CPU, RAM, both disks), the backup status, and one tile per container. Each tile shows whether the container runs, and tapping its icon restarts it:

type: tile
entity: switch.ssh_host_myserver_docker_vaultwarden
name: Vaultwarden
icon: mdi:restart
icon_tap_action:
  action: perform-action
  perform_action: button.press
  target:
    entity_id: button.ssh_host_myserver_docker_vaultwarden_restart

It’s not meant for daily use. It’s the page I open when a message arrives, to see at a glance whether one container is down or the whole host has a problem, and to restart the obvious candidate from my phone.

What I learned

• One place for alerts. I read Telegram anyway. A separate monitoring system with its own app would be one more thing I ignore.
• Check from the outside, too. “Container running” and “service works for a visitor” are two different questions. A container can run perfectly while its login is broken or the proxy points elsewhere.
• Check the expected answer. A login page that suddenly answers 200 is a security problem, not a success.
• Give every alert a short delay. Two minutes for containers, ten for backups: real problems stay, restarts don’t wake you up.
• Clean up after removing a container. Delete its device, take it out of the alert list and the dashboard. Dead entities make a dashboard you stop trusting.

In short

Problem: A homelab collects things you can’t download again: documents, passwords, photos, years of sensor history, the pairing of every Zigbee device. One dead disk, one bad update or one ransomware hit, and it’s gone.

Solution: Nightly snapshots of every service onto a separate disk (databases as dumps, files with rsync hardlinks), a third copy that a laptop pulls onto an encrypted SSD, monitoring that shouts when something is missing, and a restore script that is tested.

Tested with: about ten services in Docker (Nextcloud, Vaultwarden, Paperless-ngx, Authentik, BookStack, Zigbee2MQTT, Traefik, PostgreSQL for Home Assistant), two WordPress sites on a web host, bash + rsync + systemd timers, Home Assistant for alerts

Backups are the least exciting part of a homelab, until the day you need one. I built mine in steps, mostly after “what if…” moments, and it ended up as plain bash scripts, rsync and systemd timers: no backup software with its own database that I’d have to restore first. This article walks through the whole setup: what I back up, how the snapshots work, why databases are dumped instead of copied, how the third copy is protected against a hacked server, how I know every night that it worked, and how a restore looks.

1. Three copies, two disks, one of them out of reach

The classic rule is 3-2-1: three copies of your data, on two different media, one of them offsite. Here is my version of it, and where it falls short:

Honestly, the third copy is in the same house. Against fire or burglary it doesn’t help; for that, the SSD would have to live somewhere else, or an encrypted cloud copy would be the next step. For everything else, these three layers have covered every real problem I’ve had so far.

2. What gets backed up

Every service has its own small script and its own time slot, so a failing job never blocks the others, and the heavy Nextcloud job runs last:

Not backed up on purpose: logs, caches, message queues, CrowdSec’s ban list (it rebuilds itself), and the live database folders. Those are useless while the database runs; the dumps are the backup.

3. Snapshots with rsync hardlinks

Every run creates a folder named after the date, like 2026-10-20_0030. Each of these folders looks like a complete copy: you can browse it, copy single files out of it, or restore all of it. But files that didn’t change since the previous night aren’t copied again. They are hardlinks to the same file in the previous snapshot, so they take no extra disk space. That’s what rsync’s --link-dest option does:

/backup/paperless_backup/
├── 2026-10-19_0030/
│   ├── paperless-db.dump   database dump
│   ├── media/              all documents (mostly hardlinks)
│   ├── data/               search index, classifier
│   ├── compose/            docker-compose.yml, .env
│   └── rsync.log
├── 2026-10-20_0030/
├── latest -> 2026-10-20_0030
└── backup-paperless.sh    the script copies itself here

• Deleting an old snapshot is safe. A file only disappears from the disk when the last snapshot pointing to it is deleted.
• The filesystem must support hardlinks: ext4, XFS or btrfs. Not exFAT or NTFS – the typical format of a new USB disk.
• Hardlinks are not extra copies. Thirty snapshots of an unchanged document are still one file on the disk. If that disk sector dies, all thirty are affected. That’s why the third copy exists.
• The script copies itself next to the snapshots, so the instructions are on the backup disk even when the server is gone.

4. Databases are dumped, never copied

Copying the files of a running database gives you a snapshot of a moving target: half-written pages, a write-ahead log that doesn’t match. It may restore, or it may not. A dump asks the database itself for a consistent export, while it keeps running. And every dump is checked right after it is written:

A dump that fails its check stops the whole job, and the night’s snapshot never becomes latest (next section). A corrupt backup is worse than none, because you only find out when you need it.

5. One backup script, explained

All my scripts follow the same pattern. Here is the Paperless one, slightly shortened:

#!/usr/bin/env bash
set -Eeuo pipefail

PROJECT=/srv/docker/paperless          # compose folder
DEST=/backup/paperless_backup
KEEP_DAYS=30
STAMP=$(date +%F_%H%M)
SNAP=$DEST/$STAMP
WORK=$SNAP.partial

fail() { echo "ERROR: $*"; exit 1; }

# 1. never fill the system disk if the backup disk is missing
mountpoint -q /backup || fail "/backup is not mounted"

mkdir -p "$DEST" && chmod 700 "$DEST"
rm -rf "$DEST"/*.partial               # leftovers of a failed run
mkdir -p "$WORK"

LINK=()
[ -d "$DEST/latest" ] && LINK=(--link-dest="$DEST/latest/media")

# 2. database dump + check
cd "$PROJECT"
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' > "$WORK/paperless-db.dump"
docker compose exec -T db pg_restore --list < "$WORK/paperless-db.dump" > /dev/null 
  || fail "dump check failed"

# 3. files, unchanged ones as hardlinks to the last snapshot
rsync -aHAX --numeric-ids "${LINK[@]}" "$PROJECT/data/media/" "$WORK/media/"

# 4. only now does the snapshot become real
mv "$WORK" "$SNAP"
ln -sfn "$STAMP" "$DEST/latest"
cp -f "$0" "$DEST/"

# 5. retention
find "$DEST" -mindepth 1 -maxdepth 1 -type d -name '20??-??-??_????' 
  -mtime +"$KEEP_DAYS" -exec rm -rf {} +

• set -Eeuo pipefail: any failing command stops the script. A backup script that carries on after an error produces backups that look fine and aren’t.
• mountpoint -q: if the USB disk isn’t mounted, /backup is just an empty folder on the system disk. Without this check, the first night after a disk failure fills your system SSD.
• The .partial folder: the snapshot is built under a temporary name and only renamed when everything succeeded. A failed run never becomes latest, so the next run still links against the last good one.
• rsync -aHAX --numeric-ids: keeps permissions, hardlinks, ACLs, extended attributes and the numeric owner IDs. Containers often run as user IDs that don’t exist on the host; with names instead of numbers, a restore would get the owners wrong.
• Retention by folder age: find -mtime +30 removes snapshots older than 30 days. Thanks to hardlinks, that’s always safe.

6. Scheduling with systemd timers

I use systemd timers instead of cron. They log every run in the journal, they catch up on runs that were missed while the server was off (Persistent=true), and a service can wait until the backup disk is mounted:

# /etc/systemd/system/backup-paperless.service
[Unit]
Description=Paperless backup
RequiresMountsFor=/backup
After=docker.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup-paperless.sh

# /etc/systemd/system/backup-paperless.timer
[Unit]
Description=Nightly Paperless backup

[Timer]
OnCalendar=*-*-* 00:30
Persistent=true

[Install]
WantedBy=timers.target

Enable it with systemctl enable --now backup-paperless.timer. systemctl list-timers shows when each job ran last and runs next, and journalctl -u backup-paperless shows its output. My jobs start between 23:30 and 03:00, at least 15 minutes apart, so they never compete for the disk.

7. Services that need special care

• Nextcloud: the job switches on maintenance mode, dumps the database, copies the files and switches it off again. Otherwise someone could upload a file between the dump and the file copy, and the two wouldn’t match. The copy runs with an rsync bandwidth limit (--bwlimit) so the disks aren’t saturated, and at 03:00, when nobody uploads anything. On a normal night that’s a few minutes of maintenance mode.
• Zigbee2MQTT: its folder holds the network key and the database of all paired devices. Without it, every device has to be paired again. The container is paused (docker pause, not stopped) for the few seconds of the copy, so the database file is consistent.
• Authentik and BookStack: the database alone is not enough. Both keep a secret key in their .env that signs sessions or encrypts data. Restore the dump together with the .env from the same night, or logins and encrypted fields stop working.
• The reverse proxy: Traefik’s acme.json holds all certificates and the Let’s Encrypt account key (see my Traefik article). Without it, Traefik requests every certificate again and can run into rate limits.
• Sites on a web host: the server logs in with an SSH key, streams the WordPress folder as a tar archive and dumps the database on the host. The host’s own backups are a bonus, not a plan.

8. The third copy: pulled, read-only, encrypted

The obvious way to make a second copy is to let the server push it somewhere. The problem: if the server is hacked or hit by ransomware, the attacker has the same access and can delete or encrypt that copy too. So my third copy works the other way round. A laptop pulls the newest snapshot of every job onto an encrypted USB SSD, and the server has no way to reach it:

The rrsync restriction is one line in the server’s authorized_keys:

command="sudo rrsync -ro /backup",restrict ssh-ed25519 AAAA… offsite-pull

The pull job on the laptop runs every hour but only does something when it makes sense: at most once a day, only on mains power, never while the server’s own backups run (23:15–04:30), and only when the SSD is plugged in and the server answers. It also checks what it copies:

• Spot checks: dumps not empty, gzip archives readable, the Vaultwarden database passes its integrity check, the certificate file isn’t empty.
• Ransomware alarm: before copying Nextcloud, a dry run counts how many files changed. If it’s more than 20 %, something is very wrong (that’s what mass encryption looks like). The copy is kept, but old generations are no longer deleted until I look at it.
• Longer history than on the server: the newest 7 copies, then one per week for 8 weeks and one per month for 12 months. Nextcloud, at about 800 GB, keeps 10 generations.

9. Knowing it worked

A backup that silently stopped three weeks ago is the most common way to lose data. So a small Python script on the server collects the state of every job every five minutes and writes it to a JSON file: last run, result, age of the newest snapshot, whether the timer is enabled, whether the backup disk is mounted.

• A small status page on the server shows it as a table.
• Home Assistant reads the same file and creates a sensor per job (ok, failed, stale, …). If any job has a problem for ten minutes, I get a push notification and a Telegram message. “Stale” means the newest snapshot is older than 26 hours, which also catches a timer that simply never ran.
• Coverage check: the script also lists every running container and compares it with a list of covered services. A new container without a backup job shows up as a warning. That closed the gap I worried about most: adding a service on a Sunday afternoon and forgetting its backup.

The coverage list comes with a house rule: every new container gets its backup job, its restore step and its coverage entry in the same change. “Later” is how backups get forgotten.

10. Restoring

First, the cheap way: most “I deleted something” moments are solved in the app itself. Nextcloud has deleted files and versions, Paperless a trash for 30 days. Only when that doesn’t help do I go to the snapshots, and a single file is just a copy out of the right date folder.

For the bad day, when the server is gone or several services are broken, there is an interactive restore script on the backup disk itself:

1. Choose jobs: one, several or all, in a fixed order: infrastructure first (reverse proxy, certificates), then single sign-on, then the databases and apps.
2. Choose the snapshot: the newest, one date for all, or per job.
3. Choose steps per job: files, database, containers.
4. Dry run: the script prints every command it would run, and only continues when I type RESTORE.

It never deletes anything: files it overwrites are moved into a .pre-restore-<time> folder, and every database is dumped before it is replaced. The backup timers are paused during the restore, so no backup job runs against a half-restored system.

A restore script you never ran is a hope, not a plan. Mine has a test bench: fake docker, systemctl and sshd commands and fake snapshots, so it can run every scenario without touching real data. It’s 211 checks, and it has to pass after every change to the restore script. It still doesn’t replace a real restore on a spare machine once in a while: that’s the only proof that counts.

What I learned

• Boring tools win. rsync, bash and systemd will still be there in ten years, and I can restore with nothing but a shell.
• Dump databases and check the dump. A copied database folder is a gamble; an unchecked dump is a surprise waiting to happen.
• Snapshots aren’t copies. Hardlinks give you history, not redundancy. You still need a second disk.
• Pull, don’t push, the copy that has to survive an attack. Whatever the server can reach, an attacker on the server can reach too.
• Monitor the backups, not just the services. The alert for “no new snapshot in 26 hours” is worth more than any feature of the backup itself.
• Secrets belong to the data. Keys and .env files from the same night as the database, or the restore looks fine and nothing works.

In short

Problem: As soon as ports 80 and 443 are open, bots from all over the world scan your services, try passwords and probe for known vulnerabilities. Traefik alone forwards all of it.

Solution: Several layers in front of every service: geo-blocking for countries you never visit from, CrowdSec for known attackers and attack patterns, single sign-on in front of apps without their own good login, plus a few container basics.

Tested with: Traefik 3.7, GeoBlock plugin 0.3.8, CrowdSec 1.8 with the Traefik bouncer plugin 1.7 and AppSec, Authentik 2026.8, Docker Compose on a small home server

This is the second part of my Traefik setup. The first part explains the basics: entrypoints, routers, labels and certificates. Here it’s about the question Traefik itself doesn’t answer: should this request get in at all? A reverse proxy decides where a request goes. The layers in this article decide whether.

The layers at a glance

Every request to port 443 passes these checks in order. Each one is cheap, and each one stops a different kind of visitor:

No single layer is perfect. GeoBlock is fooled by a VPN, CrowdSec doesn’t know every attacker, and every login can have a bug. Together, they turn “anyone on the internet” into “a few people, in a few countries, with a valid login”.

1. One line for all services

You could add middlewares to every router separately. I attach the two global ones to the websecure entrypoint instead, in Traefik’s static configuration. That way no service can be forgotten, including the ones I add next year:

    command:
      # ... the configuration from part 1 ...

      # Security for EVERY site on 443: first GeoBlock, then CrowdSec, then security headers (step 5).
      # To switch both off quickly: comment out this line and run docker compose up -d
      - "--entrypoints.websecure.http.middlewares=geoblock@docker,crowdsec@docker,secheaders@docker"

      # The two plugins, downloaded from plugins.traefik.io at start
      - "--experimental.plugins.geoblock.modulename=github.com/PascalMinder/geoblock"
      - "--experimental.plugins.geoblock.version=v0.3.8"
      - "--experimental.plugins.crowdsec.modulename=github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
      - "--experimental.plugins.crowdsec.version=v1.7.1"

• The order matters: GeoBlock runs first because it’s the cheapest check. Requests from blocked countries never reach CrowdSec, which keeps its logs and work small.
• @docker means the middleware is defined with Docker labels, here on the Traefik container itself (next sections).
• Plugin versions are pinned, for the same reason as the Traefik image in part 1: a new plugin version can change options.
• Port 80 is not covered, and that’s fine: it only answers with a redirect to HTTPS, which then passes every check.

2. GeoBlock: only the countries you need

My services are used by my family, all of us in two European countries. There’s no reason for anyone in other countries to reach my login pages. GeoBlock looks up the country of each visitor’s IP address and only lets the allowed ones through. These labels go on the Traefik container:

    labels:
      # --- GeoBlock: only allow listed countries (+ private/home IPs) ---
      - "traefik.http.middlewares.geoblock.plugin.geoblock.countries[0]=DE"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.countries[1]=AT"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowLocalRequests=true"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowUnknownCountries=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.unknownCountryApiResponse=nil"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.blackListMode=false"

      # Exceptions: a service that has to reach you from abroad
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowedIPAddresses[0]=203.0.113.0/24"

      # Country lookup
      - "traefik.http.middlewares.geoblock.plugin.geoblock.api=https://get.geojs.io/v1/ip/country/{ip}"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.apiTimeoutMs=750"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.cacheSize=100"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.forceMonthlyUpdate=true"

      # Logging: only denied requests, into their own file
      - "traefik.http.middlewares.geoblock.plugin.geoblock.silentStartUp=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logLocalRequests=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logAllowedRequests=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logApiRequests=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logFilePath=/var/log/traefik/geoblock.log"

• countries: the allowed countries as two-letter codes. Mine are different; pick your own. With blackListMode=false this is an allow list: everything not listed is blocked. The opposite (block a few countries, allow the rest) protects much less.
• allowLocalRequests=true: private addresses (your home network) are always allowed. Without it, you lock yourself out at home as soon as a request arrives with a local address.
• allowUnknownCountries=false: if the lookup finds no country, the request is blocked. Safer, at the price of a rare false block.
• allowedIPAddresses: exceptions for services that call you from another country. In my case that’s an AI assistant’s connector to Home Assistant, which comes from the provider’s published IP range in the US. Only allow ranges the provider publishes officially, never a guessed one.
• Lookup and cache: unknown IP addresses are looked up with an online service (geojs.io here), at most 750 ms. The last 100 results are cached, so repeat visitors don’t cause new lookups.
• Log file: every blocked request ends up in geoblock.log. It’s surprisingly instructive to read it after a day: most of it is automated scanning.

Let’s Encrypt still works with GeoBlock on. The TLS challenge from part 1 is answered by Traefik before any middleware runs, so the validation servers abroad aren’t blocked.

3. CrowdSec: known attackers and attack patterns

CrowdSec does two things. It reads Traefik’s access log and notices when an IP address behaves like an attacker (many failed logins, scanning for /wp-login.php on a server without WordPress, and so on). And it shares this with a community list, so you also block addresses that attacked someone else yesterday. In addition, its AppSec component works as a web application firewall (WAF): it checks each request against rules for common attacks before Traefik forwards it.

There are two parts: the CrowdSec engine (its own container) and a bouncer inside Traefik that asks the engine about every request.

The engine

  crowdsec:
    image: crowdsecurity/crowdsec:v1.8.1
    container_name: crowdsec
    restart: unless-stopped
    environment:
      # Detection rules: Traefik log parser, common web attacks, known CVEs, AppSec (WAF)
      COLLECTIONS: "crowdsecurity/traefik crowdsecurity/base-http-scenarios crowdsecurity/http-cve crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules"
      # Registers the Traefik bouncer with the key from .env
      BOUNCER_KEY_traefik: ${CROWDSEC_BOUNCER_KEY}
      TZ: Europe/Berlin
    volumes:
      - ./crowdsec/config:/etc/crowdsec
      - ./crowdsec/data:/var/lib/crowdsec/data
      - ./crowdsec/acquis.d:/etc/crowdsec/acquis.d:ro
      - ./traefik-logs:/var/log/traefik:ro
    networks:
      - proxy
    # No published ports: Traefik reaches it as crowdsec:8080 and crowdsec:7422

• Collections are rule bundles from the CrowdSec hub: a parser for Traefik’s log format, scenarios for typical web attacks and known vulnerabilities (CVEs), and the AppSec rule sets.
• BOUNCER_KEY_traefik registers Traefik as a bouncer with a key you choose. Create one and put it in the .env file next to the compose file, never in the compose file itself: echo "CROWDSEC_BOUNCER_KEY=$(openssl rand -hex 32)" >> .env.
• Traefik’s log folder is mounted read-only, so CrowdSec can read the access log from part 1.
• No published ports: only Traefik talks to CrowdSec, through the shared proxy network.

What CrowdSec reads is defined in crowdsec/acquis.d/traefik.yaml:

# 1. Traefik access log: brute force, scans, known exploits
filenames:
  - /var/log/traefik/access.log
labels:
  type: traefik
---
# 2. AppSec (WAF): Traefik sends every request here before passing it on
source: appsec
name: appsec
listen_addr: 0.0.0.0:7422
appsec_config: crowdsecurity/appsec-default
labels:
  type: appsec

The bouncer in Traefik

    labels:
      # --- CrowdSec bouncer ---
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.enabled=true"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecMode=stream"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecLapiScheme=http"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecLapiHost=crowdsec:8080"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecLapiKey=${CROWDSEC_BOUNCER_KEY}"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.updateIntervalSeconds=60"
      # AppSec (WAF)
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecEnabled=true"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecHost=crowdsec:7422"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecFailureBlock=true"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecUnreachableBlock=false"
      # never ban the home network
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.clientTrustedIPs[0]=192.168.10.0/24"

• crowdsecMode=stream: the bouncer downloads the full list of blocked addresses every 60 seconds and checks requests locally. That’s fast, and Traefik doesn’t have to ask CrowdSec for each request.
• crowdsecAppsecFailureBlock=true: if AppSec can’t decide about a request (an error in the check), the request is blocked.
• crowdsecAppsecUnreachableBlock=false: if the CrowdSec container is down, requests are let through. That’s a deliberate trade-off: during a CrowdSec update, my services stay online and GeoBlock still filters. If you’d rather be offline than unprotected, set it to true.
• clientTrustedIPs: your home network is never banned. Without it, a family member typing the wrong password five times can lock out the whole house.

Everyday commands

# which addresses are blocked right now, and why?
docker exec crowdsec cscli decisions list

# what was detected recently?
docker exec crowdsec cscli alerts list

# is the log being read, are the bouncer and AppSec talking to CrowdSec?
docker exec crowdsec cscli metrics

# unblock an address (e.g. a friend who got banned)
docker exec crowdsec cscli decisions delete --ip 198.51.100.7

# block an address by hand for 24 hours
docker exec crowdsec cscli decisions add --ip 198.51.100.7 --duration 24h

The access and GeoBlock logs grow every day, so I rotate them with logrotate on the host (7 days, compressed). copytruncate keeps the file in place, so neither Traefik nor CrowdSec needs a restart:

# /etc/logrotate.d/traefik
/path/to/traefik/traefik-logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}

4. Single sign-on in front of apps

Some apps have no login of their own, or a weak one: Traefik’s dashboard, the Zigbee2MQTT frontend, small admin tools. For those, Traefik asks my identity provider Authentik before every request: is this person logged in, and allowed to use this app? If not, they see Authentik’s login page, with two-factor authentication. This is called forward auth.

The middleware is defined once, with labels on the Authentik server container:

    labels:
      # Embedded outpost path (needed for forward auth on other domains)
      - traefik.http.routers.authentik-outpost.rule=HostRegexp(`.+`) && PathPrefix(`/outpost.goauthentik.io/`)
      - traefik.http.routers.authentik-outpost.priority=1000
      - traefik.http.routers.authentik-outpost.entrypoints=websecure
      - traefik.http.routers.authentik-outpost.tls=true
      - traefik.http.routers.authentik-outpost.service=authentik

      # Forward-auth middleware for apps WITHOUT their own login
      - traefik.http.middlewares.authentik.forwardauth.address=http://authentik-server:9000/outpost.goauthentik.io/auth/traefik
      - traefik.http.middlewares.authentik.forwardauth.trustForwardHeader=true
      - traefik.http.middlewares.authentik.forwardauth.authResponseHeaders=X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid

• The outpost router catches the path /outpost.goauthentik.io/ on every host name and sends it to Authentik. That’s where the login redirect comes back to. priority=1000 makes sure it wins against the app’s own router.
• forwardauth.address: Traefik asks this URL about every request. Authentik answers “yes” (the request continues) or with a redirect to the login page.
• authResponseHeaders: after a successful login, Authentik passes the user name, groups and e-mail to the app as headers. Apps that understand them can log the user in automatically.

Protecting an app is then one more label on its router, here for the Traefik dashboard from part 1:

      - "traefik.http.routers.traefik.middlewares=authentik@docker"

In Authentik, each protected app needs a Proxy Provider in forward-auth mode (single application) and an application that is bound to the users or groups allowed in. Without that, Authentik doesn’t know the host name and refuses everyone.

5. Security headers for every service

Security headers are short instructions that the server sends to the browser with each page. Many apps set some of them, but rarely all, and every app does it differently. A third middleware on the entrypoint adds the important ones to every service and removes the headers that only tell attackers which software and version you run. These labels go on the Traefik container, and the entrypoint line from step 1 gets a third entry: geoblock@docker,crowdsec@docker,secheaders@docker.

    labels:
      # --- Security headers for every site on 443 ---
      # HSTS: browsers use https only, for 1 year
      - "traefik.http.middlewares.secheaders.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.secheaders.headers.contentTypeNosniff=true"
      # Hide software names and versions (an empty value removes the header)
      - "traefik.http.middlewares.secheaders.headers.customResponseHeaders.Server="
      - "traefik.http.middlewares.secheaders.headers.customResponseHeaders.X-Powered-By="

• HSTS (stsSeconds): after the first visit, the browser refuses to open the site over plain HTTP for one year, even if someone tries to redirect it there in a public Wi-Fi. I left out includeSubdomains and preload on purpose: they also bind every other subdomain of your domain to HTTPS, and preload is very hard to undo.
• contentTypeNosniff: the browser trusts the declared file type and doesn’t guess. That stops an uploaded “image” from being run as a script.
• Removing Server and X-Powered-By: before, my services told everyone things like Server: nginx or X-Powered-By: PHP/8.5. That doesn’t make anything vulnerable, but it saves an attacker the first step of looking up exploits for exactly that version.

Checking takes one command per service. You should see strict-transport-security and x-content-type-options, and no server line:

curl -s -o /dev/null -D - https://app.example.com/ | grep -i -E "strict-transport|x-content-type|^server|x-powered"

6. Container basics

A few small settings on the containers themselves, which cost nothing:

  traefik:
    image: traefik:v3.7
    security_opt:
      - no-new-privileges:true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # ...

• no-new-privileges: processes in the container can’t gain more rights later (for example through a setuid program). If someone ever breaks into Traefik, this makes the next step harder.
• Docker socket read-only: Traefik only needs to read container information. Be aware that :ro only protects the socket file; the Docker API behind it still accepts commands. A stricter solution is a socket proxy, a small container that only lets through the read requests Traefik needs. I use one for my monitoring portal and plan to switch Traefik to it too.
• No published ports on any service except Traefik (80 and 443). Everything else is only reachable through Traefik and therefore through all the layers above. A forgotten ports: line bypasses all of them.
• exposedbydefault=false from part 1 belongs here too: nothing is public by accident.

7. Testing that it works

Don’t trust a security setup you haven’t tested. These checks take five minutes. Run the attack tests from outside your home network (mobile data, not Wi-Fi), because your home network is on every allow list:

# AppSec should block typical attack requests with 403
curl -s -o /dev/null -w "%{http_code}n" "https://app.example.com/?id=1%27%20OR%20%271%27=%271"
curl -s -o /dev/null -w "%{http_code}n" "https://app.example.com/../../etc/passwd"
curl -s -o /dev/null -w "%{http_code}n" "https://app.example.com/.env"

# did CrowdSec see it?
docker exec crowdsec cscli alerts list | head

# GeoBlock: requests from other countries show up here
tail -n 5 traefik-logs/geoblock.log

# forward auth: without a login you should be sent to Authentik (302)
curl -s -o /dev/null -w "%{http_code} %{redirect_url}n" https://traefik.example.com/

To test GeoBlock from another country, use a VPN with an exit in a blocked country, or one of the many online “check website from another location” services. You should get a 403.

What I don’t do (yet)

• Central frame and content policies (X-Frame-Options, Content Security Policy): they depend too much on each app, so the apps set them themselves (see step 5).
• Custom TLS options: not needed for me. I checked with openssl s_client: Traefik’s defaults already refuse TLS 1.0 and 1.1 and only accept 1.2 and 1.3.
• Rate limiting: Traefik’s ratelimit middleware on login pages. CrowdSec covers most of it by banning brute-force attempts.
• The socket proxy for Traefik, as mentioned above.

What I learned

• Entrypoint middlewares beat per-router middlewares: new services are protected from their first second, without me remembering anything.
• Allow lists beat block lists. Listing the two countries I need is safer and simpler than listing the hundred I don’t.
• Always exempt the home network, in GeoBlock and in CrowdSec. Otherwise the first person locked out is you.
• Decide what happens when a security layer fails: block everything, or let traffic through. Both are valid, but it should be a decision, not a default you never looked at.
• Test from outside. Everything looks secure from your own sofa, because your home network is on every allow list.

In short

Problem: Every self-hosted service wants its own port, its own certificate and its own way to be reached from outside. After the third service, that gets messy.

Solution: One Traefik container in front of everything. It answers on ports 80 and 443, gets Let’s Encrypt certificates on its own, and sends each request to the right service, based on a few labels in each docker-compose.yml.

Tested with: Traefik 3.7, Docker Compose on a small home server, Let’s Encrypt, about ten services (Docker containers and one Home Assistant VM)

Traefik is the front door of my homelab. Every request from the internet arrives there first, and Traefik decides which service gets it. This article explains my configuration line by line: how Traefik is set up, how a container gets published with labels, how services outside Docker are added, and how the certificates work. Security hardening (geo-blocking, CrowdSec, single sign-on in front of services) is left out on purpose. It gets its own article, because it builds on everything here.

1. How Traefik thinks

Traefik has four building blocks. Once these are clear, every config line makes sense:

There are also two kinds of configuration. The static configuration is read once at start: entrypoints, certificate settings, where to find routes. The dynamic configuration is the routes themselves. Traefik reads it from Docker labels and from files, and picks up changes without a restart.

2. Before you start

1. DNS: an A record for every host name (for example vault.example.com) that points to your public IP address. A wildcard record works too.
2. Router: forward ports 80 and 443 from your internet router to the Docker host. Nothing else needs to be open.
3. A shared Docker network that Traefik and all published containers join:

docker network create proxy

4. A file for the certificates. Traefik refuses to use it if other users can read it:

mkdir -p traefik-data/dynamic
touch traefik-data/acme.json
chmod 600 traefik-data/acme.json

3. The Traefik container

I put the whole static configuration into the command section of the compose file. A separate traefik.yml works just as well; I like having everything in one place.

services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    restart: unless-stopped
    networks:
      - proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik-data/acme.json:/acme.json
      - ./traefik-data/dynamic:/dynamic:ro
      - ./traefik-logs:/var/log/traefik
    command:
      # General
      - "--global.checknewversion=false"
      - "--global.sendanonymoususage=false"
      - "--log.level=INFO"
      - "--accesslog=true"
      - "--accesslog.filepath=/var/log/traefik/access.log"
      - "--api.dashboard=true"

      # Where routes come from
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--providers.file.directory=/dynamic"
      - "--providers.file.watch=true"

      # Ports
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"

      # Send everything from http to https
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"

      # Let's Encrypt
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=you@example.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/acme.json"

      # No timeout for long uploads (Nextcloud)
      - "--entrypoints.web.transport.respondingTimeouts.readTimeout=0"
      - "--entrypoints.websecure.transport.respondingTimeouts.readTimeout=0"

networks:
  proxy:
    external: true

What the lines do:

• Docker socket: Traefik watches Docker to see which containers start and stop and which labels they have. Read-only is enough. How to protect this further is part of the hardening article.
• exposedbydefault=false: only containers with the label traefik.enable=true get published. Without this, every container you start would be reachable from the internet.
• providers.docker.network=proxy: Traefik talks to containers through the shared proxy network. This matters when a container is in more than one network: without it, Traefik may pick an address it can’t reach.
• File provider: every .yml file in /dynamic is read as extra routes, and watch=true applies changes on save. That’s how services outside Docker get in (step 5).
• Redirect: a request to http:// is answered with a redirect to https://. No service needs its own redirect.
• Access log: one line per request. It’s the first place to look when something doesn’t arrive, and later the input for intrusion detection.
• readTimeout=0: Traefik’s default read timeout cut off large Nextcloud uploads. Zero means no limit. If you don’t upload big files, leave it out.

Which version tag to use

The part after the colon in image: traefik:v3.7 is the tag. It decides which Traefik version Docker downloads, and which version you get after the next docker compose pull. Traefik publishes the same release under several tags:

Traefik follows semantic versioning: the first number (major) may break your configuration, the second (minor) adds features, the third (patch) only fixes bugs and security issues. The safer the tag, the more often you have to update it by hand.

Why this matters for a reverse proxy in particular: when Traefik breaks, every service is offline at once, not just one. And in many homelabs the updates run automatically at night. With latest, a major release can take everything down at 4 am, and you find out in the morning when nothing loads.

My recommendation is v3 if your updates run automatically, or v3.7 if you update by hand and read the release notes anyway. Traefik is exposed to the internet, so don’t pin an exact version and then forget it. Security fixes only arrive with new patch releases.

Updating and going back are both one change in the compose file:

# which version runs right now?
docker exec traefik traefik version

# update: change the tag if needed (e.g. v3.7 -> v3.8), then
docker compose pull traefik
docker compose up -d traefik
docker logs traefik --since 2m    # look for errors

# something broke? put the old tag back and run the same two commands again

Start it with docker compose up -d and check docker logs traefik. There should be no errors, only a line saying the providers started.

4. Publishing a container with labels

This is where Traefik shines. A service doesn’t publish any port on the host. It joins the proxy network and describes its route with labels. Here is my Vaultwarden as an example, reduced to the Traefik part:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.vaultwarden.rule=Host(`vault.example.com`)"
      - "traefik.http.routers.vaultwarden.entrypoints=websecure"
      - "traefik.http.routers.vaultwarden.tls.certresolver=letsencrypt"
      - "traefik.http.routers.vaultwarden.service=vaultwarden"
      - "traefik.http.services.vaultwarden.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

• Router name (vaultwarden): any name, but unique across all containers. Copying a block and forgetting to rename it is the most common mistake; the second container then silently replaces the first.
• rule: which host name belongs to this service. You can combine rules, for example Host(`example.com`) && PathPrefix(`/api`).
• entrypoints=websecure: HTTPS only. Plain HTTP never reaches the router, because the entrypoint redirects it first.
• tls.certresolver=letsencrypt: Traefik requests the certificate for the host name on the first request and renews it on its own.
• server.port: the port inside the container, not one on the host. Traefik usually guesses it from the image, but stating it avoids surprises with images that expose several ports.

After docker compose up -d the service is online under its name, with a valid certificate. No Traefik restart, no port forwarding, no certificate handling.

5. Services outside Docker

My Home Assistant runs in a virtual machine, not in Docker, so it has no labels. For services like this I write the route as a file in the dynamic folder:

# traefik-data/dynamic/homeassistant.yml
http:
  routers:
    homeassistant:
      rule: "Host(`home.example.com`)"
      entryPoints:
        - websecure
      service: homeassistant-service
      tls:
        certResolver: letsencrypt

  services:
    homeassistant-service:
      loadBalancer:
        servers:
          - url: "http://192.0.2.20:8123"

The address is the VM’s local IP address and port. Save the file and the route is live; Traefik’s log shows that it read the new configuration. The same works for a NAS, a router’s web interface or anything else in your network that speaks HTTP.

Home Assistant also needs to know that it sits behind a proxy, or it rejects the requests with “400 Bad Request”. In its configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.0.2.10   # the Docker host running Traefik

6. Certificates with Let’s Encrypt

I use the TLS challenge: Let’s Encrypt connects to port 443, and Traefik proves it controls the host name right there. The advantages: no extra port, no DNS provider API key, and it works for every host name that points to your IP address. The limit: no wildcard certificates, for those you need the DNS challenge.

All certificates and the account key end up in acme.json. Back up this file. Without it, Traefik requests every certificate again after a rebuild, and Let’s Encrypt has rate limits. How I back up the whole homelab is explained in a separate article.

7. The dashboard

Traefik’s dashboard shows every router, service and middleware it knows, and whether it has errors. It’s the fastest way to see why a route doesn’t work. I publish it like any other service, with labels on the Traefik container itself:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.traefik.rule=Host(`traefik.example.com`)"
      - "traefik.http.routers.traefik.entrypoints=websecure"
      - "traefik.http.routers.traefik.tls.certresolver=letsencrypt"
      - "traefik.http.routers.traefik.service=api@internal"

api@internal is Traefik’s built-in service for the dashboard; there’s no port to set.

8. When something doesn’t work

Two commands cover most cases:

# errors while reading routes or getting certificates
docker logs traefik 2>&1 | grep -i -E "error|acme"

# did the request reach Traefik, and what did it answer?
tail -f traefik-logs/access.log

What I learned

• Labels beat config files for containers: the route lives next to the service it belongs to, and it disappears when the service does.
• exposedbydefault=false is not optional. Publishing should always be a deliberate decision per container.
• One shared network and traefik.docker.network=proxy on every service saved me from most 502 errors.
• Back up acme.json together with the compose files.
• A reverse proxy is not a firewall. It decides where a request goes, not whether it should get in. That’s the topic of the next article: geo-blocking, CrowdSec and single sign-on in front of Traefik’s routes.

In short

Problem: Paper piles up, invoices arrive as e-mail, PDF and now XML, and German law expects you to keep all of it for up to ten years, findable and unchanged.

Solution: A self-hosted document archive (Paperless-ngx), a network scanner, a few clear daily routines, a written process description, and a retention plan based on the current German rules.

Tested with: Paperless-ngx in Docker on a small home server, a network scanner with document feeder, Nextcloud as file share, legal status in Germany as of October 2026

Small businesses and home offices drown in paper: letters, receipts, bank statements, contracts. On top of that, more and more invoices arrive by e-mail, and since 2025 every business in Germany must be able to receive electronic invoices. That is a good moment to stop filing paper and build a proper paperless office. Mine runs in my homelab, and the examples below come from that setup. This guide covers the whole path: the technical setup, the daily routines for the people who work with it, the compliance side, and how long you really have to keep what.

1. What “paperless” should mean

Before buying a scanner, agree on the goal. For us it was four rules:

1. One archive for everything: scanned paper, e-mail attachments and e-invoices end up in the same place.
2. Digital originals stay original. A PDF or XML invoice that arrived by e-mail is stored exactly as received. Printing it and scanning it again is not allowed.
3. Everything is searchable through text recognition (OCR) and a small set of tags.
4. Nothing is lost: automatic backups, including one copy outside the house.

2. The technical setup

The building blocks are cheap and mostly open source:

A minimal Paperless-ngx stack looks like this. Passwords and keys go into a .env file next to it, never into the compose file:

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
  db:
    image: docker.io/library/postgres:17
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${DB_PASSWORD}
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on: [db, broker]
    ports:
      - "127.0.0.1:8010:8000"   # only via reverse proxy / SSO
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBPASS: ${DB_PASSWORD}
      PAPERLESS_SECRET_KEY: ${SECRET_KEY}
      PAPERLESS_URL: https://paperless.example.com
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_OCR_LANGUAGE: deu+eng
      PAPERLESS_FILENAME_FORMAT: "{{ created_year }}/{{ correspondent }}/{{ created }} {{ title }}"

A few settings matter more than they look:

• OCR language: deu+eng recognises German umlauts and English words in the same document.
• Original and archive version: Paperless keeps the file exactly as it arrived and creates a separate searchable PDF/A next to it. For compliance, the original is the one that counts.
• Consume folder: the scanner, the e-mail import and people drop files into one folder. Paperless picks them up from there.
• Not on the internet: the port is bound to the server itself and only reachable through a reverse proxy with single sign-on. An archive full of invoices, contracts and bank statements is a prize for attackers.

E-invoices need special care

Since 1 January 2025 every business in Germany must be able to receive electronic invoices from other German businesses. An e-invoice is a structured file: either an XRechnung (pure XML) or a ZUGFeRD invoice (a PDF with the XML embedded). Two things follow from that:

• The XML is the legal original, not a printout or a screenshot. Store the file exactly as received.
• A pure XML file is not readable for humans. Keep a viewer at hand (for example a free XRechnung viewer) and store a readable visualisation next to the original, never instead of it.

For sending there are transition periods: paper and simple PDF invoices are still allowed until the end of 2026, and until the end of 2027 for businesses with a prior-year turnover of up to 800,000 euros. After that, invoices between German businesses must be e-invoices. Small amounts up to 250 euros and businesses under the small-business rule have exceptions; ask your tax advisor which apply to you.

3. Classification: tags, correspondents and a bit of AI

Search only works if documents are sorted consistently. Paperless offers four tools. Use them for different things:

Paperless learns from your sorting and suggests correspondents and tags for new documents. We added a small classifier on top that asks a language model for the right target folder. If you do the same, be careful with privacy: our classifier only sends the first part of the text, and it masks personal data before sending it: names, addresses, IBANs, tax and customer numbers, and all money amounts. Documents it is unsure about get a to-review tag instead of being filed automatically.

4. Workflows for the people who use it

The technology is the easy part. The paperless office only works if everyone follows the same routines. These are routines that work well for a small office; adapt them to your situation:

Incoming paper (daily)

1. Open the mail, remove staples, put everything into the document feeder.
2. Scan with duplex at 300 dpi. One document per scan job, or use separator sheets.
3. Check the result in Paperless the same day: is every page readable, is the OCR text plausible, did the classification work?
4. Put the paper into a box for the current month. It stays there until the monthly check (see below), not longer.

Invoices and documents by e-mail

• Use one dedicated mailbox for invoices and give that address to all suppliers.
• Let Paperless fetch the attachments automatically with its built-in mail import and tag them for review.
• Never print an e-mail invoice. The file is the original.

Receipts on the road

Fuel, parking, office supplies: photograph the receipt with the phone the same day and upload it, for example through a Paperless mobile app or a shared Nextcloud folder that Paperless consumes. Keep the paper receipt in the month’s box as well, because thermal paper fades and a bad photo is worthless.

Monthly routine

1. Work through everything tagged to-review.
2. Compare the month’s bank statements with the filed invoices: is there a document for every booking?
3. Hand the month over to the tax advisor (a shared folder or an export with all for-tax-advisor documents).
4. Check a sample of the scanned paper against the originals, note the check in the log, then destroy the paper. Keep the exceptions listed in section 6.

Roles and permissions

Give every person their own login. Business documents belong to the business owner; private household documents can be visible to the whole family. Nobody except the administrator may delete documents, and even then deletion should go through a trash bin with a waiting period.

5. Compliance: GoBD, process documentation and data protection

In Germany, digital bookkeeping and archiving follow the GoBD, the tax authority’s principles for proper electronic records. In practice they boil down to a few requirements:

Be honest about one point: a self-hosted Paperless-ngx is not a certified “audit-proof” archive. You cover the requirements through the way you run it: restricted deletion rights, logging, backups and a documented process. Discuss with your tax advisor whether that is enough for your business.

The process documentation (Verfahrensdokumentation)

This document is what makes destroying paper after scanning possible in the first place, so write it before you shred the first original. It describes in plain words:

• which documents are scanned, by whom, when and with which device and settings;
• how the scan is checked for completeness and legibility, and who checks it;
• how e-mail and e-invoices are received, checked and archived;
• when and how paper originals are destroyed, and which ones are kept;
• the system: software, versions, storage, access rights, backups and how a restore works;
• who is responsible, and when the document was last reviewed.

Review it once a year and every time something changes, such as a new scanner, a new software version or a new person doing the bookkeeping. The process documentation itself must be kept as long as the documents it describes.

Data protection (GDPR)

• The archive contains personal data of customers, suppliers and family members. Limit access to the people who need it.
• Every external service that sees documents (cloud storage, an AI classifier, an OCR service) needs a data processing agreement, and personal data should be masked before it leaves the house.
• Retention periods are also deletion deadlines: once a document is no longer needed for tax or commercial law, personal data in it should be deleted.

6. How long to keep what

The tax code (§ 147 AO) and the commercial code (§ 257 HGB) set the periods. Since 2025 the period for booking vouchers is shorter than before:

Three details people often get wrong:

• The period starts at the end of the calendar year in which the document was created or received. An invoice from March 2026 must be kept until the end of 2034 (8 years from 31 December 2026).
• Open tax assessments extend it: as long as the tax assessment for a year is still open (for example during an appeal or an audit), the documents for it must not be destroyed, even if the period has passed.
• Some industries differ: for banks, insurers and investment firms, other periods apply. Check if that concerns you.

Some paper originals should never be destroyed after scanning, even with a good process: notarial deeds, annual financial statements and opening balance sheets with original signatures, customs documents, and anything where the original itself has legal value (for example certificates or documents with seals). Keep these in a folder, and scan them for convenience only.

A simple way to handle this in Paperless: a custom field “keep until” (a year) on every document type that has a retention period, and a saved view that lists everything whose year has passed. Once a year you decide what to delete. Don’t let anything be deleted automatically.

7. Rollout plan

8. Checklist

• Archive only reachable through login, ideally single sign-on, not exposed to the internet
• Nightly backup, offsite copy, restore tested at least once
• Dedicated invoice mailbox with automatic import
• E-invoices stored as original XML or ZUGFeRD PDF, with a viewer available
• Written folder and tag list
• Process documentation written and reviewed by the tax advisor
• Monthly review routine with a scan check and log
• Retention field and a yearly deletion review
• Box for paper originals that must be kept

What I learned

• The hard part is not the software but the routine. Plan a fixed time each day and each month for it.
• Write the process documentation early. It forces you to decide things you would otherwise leave open.
• Mask personal data before any document text leaves the house, also for “just a quick AI classification”.
• Check ownership and permissions with a second user account before you go live. Many “it doesn’t work for her” problems were permission problems.
• Deleting in one place should delete everywhere. We sync the Paperless trash to the Nextcloud copy, otherwise old copies live on.

In short

Problem: Radiator thermostats measure the temperature right next to the hot radiator, a shared blueprint stopped reacting, and an update silently broke the heating.

Solution: Three small automations per room (Toggle, Target Sync, Calibration), a real room sensor fed into every valve, and a few safety nets that tell me when something drifts.

Tested with: Home Assistant, Zigbee2MQTT 2.14, 12 SONOFF TRVZB radiator valves, Zigbee temperature and motion sensors

Our house has nine heated rooms with twelve smart radiator valves. The goal was simple: warm when someone is in the room, a few degrees less when not, and no heating with the window open. Getting there took a few rebuilds. This is the setup that works now, and the problems we hit on the way.

The building blocks per room

Every room uses the same set of helpers. That makes the automations almost identical, and a new room is mostly copy and rename.

On top of that, each room has three automations:

• Toggle follows the master switch and turns the valve and the Target Sync on or off.
• Target Sync decides between Comfort and ECO and writes the target to the valve.
• Calibration feeds the real room temperature into the valve.

Why I dropped the blueprint

At first all rooms ran on one shared heating blueprint. It was convenient until it wasn’t: at the end of August it simply stopped reacting to some inputs, because an internal guard condition failed. One bug in a shared blueprint means every room is affected at once, and the logic is hard to debug from the outside.

I replaced it with three plain automations per room. That is more automations (33 for the whole house), but each one is short, does one thing, and shows up clearly in the trace when something goes wrong.

1. Toggle

When the master switch goes on, the valve is set to heat, the Target Sync is enabled and run once, so the right temperature is applied immediately. When it goes off, the Target Sync is disabled first, then the valve is switched off.

alias: Office - Heating - Toggle
triggers:
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "on"
    id: turned_on
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "off"
    id: turned_off
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: turned_on
        sequence:
          - action: climate.set_hvac_mode
            target:
              entity_id: climate.office_heating_valve
            data:
              hvac_mode: heat
          - action: automation.turn_on
            target:
              entity_id: automation.office_heating_target_sync
          - action: automation.trigger
            target:
              entity_id: automation.office_heating_target_sync
      - conditions:
          - condition: trigger
            id: turned_off
        sequence:
          - action: automation.turn_off
            target:
              entity_id: automation.office_heating_target_sync
          - action: climate.set_hvac_mode
            target:
              entity_id: climate.office_heating_valve
            data:
              hvac_mode: "off"
mode: single

2. Target Sync

The Target Sync is where the rooms differ. In the office it follows a motion sensor: Comfort after two minutes of motion, ECO after ten minutes without. The delays stop the heating from jumping up and down when someone just walks through.

alias: Office - Heating - Target Sync
triggers:
  - trigger: state
    entity_id: binary_sensor.office_motion
    to: "on"
    for: { minutes: 2 }
  - trigger: state
    entity_id: binary_sensor.office_motion
    to: "off"
    for: { minutes: 10 }
  - trigger: state
    entity_id:
      - input_number.temperature_comfort_office
      - input_number.temperature_eco_office
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "on"
conditions:
  - condition: state
    entity_id: input_boolean.heating_office_on
    state: "on"
actions:
  - if:
      - condition: state
        entity_id: binary_sensor.office_motion
        state: "on"
    then:
      - action: climate.set_temperature
        target:
          entity_id: climate.office_heating_valve
        data:
          temperature: "{{ states('input_number.temperature_comfort_office') | float }}"
    else:
      - action: climate.set_temperature
        target:
          entity_id: climate.office_heating_valve
        data:
          temperature: "{{ states('input_number.temperature_eco_office') | float }}"
mode: restart

Other rooms use other signals with the same pattern:

• Schedule only (kitchen, bedroom, bathroom): Comfort inside the schedule, ECO outside it.
• Schedule and presence (rooms that belong to one person): Comfort only if the schedule is on and that person is at home.
• A device as presence: in the gaming room the AV receiver is the best sign that someone is there. Receiver on means Comfort, receiver off means a lower setback.

3. Calibration: the part that matters most

A radiator thermostat measures the temperature where it sits: right next to the hot radiator. So it thinks the room is warm long before it is, and closes too early.

The SONOFF TRVZB can use an external temperature instead. In Zigbee2MQTT it has two relevant entities:

• a select “Temperature sensor”: local_temperature (its own sensor) or remote_temperature (an external value)
• a number “External temperature input” that receives the external value

The Calibration automation copies a real room sensor into that input whenever the reading has been stable for two minutes. It also checks the select, because after a reconnect or a battery change the valve sometimes falls back to its own sensor.

alias: Office - Climate - Calibration
triggers:
  - trigger: state
    entity_id: sensor.office_temperature
    for: { minutes: 2 }
  - trigger: state
    entity_id: select.office_heating_valve_temperature_sensor_select
    not_to:
      - remote_temperature
      - remote_source_offline
      - unavailable
      - unknown
conditions:
  - condition: numeric_state
    entity_id: sensor.office_temperature
    above: 0
actions:
  # switch the valve back to the external sensor if it reverted
  - if:
      - condition: not
        conditions:
          - condition: state
            entity_id: select.office_heating_valve_temperature_sensor_select
            state:
              - remote_temperature
              - remote_source_offline
    then:
      - action: select.select_option
        target:
          entity_id: select.office_heating_valve_temperature_sensor_select
        data:
          option: remote_temperature
        continue_on_error: true
  # feed the real room temperature into the valve
  - action: number.set_value
    target:
      entity_id: number.office_heating_valve_external_temperature_input
    data:
      value: "{{ states('sensor.office_temperature') | float }}"
mode: single

The condition above: 0 keeps a sensor that reports 0 or nothing from cooling the house down. With the calibration in place, the room finally reaches the temperature it shows on the dashboard.

4. No heating with the door open

The living room has a terrace door and two windows, and the heating kept running when they were open. The pause automation switches the three valves off after a door or window has been open for one minute, and switches them back on when all of them are closed again.

The important detail: it does not touch the master switch. Instead it sets its own flag (input_boolean.heating_living_room_paused). Toggle and Target Sync leave the valves alone while the flag is on. Because the flag is a helper and not a wait in the automation, it also survives a Home Assistant restart. A start trigger restores the heating if everything was closed while Home Assistant was down.

triggers:
  - trigger: state
    entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
    to: "on"
    for: { minutes: 1 }
    id: opened
  - trigger: state
    entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
    from: "on"
    to: "off"
    id: closed
  - trigger: homeassistant
    event: start
    id: ha_start
actions:
  - choose:
      - conditions:   # opened while heating is on -> pause
          - condition: trigger
            id: opened
          - condition: state
            entity_id: input_boolean.heating_living_room_on
            state: "on"
        sequence:
          - action: input_boolean.turn_on
            target: { entity_id: input_boolean.heating_living_room_paused }
          - action: climate.set_hvac_mode
            target: { entity_id: [climate.living_room_heating_1, climate.living_room_heating_2, climate.living_room_heating_3] }
            data: { hvac_mode: "off" }
      - conditions:   # all closed and paused by us -> resume
          - condition: trigger
            id: [closed, ha_start]
          - condition: state
            entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
            state: "off"
          - condition: state
            entity_id: input_boolean.heating_living_room_paused
            state: "on"
        sequence:
          - action: input_boolean.turn_off
            target: { entity_id: input_boolean.heating_living_room_paused }
          - if:
              - condition: state
                entity_id: input_boolean.heating_living_room_on
                state: "on"
            then:
              - action: climate.set_hvac_mode
                target: { entity_id: [climate.living_room_heating_1, climate.living_room_heating_2, climate.living_room_heating_3] }
                data: { hvac_mode: heat }
              - action: automation.trigger
                target: { entity_id: automation.living_room_heating_target_sync }
mode: queued

5. Safety nets

Automations fail quietly. These three make sure I hear about it:

• Child lock enforcement: after a battery change or a re-pair, a valve’s child lock can be off, and then anyone can turn the knob. If any of the twelve locks is off for 10 seconds, or Home Assistant starts, all locks are switched on again.
• Target mismatch alert: 10 minutes after a valve’s target or a Comfort/ECO value changes, a template checks every valve. If a target matches neither its room’s ECO nor its Comfort value (tolerance 0.25 °C), I get a Telegram message. Rooms with heating off, valves that are off and the paused living room are skipped. This catches a Target Sync that didn’t reach the valve.
• Zigbee2MQTT version alert: a message whenever Zigbee2MQTT runs a new version. The reason is the next section.

The core of the mismatch check, simplified to one valve:

{% set target  = state_attr('climate.office_heating_valve', 'temperature') | float %}
{% set eco     = states('input_number.temperature_eco_office') | float %}
{% set comfort = states('input_number.temperature_comfort_office') | float %}
{{ (target - eco) | abs > 0.25 and (target - comfort) | abs > 0.25 }}

The issues we had

What I learned

• Small, boring automations per room beat one clever shared blueprint. They are easier to read, test and fix.
• A radiator thermostat without an external sensor heats to the wrong temperature. Feeding it a real room sensor is worth the extra automation.
• Use a flag helper instead of a wait for anything that must survive a restart.
• Every automation that can fail silently needs an alert that checks the result, not just the trigger.

In short

Problem: WordPress was the last service still asking for its own password.

Solution: An OAuth2/OpenID provider in Authentik plus the OpenID Connect Generic plugin in WordPress, with every value listed below.

Tested with: WordPress 7.1, Authentik 2026.8, OpenID Connect Generic 3.11

I use Authentik as the single login for my self-hosted services. This blog should work the same way: one click on the login button, passkey, done. The normal WordPress login stays as a fallback, in case Authentik is ever down.

In the examples, Authentik runs at https://auth.example.com, the blog at https://blog.example.com, and the Authentik application slug is blog. Replace these with your own values.

How the login works

1. You click the login button on the WordPress login page.
2. WordPress sends you to Authentik, where you log in, for example with a passkey.
3. Authentik sends you back to WordPress with a one-time code.
4. WordPress exchanges the code for tokens in the background, reads your username and e-mail, and logs you in as the matching WordPress user.

1. Authentik: create the provider

In the Authentik admin interface go to Applications → Providers → Create and choose OAuth2/OpenID Provider. These are the settings I use:

For reference, the same provider created through the API:

curl -X POST https://auth.example.com/api/v3/providers/oauth2/ \
  -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provider for Blog",
    "client_type": "confidential",
    "authorization_flow": "<uuid of default-provider-authorization-implicit-consent>",
    "invalidation_flow": "<uuid of default-provider-invalidation-flow>",
    "property_mappings": ["<openid uuid>", "<email uuid>", "<profile uuid>"],
    "signing_key": "<uuid of the signing certificate>",
    "sub_mode": "hashed_user_id",
    "include_claims_in_id_token": true,
    "grant_types": ["authorization_code", "refresh_token"],
    "redirect_uris": [{
      "matching_mode": "strict",
      "url": "https://blog.example.com/wp-admin/admin-ajax.php?action=openid-connect-authorize"
    }]
  }'

2. Authentik: create the application

Go to Applications → Applications → Create:

Then open the application, go to Policy / Group / User Bindings and bind the users or the group who may log in to WordPress. Without a binding, every Authentik user can use the application.

All endpoints are listed in the discovery document of the application. Open it once to check that it works:

curl -s https://auth.example.com/application/o/blog/.well-known/openid-configuration

3. WordPress: install the plugin

Install and activate OpenID Connect Generic (by daggerhart) from the plugin directory. The settings are under Settings → OpenID Connect Client. As soon as the plugin is active, the login page shows a button. It only works once the settings below are saved.

4. WordPress: all plugin settings

Only the JWKS URI, the End Session URL and the issuer contain the application slug. The authorize, token and userinfo endpoints are the same for every application in Authentik.

How existing users are matched

With Link Existing Users on, the plugin looks for a WordPress user whose username matches the value of the identity key, here the Authentik username (preferred_username). The first login links the two accounts, and after that the link is fixed. Use the same username in WordPress and Authentik, or log in once with the matching account. With Create user if does not exist off, nobody gets a new WordPress account just because they have an Authentik login.

Optional: keep the secret out of the database

Instead of typing the values into the settings page, you can define them in wp-config.php. The plugin then uses these values and shows the fields as read-only:

define( 'OIDC_CLIENT_ID', 'your-client-id' );
define( 'OIDC_CLIENT_SECRET', 'your-client-secret' );
define( 'OIDC_CLIENT_SCOPE', 'openid email profile' );
define( 'OIDC_ENDPOINT_LOGIN_URL', 'https://auth.example.com/application/o/authorize/' );
define( 'OIDC_ENDPOINT_USERINFO_URL', 'https://auth.example.com/application/o/userinfo/' );
define( 'OIDC_ENDPOINT_TOKEN_URL', 'https://auth.example.com/application/o/token/' );
define( 'OIDC_ENDPOINT_LOGOUT_URL', 'https://auth.example.com/application/o/blog/end-session/' );

5. Test it

Before clicking the button, test the authorize request from the command line. A working provider redirects to the Authentik login flow:

curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" \
  "https://auth.example.com/application/o/authorize/?response_type=code&scope=openid%20email%20profile&client_id=YOUR_CLIENT_ID&state=test&redirect_uri=https%3A%2F%2Fblog.example.com%2Fwp-admin%2Fadmin-ajax.php%3Faction%3Dopenid-connect-authorize"

# good:  302 -> https://auth.example.com/if/flow/default-authentication-flow/?...
# wrong: 302 -> https://blog.example.com/...?error=invalid_request&...

If that looks good, log out of WordPress, click the login button and log in with Authentik. You should land in the dashboard as your existing user.

Troubleshooting

What I learned

• The Authentik UI fills in defaults that the API does not.
• The server log tells you the real reason when the browser only shows a generic error.
• Keep the local WordPress login as a fallback. If the identity provider is down, you still want to reach your own site.