What are we building?

By the end, Jellyfin 10.11 runs as a container on your server, reachable at https://jellyfin.YOUR_DOMAIN with valid HTTPS. Jellyfin is a completely free media server (no cloud, no telemetry, no subscription): you store your files, Jellyfin automatically pulls covers, descriptions and metadata and streams everything to the browser, phone, smart TV or the Jellyfin app.

The real challenge with a media server is storage space – a movie collection quickly bursts the small system SSD of a VPS. That’s why we mount netcup’s Local Block Storage: an additional, local disk that appears in the server like a normal drive and on which the library lives.

Prerequisites

• A running Traefik reverse proxy with the proxy network and the resolver le – see reverse proxy with Traefik.
• A subdomain jellyfin.YOUR_DOMAIN with a DNS record to your server IP – see connecting a domain to your server.
• Dedicated CPU cores are clearly at an advantage for smooth streaming (transcoding). On a shared VPS it works too for Direct Play, but gets tight quickly on re-encoding.
• Optional but recommended: booked netcup Local Block Storage for the library (step 2). Without it, you simply put the media in a folder on the system disk – until the space runs out.
• A few of your own media files (movies/series/music) that you’re allowed to host.

Whether your setup really needs dedicated cores is shown by the server calculator – with transcoding the answer is usually yes.

Step by step

Step 1: Create the DNS record

Create jellyfin.YOUR_DOMAIN (A/AAAA to your server IP) and check that it resolves:

dig +short jellyfin.YOUR_DOMAIN

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

Step 2: Mount netcup Local Block Storage

The Local Block Storage is additional storage you book to your server in the netcup customer account. Unlike the network-attached Storage Space of other providers (which is connected via NFS and is slower), it appears in the server as a completely normal local disk – ideal for a library because it’s fast and freely partitionable.

First look at which disks the server knows:

sudo fdisk -l

The system disk is typically /dev/sda (or /dev/vda). The new block storage appears as an additional device, usually /dev/vdb – recognizable by the size you booked.

Create a partition on the new disk (here /dev/vdb):

sudo cfdisk /dev/vdb

Choose gpt at the prompt (the modern standard – dos/MBR can address at most 2 TiB, libraries like to grow beyond that), then New, take the full size, and write the table with Write (type yes), then Quit. The partition /dev/vdb1 is created. Format it with an ext4 filesystem:

sudo mkfs.ext4 /dev/vdb1

Create a mount point and mount the partition:

sudo mkdir -p /mnt/media
sudo mount /dev/vdb1 /mnt/media

So that the disk is mounted automatically even after a reboot, you enter it in /etc/fstab with its UUID (not with /dev/vdb1, which can change). Read out the UUID:

sudo blkid /dev/vdb1

/dev/vdb1: UUID="a1b2c3d4-...." TYPE="ext4" ...

Open the fstab and append the line with your UUID:

sudo nano /etc/fstab

UUID=a1b2c3d4-....   /mnt/media   ext4   defaults   0   2

Check the entries before you rely on the reboot – a typo in the fstab can block the boot process:

sudo umount /mnt/media && sudo mount -a && df -h /mnt/media

If no error appears here and df -h shows your new disk under /mnt/media, everything is entered correctly.

Step 3: Create the project and media folders

Create the Compose project – the configuration is small and may go on the system disk. You create the subfolders config and cache right along, before the container starts for the first time: if the Docker daemon created them first, they would belong to root – but Jellyfin runs as UID 1000 (see step 4) and couldn’t write into its own /config, the container would crash on the first start.

mkdir -p ~/jellyfin/{config,cache} && cd ~/jellyfin

And the folder structure for the library on the block storage. Jellyfin sorts best when movies, series and music are kept separate:

sudo mkdir -p /mnt/media/{filme,serien,musik}

So that the Jellyfin container may read the files, they have to belong to your user. Determine your user and group ID (usually 1000) and hand over the folder:

id -u && id -g
sudo chown -R 1000:1000 /mnt/media

Now copy your media into the appropriate subfolders (via scp, rsync or an SFTP client). For clean recognition, a clear naming helps, e.g. filme/The Godfather (1972)/The Godfather (1972).mkv.

Step 4: The compose.yaml

Now the central file. Replace jellyfin.YOUR_DOMAIN with your subdomain:

services:
  jellyfin:
    image: jellyfin/jellyfin:10.11.11
    user: "1000:1000"
    environment:
      - JELLYFIN_PublishedServerUrl=https://jellyfin.YOUR_DOMAIN
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.jellyfin.rule=Host(`jellyfin.YOUR_DOMAIN`)"
      - "traefik.http.routers.jellyfin.entrypoints=websecure"
      - "traefik.http.routers.jellyfin.tls.certresolver=le"
      - "traefik.http.services.jellyfin.loadbalancer.server.port=8096"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

What the lines mean:

• image: …:10.11.11 – the fixed, current stable version. No latest (see “Maintenance & backups”).
• user: "1000:1000" – Jellyfin runs with your user/group ID so it can read the media. If you adjust other IDs in step 3, change them here too.
• JELLYFIN_PublishedServerUrl – tells Jellyfin under which public address it’s reachable. This prevents app links from suddenly pointing to an internal IP.
• volumes: config (settings, users, metadata) and cache live small in the project folder; the library is mounted from the block storage under /mnt/media into the container as /media – :ro (read-only), so Jellyfin never changes your originals.
• The four Traefik labels are the familiar pattern. New is only the port: Jellyfin listens on 8096, hence the loadbalancer.server.port label. Without it, there’d be a 502 Bad Gateway.
• No ports: – Jellyfin is reachable exclusively via Traefik (HTTPS), not directly from the internet.

Start the stack and watch it boot:

docker compose up -d
docker compose logs -f jellyfin

On the first start, certificate issuance takes a few seconds. Once Startup complete appears in the log, Jellyfin is ready.

Step 5: The initial setup wizard

Open https://jellyfin.YOUR_DOMAIN in the browser. On the very first call, a wizard guides you through the basic setup:

1. Choose the language.
2. Create an administrator account – set a long, unique password, because the login page is publicly on the net.
3. Add media libraries: click “Add media library”, choose the type (e.g. Movies), and enter the container path as the folder – i.e. /media/filme (not /mnt/media/filme, that’s the path on the host!). Repeat this for serien and musik.
4. Set the metadata language and you can accept the rest.

After the wizard, Jellyfin scans the folders and loads covers and descriptions. For large collections the first scan takes a while – you see the progress under Dashboard → Scheduled Tasks. After that you land on the home page and see your library with the first titles:

Step 6: Configure Jellyfin cleanly behind the proxy

Two settings make Jellyfin work correctly behind Traefik. Open Dashboard → Networking:

• Under Known proxies you enter the Traefik network so Jellyfin sees the real client IP (instead of Traefik’s container IP). You determine the subnet with:

  Terminal

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

  Enter the returned range (e.g. 172.19.0.0/16) there.

• HTTPS: since Traefik handles the encryption, Jellyfin itself needs no TLS. Leave the HTTPS options in Jellyfin empty – everything runs via the proxy.

WebSockets (for live updates of the interface) Traefik forwards automatically, nothing to do there.

Step 7: Transcoding vs. Direct Play

Whether your server breaks a sweat is decided here. Two cases:

• Direct Play – the end device can play the file as-is. The server just pushes bytes through, almost no CPU load. That’s the ideal case.
• Transcoding – format, codec or bitrate don’t fit the device (or the line is too slow), so Jellyfin re-encodes live. On a netcup server this happens via the CPU – with a 4K stream that can max out a whole server.

This is how you keep the load low:

• Provide suitable formats: H.264/AAC in an .mp4/.mkv plays directly on practically every device. Exotic codecs (e.g. certain 4K HEVC audio tracks) force transcoding.
• Set the client quality in the app to “Original/Direct Play” when the line is enough.
• Under Dashboard → Playback you can set the transcoding settings and a limit for simultaneous streams.

When things go wrong

Maintenance & backups

• Apply updates deliberately. The fixed tag (jellyfin:10.11.11) means: you decide when to update. Bump the tag → docker compose pull → docker compose up -d. Before jumping to a new major version, read the release notes – database migrations aren’t always reversible.
• Back up the config, treat the media separately. The config volume (users, settings, playback state, metadata) is small and the actually valuable part – back it up encrypted off-site with Restic. The library itself is usually too large for a classic backup and reproducible from the original media; decide deliberately whether you back it up or classify it as “replaceable”. Honestly: a second backup of your movie collection costs real storage.
• Monitor disk space. A library grows steadily. Keep an eye on usage (df -h /mnt/media) and best set up a monitor in Uptime Kuma that raises the alarm before the block storage is full.
• Publicly reachable = secure it. The login page is on the net, and Jellyfin brings no two-factor authentication (not even via an official plugin). So consistently assign strong passwords, deactivate unused accounts – and for purely private use, consider making Jellyfin reachable not publicly but only via a VPN.

What are we building?

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

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

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

Prerequisites

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

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

Step by step

Step 1: Create the DNS record

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

dig +short photos.YOUR_DOMAIN

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

Step 2: Prepare the folder and .env

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

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

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

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

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

Step 3: Create the compose.yaml

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

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

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

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

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

volumes:
  model-cache:

networks:
  default:
  proxy:
    external: true

Important to understand:

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

Step 4: Allow large uploads (Traefik timeout)

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

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

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

Step 5: Start and run through the initial setup

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

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

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

docker compose ps

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

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

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

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

Step 6: Connect the phone app

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

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

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

When things go wrong

Maintenance & backups

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

  Terminal

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

  Back up the dump together with the library folder encrypted and off-site with Restic. Alternatively, Immich can generate automatic DB dumps under Administration → Job queues – you still have to back up the photos separately.

• Rehearse the worst case once. A backup you’ve never restored is just a hope. To restore, you import the DB dump into a fresh Immich instance of the same version and place the library folder in the same spot – Immich offers the option “Restore from database” on the first start for this (the second button from step 5). What matters is the same version: the database state and the program must match.

• Backup before every update. Because migrations aren’t reversible, the backup is your only way back. Back up first, then raise IMMICH_VERSION, then docker compose pull && docker compose up -d.

• Honest about the effort: Immich often brings several releases per month. You don’t have to follow every one – but before a jump across several versions, read the release notes, and stick to the pinned version until you deliberately update.

• Keep an eye on disk space. Photos and videos grow steadily; Immich additionally creates thumbnails and converted videos. Monitor the disk usage (e.g. with Uptime Kuma) so the server doesn’t fill up.

What are we building?

By the end, Paperless-ngx 2.20 runs behind your Traefik proxy, reachable at https://paperless.YOUR_DOMAIN with HTTPS. Paperless is a document management system: you feed it scans or PDFs, it reads out the text via OCR (even from pure image scans), recognizes date and content, and stores everything searchably. Via tags, correspondents and document types you bring order into it; the full-text search later finds every document.

The clever part is the consume folder: everything you place there (e.g. from a network scanner) is imported and processed automatically. Paperless consists of five containers – the web server, a PostgreSQL database, a Redis broker for background processing, plus Gotenberg and Tika, which convert office documents into PDF. The official template provides the complete team.

The gain over a folder full of PDFs on the disk: Paperless makes every document searchable (even scanned paper), keeps the original and archive version cleanly separated, and can be automated via rules. Your documents stay on your server – no cloud service reads along, and you’re not tied to a proprietary format.

Prerequisites

• A running Traefik reverse proxy with the proxy network and the resolver le – see reverse proxy with Traefik.
• A subdomain paperless.YOUR_DOMAIN with a DNS record to your server IP – see connecting a domain to your server.
• A backup. Your most important documents land in Paperless – first set up backups with Restic.

Not sure which server size is enough? The server calculator calculates the RAM and CPU needs for your services.

Step by step

Step 1: Create the DNS record

Create paperless.YOUR_DOMAIN (A/AAAA to your server IP) and check:

dig +short paperless.YOUR_DOMAIN

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

Step 2: Generate a secret key

Paperless encrypts sessions with a secret key. The default is publicly known – a real risk for an instance on the internet. Generate your own:

head -c 50 /dev/urandom | base64

Copy the output – it goes into the configuration as PAPERLESS_SECRET_KEY shortly.

Step 3: Create the compose.yaml

Create the project – including the two bind-mount folders:

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

You deliberately create the subfolders consume and export now, as a normal user: if the Docker daemon created them at startup, they would belong to root – then neither you (cp into the consume folder) nor Paperless itself (runs via USERMAP_UID as UID 1000) could write into them.

Create compose.yaml. Replace paperless.YOUR_DOMAIN, the passwords and the PAPERLESS_SECRET_KEY:

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

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

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

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

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

volumes:
  data:
  media:
  pgdata:
  redisdata:

networks:
  default:
  proxy:
    external: true

The most important points:

• Only webserver is on the proxy network and carries Traefik labels (port 8000). The four helper services (db, broker, gotenberg, tika) stay internal.
• PAPERLESS_URL is mandatory behind a proxy. Without it, Paperless rejects the login with a CSRF/“403 Forbidden” error. It simultaneously sets the allowed hosts and the trusted origins.
• PAPERLESS_OCR_LANGUAGE: eng sets text recognition to English. English, German and a few other languages are already included in the image – no additional package needed.
• PAPERLESS_ADMIN_USER / _PASSWORD create the superuser automatically on the first start, so you can log in directly.
• USERMAP_UID/GID should match your server user’s ID (determine via id -u or id -g, usually 1000). Otherwise there’s “Permission denied” in the consume folder.
• export and consume are deliberately folders in the project directory (bind mounts): consume is the inbox, export the target for backups.

Paperless uses four storage areas in total, which you should keep apart: media contains your processed documents (the heart!), data the search index and helper data, consume is the inbox and export the backup target. For the backup, media and data plus the database count – exactly what the document_exporter further below takes off your hands.

Step 4: Start and log in

Pull the images (several GB) and start:

docker compose up -d
docker compose logs -f webserver

On the first start, Paperless sets up the database (migrations) – that takes a moment. Check that all five containers are running:

docker compose ps

You should see webserver, db, broker, gotenberg and tika with status running (the webserver becomes healthy after a short while). Once the worker is ready (celery@… ready in the log), open https://paperless.YOUR_DOMAIN. The login page appears:

Log in with admin and your password. You land on the home page with a short welcome message and initial statistics. At the bottom left you see the running version – handy to know the starting point before an update. You can change the language under Settings if needed; by default Paperless follows your browser’s language:

Step 5: Import the first document

Now the core. There are three ways to get a document in:

1. Via the web interface: click Upload documents at the top right and choose a PDF or image file.
2. Via the consume folder: place a file in ~/paperless/consume – Paperless detects it automatically, processes it and then deletes it from the folder. Ideal for a network scanner that scans directly there.
3. From a mailbox: under Email, Paperless can fetch an IMAP account and import attachments automatically – handy for invoices that come to you by mail anyway.

cp ~/an-invoice.pdf ~/paperless/consume/

Paperless accepts PDFs, images (JPG/PNG/TIFF) and – thanks to Gotenberg and Tika – office files like Word or Excel. For a pure image scan, the OCR reads out the text and places it as a searchable layer over the document; for a PDF with an existing text layer, Paperless skips the recognition and is correspondingly faster. The original is preserved untouched – Paperless additionally creates a searchable archive version.

After a few seconds (OCR takes some time), the document appears under Documents – with a preview and the recognized title:

A click opens the detail view: on the left the metadata (title, date, correspondent, tags) and the tabs for content, metadata and history, on the right the document with a zoomable preview. Paperless has already recognized the date from the scan and suggests it for confirmation – exactly what the OCR does for you in the background:

Step 6: Order with tags, correspondents & document types

So that the search works later, you assign tags (e.g. Tax, Insurance), assign a correspondent (the sender) and a document type (invoice, contract …). You can do that by hand – or automate it via workflows: rules that automatically tag incoming documents based on their content. This way your archive sorts itself over time.

The full-text search at the top then searches not only titles and tags, but the complete recognized text – a search for invoice amount or a customer name finds the matching document in seconds. Combined with the filters (correspondent, period, document type), the paper pile finally becomes a searchable archive.

A simple example of a workflow: if a new document contains the word “electricity bill”, automatically assign the tag Energy, set the correspondent to your electricity provider and the document type to Invoice. You create such rules under Administration → Workflows; they take effect for every incoming document. At the start it pays to sort a few documents by hand – from that you quickly see which rules repeat and can be automated. After a few weeks, the majority of your mail lands in the right place without your involvement.

When things go wrong

Maintenance & backups

• The clean backup is done by the document_exporter. It writes all documents, thumbnails, metadata and the database content into the export folder – portable and re-importable:

  Terminal

  docker compose exec -T webserver document_exporter ../export

  Then back up the export folder encrypted and off-site with Restic. Alternatively you back up the volumes media, data and the database directly – but the exporter is the recommended, migration-safe way.

• Use the same version when restoring. An export contains an image matching the database schema; only import it into a Paperless instance of the same version (document_importer ../export).

• Updates. Before the update, pull a backup, then raise the image tag (e.g. 2.20.15 → next version), docker compose pull and docker compose up -d. The database migrations run automatically at startup. Stay on the stable 2.x series – the 3.0 beta isn’t meant for production yet.

• Automate the backup. Best put the document_exporter in a daily cron job (e.g. at night) that afterwards backs up the export folder via Restic. That way you have a fresh, restorable state every morning – without having to think about it.

• Honest about the effort: Paperless runs very low-maintenance after that. The actual effort is filing new documents – but with a bit of set-up automation, the software increasingly takes that off your hands too. Plan the rough tag structure once, then the archive largely maintains itself.

What are we building?

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

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

Prerequisites

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

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

Step by step

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

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

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

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

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

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

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

Step 2: Fix the two quick warnings

Two warnings are done with one command each.

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

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

To verify, the setup check afterwards confirms:

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

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

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

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

Step 3: Set the HSTS security header via Traefik

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

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

First, extend the router line with nc-secure:

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

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

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

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

docker compose up -d nc-app

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

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

You should see exactly this:

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

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

Step 4: Set up email sending

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

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

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

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

Step 5: Enforce two-factor authentication

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Step 7: Check caching & PHP – the performance foundation

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

Nextcloud uses three cache roles. Check all three:

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

Expected:

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

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

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

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

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

With that, the overview is warning-free:

When things go wrong

Maintenance & backups

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

What are we building?

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

Prerequisites

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

Step by step

Step 1: The compose.yaml

Own folder, own file:

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

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

volumes:
  kuma-data:

networks:
  proxy:
    external: true

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

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

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

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

Step 2: Start and first login

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

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

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

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

Step 3: Create the first monitor

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

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

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

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

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

Create the matching monitor for every important service.

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

Step 4: Set up notifications (email and Telegram)

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

Email (SMTP)

Choose “Email (SMTP)” as the notification service and enter your mail provider’s data:

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

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

Telegram

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

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

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

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

Step 5: A public status page (optional)

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

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

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

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

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

• Retries: the service only counts as “Down” after n failed checks. 2–3 filters out individual dropouts without obscuring real outages for long.
• Heartbeat interval on failure: Kuma may check more often in the error case (e.g. every 20 seconds) to detect recovery quickly.
• Resend notification: Kuma can remind you every x minutes as long as a service is down – useful so an outage at night doesn’t get lost in a single mail.

Step 7: Monitor cron jobs with a push monitor

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

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

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

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

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

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

Step 8: Secure the admin login with 2FA

Your Kuma login protects access to all monitors, the stored notification credentials and the status-page configuration – and it’s publicly on the net. So enable two-factor authentication: under Settings → Security → Two-Factor Authentication. Kuma shows a QR code you scan with an authenticator app (e.g. Aegis or 2FAS); to activate, you enter the generated code once.

When things go wrong

Maintenance & backups

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

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

What are we building?

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

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

Prerequisites

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

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

Step by step

Step 1: Create the DNS record

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

dig +short cloud.YOUR_DOMAIN

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

Step 2: Determine the proxy subnet

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

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

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

Step 3: Create the compose.yaml

Create a folder and change into it:

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

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

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

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

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

volumes:
  nc_html:
  nc_db:

networks:
  default:
  proxy:
    external: true

What matters here:

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

Step 4: Start and run through the initial setup

Start the stack:

docker compose up -d

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

docker compose logs -f nc-app

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

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

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

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

Step 5: Set up background jobs (cron)

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

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

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

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

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

docker exec -u www-data nc-app php occ db:add-missing-indices
docker exec -u www-data nc-app php occ config:system:set default_phone_region --value=DE

Step 6: Connect the clients

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

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

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

When things go wrong

Maintenance & backups

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

  Terminal

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

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

• Updates: only one major version per step. From 34 to 35, never directly to 36. Bump the image tag (nextcloud:35-apache), then docker compose pull and docker compose up -d. The container runs the necessary occ upgrade automatically on start. Always make a backup first. Bump the cron sidecar to the same version.

• Check security. After setup, run the official Nextcloud Security Scan against your domain (target: grade A) and work through the warnings from the admin overview. The overview under Administration → Overview runs automatic checks and shows exactly what’s still missing. Keep Nextcloud up to date – security holes are closed promptly, but only if you update.

• Honest about the effort: a self-hosted cloud wants to be maintained. Reckon with an update pass roughly monthly and a regular look at the admin overview. In return, the data then really belongs to you.

What are we building?

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

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

Prerequisites

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

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

Step by step

Step 1: Generate the ADMIN_TOKEN

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

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

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

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

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

Password:
Confirm Password:

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

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

Step 2: Create the compose.yaml

Create a dedicated folder and change into it:

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

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

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

networks:
  proxy:
    external: true

The most important lines in detail:

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

Step 3: Start it and the first call

Start the container:

docker compose up -d

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

docker compose logs -f vaultwarden

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

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

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

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

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

Step 4: Close registration again

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

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

And apply the change:

docker compose up -d

Compose detects the changed environment variable and restarts the container. From now on the login page rejects new registrations. Further users (e.g. for the family) you invite specifically via the admin panel when needed – more on that shortly.

Step 5: The admin panel

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

Here you control the service centrally:

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

Step 6: Connect the clients

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

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

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

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

When things go wrong

Maintenance & backups

• Backups are non-negotiable for a password manager. Your entire vault is in the vw-data/ directory (SQLite database, keys, attachments). Back it up encrypted and off-site with Restic – add the folder ~/vaultwarden/vw-data to your backup sources. For a consistent database state, briefly run docker compose stop before the backup, or use the “Backup Database” function in the admin panel. A mere file copy while the container is running can catch an inconsistent state (SQLite writes into WAL files) – with a password manager that’s not a risk worth taking.

• Apply updates in a controlled way. Because we pinned the version, you update deliberately: before the switch read the release notes, then raise the tag in the compose.yaml (e.g. to the next 1.x) and pull anew:

  Terminal

  docker compose pull && docker compose up -d

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

• Keep registration closed. Occasionally check that SIGNUPS_ALLOWED is still false – always invite new users specifically via the admin panel.

• Rotate the ADMIN_TOKEN if it might be compromised: generate a new hash with the hash command from step 1, replace it in the compose.yaml, restart.

• Never lose the master password. There is no recovery. In a team/family setup, an emergency access can make sense – you set that up per vault in the account settings.