Kopia Docker Compose: Docker-Volumes verschlüsselt sichern

Kopia kennt pro Tresor genau ein Passwort, und es kennt keinen Weg daran vorbei. Keine Hintertür, kein „Passwort vergessen“, kein Support, der es zurücksetzt. Die Dokumentation sagt das in einem Satz: Ohne das Passwort gibt es keine Möglichkeit, die Dateien in diesem Repository wiederherzustellen. Ich finde, so soll ein Backup-Werkzeug reden. Es heißt nämlich auch: Wer die Platte mit deinem Backup klaut, hat eine Platte mit Rauschen.

Am Ende dieser Anleitung läuft Kopia als Container neben deinen anderen Diensten, sichert jede Nacht die Datenordner deiner Container verschlüsselt auf eine externe Platte, behält davon eine sinnvolle Auswahl und hat einmal bewiesen, dass es die Daten auch wieder herausrückt. Der letzte Punkt ist der, den die meisten auslassen.

Was Kopia anders macht als eine Kopie

Eine Kopie des Ordners data auf einen USB-Stick ist besser als nichts, und ich habe sie in jeder Anleitung hier empfohlen. Sie hat zwei Schwächen: Sie ist unverschlüsselt, und sie überschreibt sich selbst. Wenn Paperless am Dienstag ein Dokument zerlegt und du am Mittwoch kopierst, ist das zerlegte Dokument jetzt dein Backup.

Kopia löst beides. Jeder Durchlauf ist ein Snapshot, ein eingefrorener Stand von heute Nacht, und der von gestern bleibt daneben liegen. Im Tresor liegen die Daten mit AES-256 verschlüsselt, der Schlüssel entsteht aus deinem Passwort und verlässt deinen Rechner nie; die Doku schreibt dazu, Kopia erlaube gar keine unverschlüsselten Backups. Und weil Kopia Dateien in Stücke zerlegt und jedes Stück nur einmal speichert, belegen dreißig Snapshots von zwanzig Gigabyte am Ende etwa zwanzig Gigabyte plus das, was sich geändert hat, keine sechshundert.

Ein Wort zu den Grenzen, bevor es losgeht. Kopia sichert Dateien. Eine Datenbank, die gerade schreibt, ist als Datei nur so lange konsistent, wie niemand schreibt. Für Ordner mit Dokumenten, Fotos und Konfigurationen ist das egal. Für Paperless oder Nextcloud mit eigener Datenbank gilt: entweder vorher einen Dump ziehen, wie im Nextcloud-Backup-Beitrag beschrieben, oder die Container für die Minute des Snapshots anhalten. Darauf komme ich am Ende zurück.

Was du brauchst

• Einen Linux-Rechner, auf dem deine Container laufen, mit Docker und dem Compose-Plugin. Das ist der Rechner, der gesichert wird; Kopia läuft direkt daneben.
• Eine zweite Platte als Ziel: eine externe USB-Platte oder eine NAS-Freigabe, unter einem festen Pfad eingehängt. Ein Backup auf derselben Platte, von der es stammt, ist eine Kopie mit Lesezeichen, kein Backup.
• Port 51515 frei.
• Zwei Passwörter aus dem Passwort-Manager: eins für die Web-Oberfläche, eins für den Tresor. Das zweite ist das, das nicht verloren gehen darf.

Drei Prüfungen vorab. Die ersten beiden Befehle antworten mit einer Versionsnummer. Der dritte meldet „Port frei“ oder zeigt die Zeile des Dienstes, der 51515 schon belegt hat; wie du den loswirst, steht in einer eigenen Anleitung. Der vierte zeigt, ob die Backup-Platte wirklich eingehängt ist: In der Spalte Eingehängt auf muss /mnt/backup stehen. Steht dort /, liegt der Ordner auf der Systemplatte, und dann sicherst du gleich auf die Platte, die du eigentlich schützen willst.

docker --version
docker compose version
ss -tulpn | grep :51515 || echo "Port frei"
df -h /mnt/backup

Alle Beispielwerte stehen hier einmal gesammelt. Du ersetzt sie durch deine und musst danach nichts mehr nachschlagen.

Schritt 1: Ordner und Bauplan anlegen

Kopia bekommt einen eigenen Ordner im Home-Verzeichnis, darin die Compose-Datei. nano öffnet eine leere Datei; Inhalt einfügen, mit Strg+O und Enter speichern, mit Strg+X schließen. Wenn dir Compose noch fremd ist: Die Grundlagen stehen in einem eigenen Beitrag.

mkdir ~/kopia
cd ~/kopia
nano compose.yaml

Die Datei folgt dem Compose-Beispiel aus der Installationsdoku von Kopia; ich habe die Pfade auf die Beispielwerte gesetzt, die Version festgenagelt und zwei Flags weggelassen, dazu gleich mehr. Die beiden Passwörter ersetzt du, bevor du speicherst.

services:
  kopia:
    image: kopia/kopia:0.23.1
    container_name: kopia
    hostname: homelab-server
    restart: unless-stopped
    ports:
      - "51515:51515"
    environment:
      - KOPIA_PASSWORD=Repo-Passwort-hier-aendern
      - USER=homelab
      - TZ=Europe/Berlin
    command:
      - server
      - start
      - --insecure
      - --address=0.0.0.0:51515
      - --server-username=admin
      - --server-password=UI-Passwort-hier-aendern
    volumes:
      - ./config:/app/config
      - ./cache:/app/cache
      - ./logs:/app/logs
      - ./restore:/restore
      - /home/homelab:/data:ro
      - /mnt/backup/kopia:/repository

Zeile für Zeile, was hier Gewicht hat:

• image mit 0.23.1 statt latest. Das ist die aktuelle Version, und die Release-Notes beschreiben sie als Bugfix für eine seltene Race Condition, die zu Datenverlust führen kann. Bei einem Backup-Programm will ich wissen, welche Version läuft, und ein Update bewusst machen.
• hostname: homelab-server und USER=homelab. Kopia schreibt an jeden Snapshot, wer ihn gemacht hat, als benutzer@rechner. Ohne diese beiden Zeilen nimmt der Container seinen zufälligen Docker-Hostnamen, und der ist nach jedem Neubau ein anderer. Im Kopia-Forum beschreibt tiger2983 genau das: Nach jedem Update des Containers tauchten die alten Snapshots unter einem fremden Namen auf. Die Antwort von ChrisA war, den Hostnamen in der Compose-Datei festzuschreiben.
• KOPIA_PASSWORD ist das Tresor-Passwort. Das Docker-Image von Kopia ist so gebaut, dass es Zugangsdaten nicht in der Konfiguration speichert (im Dockerfile steht KOPIA_PERSIST_CREDENTIALS_ON_CONNECT=false). Deshalb liest Kopia das Passwort bei jedem Start aus dieser Variable. Merk dir das für Schritt 3: Das Passwort, das du dort im Browser eintippst, muss dasselbe sein wie hier.
• command startet Kopia als Server mit Web-Oberfläche. --insecure heißt: Die Oberfläche spricht HTTP ohne Verschlüsselung, und die Kommandozeilen-Referenz schreibt dazu, das sei nicht für den Produktivbetrieb gedacht. Im Heimnetz, wo Browser und Server im selben WLAN stehen, nehme ich das in Kauf; ins Internet gehört dieser Port nie. --server-username und --server-password sind der Login der Oberfläche. Seit Version 0.23.0 verweigert Kopia den Start, wenn ein Server ohne Passwort auf allen Adressen lauschen soll; mit Login ist das erlaubt.
• Das Beispiel der Doku enthält zusätzlich --disable-csrf-token-checks. Die Referenz führt das Flag als erweitert und warnt, es schalte eine Schutzprüfung ab. Ich lasse es weg; die Oberfläche läuft ohne.
• ./config, ./cache, ./logs: Konfiguration, Zwischenspeicher und Protokolle landen neben der Compose-Datei. Das Image erwartet sie genau dort, die Pfade stehen so im Dockerfile.
• /home/homelab:/data:ro ist die Quelle. Das :ro heißt nur lesen: Kopia kann deine Daten damit nicht einmal versehentlich verändern.
• /mnt/backup/kopia:/repository ist das Ziel, der Tresor auf der externen Platte. Und ./restore:/restore ist der Ordner, in den du in Schritt 5 Dateien zurückholst.

Ob die Datei lesbar ist, sagt dir Docker selbst. Kommt der aufgelöste Bauplan zurück, stimmt die Form. Kommt eine Fehlermeldung mit Zeilennummer, ist meist die Einrückung verrutscht.

docker compose config

Schritt 2: Container starten

Ein Befehl im Ordner ~/kopia. Docker holt das Image und startet Kopia im Hintergrund.

docker compose up -d
docker compose ps

In der Spalte STATUS steht Up. Das Protokoll ist beim ersten Start nicht leer, und eine Zeile darin wird dich irritieren: Kopia meldet, dass kein Repository verbunden ist. Das ist richtig so. Der Tresor existiert noch nicht, du legst ihn gleich im Browser an. Im Forum hat Matt dieselbe Meldung 2022 schon einmal einem verunsicherten Nutzer erklärt: Beim ersten Start ist das normal.

docker compose logs --tail 20

Schritt 3: Den Tresor anlegen

Jetzt der Browser. Die Oberfläche fragt zuerst nach dem Login aus der Compose-Datei, dann zeigt sie die Einrichtung, weil noch kein Repository verbunden ist.

Der Pfad ist /repository und nicht /mnt/backup/kopia, weil Kopia im Container lebt und die Platte dort unter diesem Namen eingehängt ist. Die Seite bietet unter Show Advanced Options noch die Wahl von Verschlüsselung und Hash-Algorithmus an; die Vorgabe ist AES-256-GCM, der Standard laut Doku, und ich würde sie nicht anfassen.

Nach dem Klick landest du im Reiter Snapshots mit einer leeren Tabelle. Klicke oben auf Repository, dann zeigt der Reiter die Zeile Connected To Repository, darunter Provider, Encryption Algorithm und Connected as mit root@homelab-server. Wenn dort ein anderer Rechnername steht, stimmt hostname in der Compose-Datei nicht. Auf der Platte ist der Tresor inzwischen auch sichtbar: Der Ordner enthält jetzt eine Handvoll Dateien mit Namen aus Buchstaben und Zahlen, darunter kopia.repository.

ls /mnt/backup/kopia

Das Tresor-Passwort kommt jetzt in den Passwort-Manager, zusammen mit einer Kopie der Datei ~/kopia/config/repository.config. Die Doku rät dazu, und der Grund ist der Satz vom Anfang: Wenn der Rechner mit Kopia abbrennt, brauchst du für die externe Platte nur Kopia, den Pfad und dieses Passwort. Ohne das Passwort ist die Platte Schrott, und das meine ich wörtlich.

Schritt 4: Die Policy, jede Nacht und was bleibt

Eine Policy ist der Plan für einen Ordner: wann Kopia ihn sichert und wie viele Stände es behält. Ohne Policy sichert Kopia nur, wenn du klickst. Die Doku beschreibt den Weg über den Reiter Policies, und so sieht er aus.

Die Zahlen sind mein Vorschlag für ein Homelab, und sie bedeuten: Die drei jüngsten Stände bleiben immer, dazu der letzte jedes Tages für eine Woche, der letzte jeder Woche für einen Monat, der letzte jedes Monats für ein halbes Jahr. Die Hilfetexte im Editor erklären jede Zeile genau so. Wenn dir am 20. auffällt, dass seit dem 3. eine Datei fehlt, findest du sie im Wochen-Snapshot. Zur Kompression sagt die Doku, es gebe keine Regel, die für alle passe, und zeigt einen Vergleich: zstd packt am kleinsten und braucht dafür länger. Bei einer nächtlichen Sicherung ist mir die Zeit egal, die Platte nicht.

Den ersten Snapshot löst du jetzt von Hand aus, damit du nicht bis drei Uhr nachts auf die Erfolgskontrolle wartest.

Je nach Datenmenge dauert das beim ersten Mal Minuten bis Stunden, weil jede Datei einmal gelesen, zerlegt und verschlüsselt wird. Der zweite Snapshot ist dann die Überraschung: Er dauert einen Bruchteil, weil Kopia nur noch anfasst, was sich geändert hat. Oben im Reiter Tasks siehst du jeden Lauf mit Dauer und Ergebnis. Steht dort ein Fehler, ist er fast immer eine Datei, die Kopia nicht lesen durfte; der Snapshot ist trotzdem da, nur ohne diese Datei, und der Tasks-Eintrag nennt sie.

Die Größe im Tresor kannst du von außen gegenprüfen, und dafür brauchst du sudo. Kopia läuft im Container als root, das stand eben schon bei Connected as, und es legt seine Ordner im Tresor so an, dass nur der Besitzer hineinsehen darf. Ohne sudo antwortet du deshalb mit einer Reihe von Permission denied und einer Zahl, die nur den Rest zählt. Mit sudo fragt dich das Terminal einmal nach deinem Passwort und zeigt dann die Größe. Die Zahl ist kleiner als dein Ordner, weil zstd und die Deduplizierung schon beim ersten Lauf arbeiten.

sudo du -sh /mnt/backup/kopia

Schritt 5: Die Rückholprobe

Hier trennt sich ein Backup von einer Hoffnung. Du holst eine Datei aus dem Snapshot zurück, und zwar nicht an ihren alten Platz, sondern in den Ordner restore, damit nichts überschrieben wird.

Auch hier gilt der Container-Pfad: /restore im Container ist ~/kopia/restore auf dem Rechner. Dort liegt der Ordner jetzt, und der Beleg ist ein Blick hinein.

ls ~/kopia/restore/probe

Steht dort kuma.db, hat der Kreis sich geschlossen: Datei rein, verschlüsselt auf der Platte, Datei wieder raus. Das ist der Moment, in dem ich ein Backup zum ersten Mal ernst nehme. Die Doku nennt noch einen Weg für Einzelfälle: Bei Destination einen Dateinamen mit .zip am Ende eintragen, dann landet der ganze Stand als Archiv in restore, das du auf einen anderen Rechner tragen kannst.

Den Knopf Mount as Local Filesystem daneben lässt du im Container in Ruhe. Er braucht FUSE, und das hat der Container nicht. Im Forum berichtet bk55, dass der Knopf unter Docker nur einen leeren Ordner erzeugt, jg4fun sah dazu die Meldung „fuse device not found“, und eine Lösung ohne Sonderrechte für den Container nennt der Thread nicht. Restore tut dasselbe, nur ohne Magie.

Was am Ende eingestellt ist

Kopia läuft, sichert nachts um drei und behält sechs Monate. Fünf Dinge gehören noch dazu, damit das auch in einem Jahr noch stimmt.

1. Der Tresor liegt auf der zweiten Platte, und das bleibt so. Die größte Falle steckt in einer Zeile der Compose-Datei: Ist /mnt/backup beim Start des Containers nicht eingehängt, legt Docker den Ordner /mnt/backup/kopia einfach auf der Systemplatte an, und Kopia sichert monatelang fröhlich dorthin. Der Prüfbefehl vom Anfang gehört deshalb nach jedem Neustart des Rechners wiederholt. Wer das nicht vergessen will, trägt die Platte in /etc/fstab ein, damit sie beim Hochfahren von selbst kommt; das ist eine eigene kleine Anleitung.

2. Die zweite Kopie außer Haus. Die 3-2-1-Regel will drei Kopien auf zwei Arten von Datenträgern, eine davon woanders. Kopia hilft dabei, weil ein zweites Repository nur ein zweiter Eintrag ist: SFTP, S3-kompatibler Speicher, Backblaze B2 und WebDAV stehen in der Liste der Speicherarten. Das Passwort ist dann ein anderes, und auch das gehört in den Manager. Der Beitrag hier endet bei der einen Platte; die zweite ist ein eigener.

3. Datenbanken brauchen einen Moment Ruhe. SQLite-Dateien wie die von Uptime Kuma oder Gitea sind im Snapshot meist brauchbar, aber „meist“ ist bei Backups ein schlechtes Wort. Zwei saubere Wege: Entweder ein Dump vor dem Snapshot, so wie ihn der Nextcloud-Backup-Beitrag zieht, in einen Ordner unter /home/homelab, dann sichert Kopia den Dump mit. Oder die Container für den Snapshot anhalten, was sich mit Kopia-Actions automatisieren lässt; die Doku beschreibt sie als Skripte vor und nach dem Snapshot, aus Sicherheitsgründen abgeschaltet, bis man in der repository.config den Wert enableActions auf true setzt. Das verdient einen eigenen Beitrag, hier nur der Hinweis, dass es geht.

4. Wartung und Prüfung. Kopia räumt von selbst auf: Die Doku nennt eine schnelle Wartung etwa stündlich und eine volle alle 24 Stunden, bei der gelöschte Snapshots wirklich Platz freigeben. Das darf nur der Besitzer des Repositorys, und der heißt root@homelab-server, ein weiterer Grund, warum diese beiden Namen in der Compose-Datei festgeschrieben sind. Die Wartung prüft die Struktur, aber nicht den Inhalt jeder Datei. Dafür empfiehlt die Doku einmal im Monat einen Befehl, der einen Teil der Dateien tatsächlich aus dem Tresor liest und entschlüsselt. Er läuft nur über die Kommandozeile, aus dem Container heraus.

docker compose exec kopia kopia snapshot verify --verify-files-percent=100 --file-parallelism=10

5. Updates mit Ansage. Die Version steht im Bauplan. Ein Update heißt: Release-Notes lesen, die Zahl ändern, dann die Befehle unten. Warum Lesen sich lohnt, zeigen die Notes zu 0.23.0: Dort wurde die Unterstützung für LZ4-Kompression entfernt, wer das nutzte, musste vorher umstellen.

cd ~/kopia
nano compose.yaml
docker compose up -d --force-recreate

Und was offen bleibt: Die Oberfläche spricht HTTP, und der Kopia-Server hält den Schlüssel zum Tresor im Speicher. Issue #4772 auf GitHub diskutiert genau das: Wer den Rechner übernimmt, auf dem Kopia läuft, liest die Backups mit. Die externe Platte allein bleibt trotzdem wertlos. Es heißt nur, dass Port 51515 im Heimnetz bleibt und der Rechner selbst gepflegt sein will.

Wo es klemmt

Nach einem Neustart fragt die Oberfläche wieder nach einem Passwort oder zeigt die Einrichtung. Dann stimmt KOPIA_PASSWORD in der Compose-Datei nicht mit dem Passwort überein, das du in Schritt 3 eingetippt hast. Das Image speichert das Passwort nicht, also braucht es die Variable bei jedem Start. In der Compose-Datei korrigieren, dann docker compose up -d. Hast du dich in Schritt 3 vertippt und weißt das Passwort noch, lässt es sich laut FAQ nur ändern, solange das Repository verbunden ist.

Die Snapshots sind nach einem Umbau weg, aber der Tresor ist voll. Sie sind nicht weg, sie gehören einem anderen Namen. Das passiert, wenn hostname oder USER sich geändert haben; dann listet der Reiter Snapshots nur die Stände des neuen Namens. Das Dropdown über der Tabelle auf All Snapshots stellen, dann erscheinen die alten wieder. Und die Compose-Datei auf die alten Werte zurückstellen.

„repository is not connected“ im Protokoll. Vor Schritt 3 normal. Danach heißt es meist, dass /mnt/backup/kopia beim Start leer oder nicht erreichbar war, etwa weil die Platte nicht eingehängt ist. Platte prüfen, dann docker compose restart.

Benannte Volumes mitsichern

Alle Anleitungen hier legen die Daten als Ordner neben die Compose-Datei, deshalb reicht /home/homelab als Quelle. Wenn ein Dienst stattdessen ein benanntes Volume nutzt, liegt es laut Docker-Doku unter /var/lib/docker/volumes/<name>/_data. In ~/kopia/compose.yaml im Abschnitt volumes des Dienstes kopia kommt dann diese eine Zeile dazu, danach docker compose up -d und eine zweite Policy für /volumes, genau wie in Schritt 4.

      - /var/lib/docker/volumes:/volumes:ro

Welche Volumes es auf deinem Rechner überhaupt gibt, zeigt ein Befehl. Ist die Liste leer, brauchst du die Zeile nicht.

docker volume ls

Warum Kopia

Ich würde Kopia nehmen, weil es drei Dinge zugleich tut, die eine Ordnerkopie nicht kann: verschlüsseln, mehrere Stände behalten und dabei Platz sparen. Und weil die Oberfläche die Rückholprobe zu einem Klick macht; ein Backup, dessen Restore eine Kommandozeilen-Expedition ist, wird im Ernstfall zur Expedition mit zitternden Händen. Dass das Projekt in den Release-Notes eine seltene Race Condition mit möglichem Datenverlust beim Namen nennt und behebt, statt sie in einem „various fixes“ zu verstecken, zählt für mich auch.

Nach 45 Minuten hast du etwas, das die meisten Homelabs nicht haben: einen Beweis, dass die Daten zurückkommen. Die Platte außer Haus und die Datenbank-Dumps sind die nächsten beiden Schritte, und beide sind kleiner als der, den du gerade gemacht hast.

Wohin geht bei dir die zweite Kopie: NAS beim Bruder, Hetzner-Box, Backblaze, oder liegt die USB-Platte noch neben dem Server? Und hast du schon einmal wirklich etwas aus einem Backup zurückgeholt? Schreib's in die Kommentare.

Wenn Kopia nachts läuft, lohnt sich ein Wächter, der meldet, wenn der Rechner selbst nicht mehr antwortet: Uptime Kuma war hier die erste Anleitung, und sein Ordner data ist ab heute mit im Tresor.

Quellen

• Kopia-Doku: Installation (Docker-Image, Compose-Beispiel, Umgebungsvariablen)
• Dockerfile des Kopia-Images (KOPIA_CONFIG_PATH, KOPIA_PERSIST_CREDENTIALS_ON_CONNECT)
• Kopia-Doku: Getting Started (Repository, Policies, Snapshots, Restore)
• Kopia-Doku: Features (Verschlüsselung, Deduplizierung, Kompression, Speicherziele)
• Kopia-Doku: Encryption (AES-256-GCM, scrypt)
• Kopia-Doku: Compression
• Kopia-Doku: Maintenance
• Kopia-Doku: Ensuring Backup Consistency (snapshot verify)
• Kopia-Doku: Actions
• Kopia-Doku: FAQ (Passwort ändern)
• Kopia-Referenz: server start (Flags)
• Release v0.23.1 und Release v0.23.0 (Loopback-Beschränkung, LZ4 entfernt)
• Pull Request #5354: restrict insecure unauthenticated server to loopback binds
• Issue #4772: Kopia server is insecure
• Quellcode der Kopia-Web-Oberfläche (Beschriftungen der Seiten und des Policy-Editors)
• Kopia-Forum: Change repository hostname?
• Kopia-Forum: How to install/configure via Docker
• Kopia-Forum: Docker kopia server mount issue
• Docker-Doku: Volumes (Speicherort benannter Volumes)