AmberShelf auf Linux mit Docker installieren

AmberShelf spiegelt eine Master-Platte auf eine oder mehrere Sicherungsplatten und löscht oder überschreibt nichts ohne deine Freigabe. Am Ende dieser Anleitung läuft die Weboberfläche auf deinem Linux-Rechner, du bist angemeldet und kannst Platten registrieren.

Zuerst prüfen: Läuft das auf deinem Rechner?

AmberShelf besteht aus zwei Teilen. Ein kleiner Helfer läuft als systemd-Dienst mit Root-Rechten auf dem Rechner selbst, erkennt Platten und hängt sie ein. Der eigentliche Container hat keine Sonderrechte und spricht über einen Socket mit dem Helfer. Deshalb reicht ein einfaches docker compose up nicht: Du brauchst einen Linux-Rechner mit systemd, auf dem du Root-Rechte hast und an den die Platten direkt angesteckt werden.

Für Unraid, Synology, UGREEN und macOS ist diese Anleitung nicht gedacht, denn der Helfer braucht systemd und direkten Zugriff auf die Blockgeräte des Docker-Hosts. Netzfreigaben (SMB, NFS) funktionieren derzeit nicht, weil AmberShelf Platten über Dateisystem-UUID und Seriennummer erkennt. Für macOS und Windows gibt es stattdessen Desktop-Apps zum Herunterladen auf der Release-Seite.

Die Befehle unten gelten für Ubuntu und Debian. Auf anderen Linux-Distributionen brauchst du dieselben Pakete, nur mit dem Paketmanager deiner Distribution.

Vorbereitung

Terminal öffnen

Alle Befehle gibst du in einem Terminal auf dem Linux-Rechner ein, entweder direkt am Gerät oder per SSH. Jeder Befehl wird mit der Eingabetaste abgeschickt. Bei sudo fragt das System nach deinem Passwort; beim Tippen erscheinen keine Zeichen, das ist normal.

Docker installieren

Wenn docker compose version bei dir bereits eine Versionsnummer zeigt, überspringe diesen Abschnitt und mach bei „Programmdateien herunterladen“ weiter. Andernfalls installierst du Docker aus dem offiziellen Paket-Repository von Docker. Die Schritte unterscheiden sich für Ubuntu und Debian nur in den Adressen.

1. Entferne mögliche Konfliktpakete. Die Meldung, dass keines davon installiert ist, ist in Ordnung.

sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)

Das Ergebnis ist entweder eine Liste entfernter Pakete oder die Meldung, dass nichts zu entfernen war.

2. Installiere die Hilfspakete für das Repository und lege den Schlüsselordner an.

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

Repository auf Ubuntu eintragen

3. Lade den Schlüssel von Docker herunter und mache ihn lesbar.
4. Trage das Repository ein. Kopiere dazu den ganzen Block bis einschließlich der Zeile EOF.
5. Lies die Paketlisten neu ein.

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

Repository auf Debian eintragen

Auf Debian gehst du genauso vor, nur mit anderen Adressen. Bei Debian-Ableitungen oder testing trägst du statt des Ausdrucks hinter Suites: den Codenamen deiner Version ein, zum Beispiel trixie.

sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

Docker und Compose installieren

6. Installiere Docker samt Compose-Plugin.
7. Prüfe, dass Docker läuft.

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo docker run hello-world

Docker lädt ein kleines Testimage und gibt eine Begrüßung aus („Hello from Docker!“). Unter Debian und Ubuntu startet der Dienst bei jedem Systemstart automatisch.

8. Nimm deinen Benutzer in die Gruppe docker auf, damit du nicht jedes Mal sudo brauchst.
9. Melde dich ab und wieder an, damit die Gruppe gilt (bei einer SSH-Sitzung: Verbindung trennen und neu verbinden).
10. Prüfe, dass Compose ohne sudo antwortet.

sudo usermod -aG docker $USER

docker compose version

Die Ausgabe nennt eine Version. Die Gruppe docker gibt Root-nahe Rechte, nimm also nur Benutzer auf, denen du das zutraust. Der Befehl heißt docker compose mit Leerzeichen, nicht docker-compose.

AmberShelf herunterladen

Die Dateien holst du mit git. Der Helfer-Installer liegt im Repository, deshalb brauchst du den Quellcode auf dem Rechner. Ein Ordner ambershelf entsteht dabei im aktuellen Verzeichnis, normalerweise deinem Home-Ordner.

1. Installiere git, falls es fehlt.
2. Lade das Repository herunter.
3. Wechsle in den neuen Ordner.
4. Lege den Datenordner selbst an. Er speichert die Datenbank mit Prüfsummen und Entscheidungen.

sudo apt install git

git clone https://github.com/sphings79/ambershelf.git

cd ambershelf

mkdir -p data

Den Datenordner legst du als normaler Benutzer an, damit er dir gehört. Der Container läuft mit der Benutzerkennung 1000 und muss dort schreiben dürfen; auf Ubuntu und Debian hat der erste angelegte Benutzer diese Kennung.

Installation

Helfer installieren

Das Skript prüft die Voraussetzungen, legt die Systemgruppe ambershelf und die Ordner /etc/ambershelf, /mnt/ambershelf und /run/ambershelf an, installiert den Helfer samt systemd-Dienst und startet ihn. Außerdem trägt es die Nummer der Gruppe in die Datei .env im AmberShelf-Ordner ein. Ohne diesen Eintrag weigert sich Compose zu starten.

1. Starte das Installationsskript im Ordner ambershelf. Es braucht Root-Rechte.
2. Optional: Installiere smartmontools, damit AmberShelf den Zustand der Platten (SMART) anzeigen kann.
3. Optional: Installiere exfatprogs, falls du einen unsauber getrennten exFAT-Datenträger reparieren können willst.

sudo docker/install.sh

sudo apt install smartmontools

sudo apt install exfatprogs

Die Ausgabe des Skripts endet mit „helper is running“ und dem Hinweis, als Nächstes docker compose up -d auszuführen. Warnungen wie „no exfat driver found“ bedeuten, dass der Kernel dieses Dateisystem nicht kennt; Platten damit lassen sich dann nicht einhängen. Verlangt werden exfat ab Kernel 5.7 und ntfs3 ab Kernel 5.15.

Container starten

4. Starte AmberShelf im Hintergrund. Der erste Start baut das Image aus dem Quellcode und dauert deshalb einige Minuten.
5. Prüfe, ob der Container läuft.

docker compose up -d

docker compose ps

Die Liste zeigt den Container ambershelf mit dem Status „Up“. Wer nicht selbst bauen möchte, kann in compose.yaml die drei build-Zeilen auskommentieren und bei image: den Wert ghcr.io/sphings79/ambershelf:latest eintragen; dieses fertige Image gibt es für linux/amd64 und linux/arm64.

Einrichtung

Erstes Passwort holen

AmberShelf hat bewusst keinen Einrichtungsbildschirm. Beim ersten Start erzeugt es ein Passwort und schreibt es ins Protokoll des Containers.

1. Lies das Passwort aus dem Protokoll.

docker compose logs ambershelf | grep -A4 "first start"

In der Ausgabe steht unter der Zeile mit „first start“ das erzeugte Passwort. Kopiere es.

Oberfläche öffnen

Die Oberfläche hört nur auf 127.0.0.1:8088, ist also nur auf dem Rechner selbst erreichbar. Das ist Absicht, denn der Container gehört nicht ungeschützt ins Netz.

2. Sitzt du direkt am Linux-Rechner, öffne in dessen Browser die Adresse http://127.0.0.1:8088.
3. Arbeitest du von einem anderen Rechner aus, öffne dort ein Terminal und baue einen SSH-Tunnel auf. Ersetze BENUTZER durch deinen Benutzernamen auf dem Linux-Rechner und SERVER-IP durch dessen Adresse.
4. Lass das Terminal offen und öffne im Browser des anderen Rechners http://127.0.0.1:8088.

ssh -L 8088:127.0.0.1:8088 BENUTZER@SERVER-IP

Es erscheint die Anmeldeseite von AmberShelf. Für einen dauerhaften Zugriff im Heimnetz gibt es im Repository die Vorlage docs/compose.override.example.yaml für den Betrieb hinter einem Reverse Proxy; beschränke ihn auf dein eigenes Netz.

Anmelden und eigenes Passwort setzen

5. Melde dich mit dem Passwort aus dem Protokoll an.
6. Vergib ein eigenes Passwort. Vorher geht in AmberShelf nichts anderes.

Danach öffnet sich die Übersicht. Nach fünf Fehlversuchen von derselben Adresse sperrt AmberShelf die Anmeldung für eine Weile.

Platten registrieren

Ein Auftrag besteht aus einem Master, der gelesen wird, und Kopien, die beschrieben werden. Eine Platte ist entweder Master oder Kopie, nie beides. Der Master wird vom Kernel nur lesend eingehängt.

7. Stecke die erste Platte an den Rechner und öffne in AmberShelf den Bereich „Platten“.
8. Benenne die Platte und wähle ihre Rolle. Beginne mit dem Master.
9. Registriere die Platte. Der erste Master eröffnet einen Auftrag.
10. Stecke die Sicherungsplatte an und registriere sie auf demselben Weg mit der Rolle Kopie.
11. Öffne die „Übersicht“ und hänge den Auftrag ein.
12. Lies jede Platte ein. Der erste Lauf bildet Prüfsummen über alle Dateien und dauert je nach Plattengröße viele Stunden; er lässt sich anhalten und fortsetzen.

Nach dem Einlesen zeigt die Übersicht Master und Kopien mit ihrem Verzeichnisstand. Je Auftrag legst du außerdem die Sync-Art fest: Entweder trägt jede Kopie den vollständigen Bestand, oder die Kopien teilen ihn sich, dann teilst du Ordner den Kopien zu.

Kontrolle

1. Öffne die „Vorschau“ und vergleiche. AmberShelf zeigt dort, was passieren würde, und führt nichts aus, bevor du entschieden hast.
2. Gib Änderungen frei, wenn sie stimmen. Neue Dateien kopiert AmberShelf von selbst, Ersetzen, Umbenennen und Löschen brauchen deine Freigabe: freigeben, diesmal übergehen oder nie wieder fragen.

Gelöschte und ersetzte Dateien landen nicht im Nichts, sondern im Ordner .ambershelf-trash auf der Kopie. Der Zustand des Hintergrunddienstes lässt sich jederzeit prüfen:

systemctl status ambershelf-helper

Die Ausgabe zeigt „active (running)“. Die Platten auf dem Rechner erscheinen unter /mnt/ambershelf.

Wenn etwas nicht klappt

Compose bricht mit einer Meldung zu „install.sh“ ab

In der .env-Datei fehlt AMBERSHELF_GID. Führe sudo docker/install.sh im Ordner ambershelf aus und starte danach docker compose up -d im selben Ordner erneut.

Die Seite ist von einem anderen Rechner nicht erreichbar

Das ist Absicht, die Oberfläche hört nur auf 127.0.0.1. Nutze den SSH-Tunnel aus dem Abschnitt „Oberfläche öffnen“.

Ich finde das erste Passwort nicht mehr

Wiederhole docker compose logs ambershelf | grep -A4 "first start" im Ordner ambershelf. Hast du bereits ein eigenes Passwort vergeben, gilt nur noch dieses.

Der Container schreibt nicht in den Datenordner

Der Container läuft mit der Benutzerkennung 1000. Prüfe mit id -u, welche Kennung dein Benutzer hat. Gehört data einem anderen Benutzer, setze die Besitzer mit sudo chown 1000:1000 data und starte neu mit docker compose up -d.

Eine Platte lässt sich nicht einhängen

Prüfe, ob der Installer beim Dateisystem eine Warnung ausgegeben hat. exfat braucht Kernel 5.7 oder neuer, ntfs3 Kernel 5.15 oder neuer. Läuft der Helfer nicht, starte ihn mit sudo systemctl restart ambershelf-helper und sieh in den Meldungen mit journalctl -u ambershelf-helper nach.

Eine Netzfreigabe soll als Master oder Kopie dienen

Das geht derzeit nicht. AmberShelf braucht direkt am Rechner angeschlossene Platten, die es über Dateisystem-UUID und Seriennummer erkennt.