Zum Inhalt springen
SONOYA.com
Raspberry Pi & Linux

Docker auf dem Raspberry Pi installieren und nutzen

Docker und Docker Compose auf dem Raspberry Pi sauber aus dem offiziellen Repository installieren, ersten Stack mit Uptime Kuma starten und Fehler lösen.

Von

  • 6 Min. Lesezeit
Docker-Wal-Symbol auf farbigem Verlauf für die Installation von Docker und Docker Compose auf einem Raspberry Pi

Ein Raspberry Pi mit Docker ist der einfachste Einstieg ins Selfhosting: Pi-hole, Uptime Kuma, Vaultwarden, Nextcloud oder Home-Assistant-Helfer laufen dann jeweils in einem eigenen Container und lassen sich mit einem Befehl starten, aktualisieren und wieder entfernen. Viele Anleitungen im Netz arbeiten dafür noch mit Skripten aus dem Internet, die direkt in die Shell gepipt werden, oder mit dem veralteten Paket docker.io aus den Debian-Quellen.

Diese Anleitung geht den Weg, den Docker selbst für 64-Bit-Systeme empfiehlt: Installation aus dem offiziellen Docker-Repository für Debian, auf dem Raspberry Pi OS aufbaut. Danach startest Du einen ersten Stack mit Docker Compose und lernst die typischen Stolpersteine kennen. Getestet habe ich die Installationsbefehle in einem Debian-13-Container („Trixie“) auf arm64, also derselben Basis und Architektur wie Raspberry Pi OS auf dem Pi 5. Installiert wurden dabei Docker 29.9.3 und Docker Compose 5.7.1.

Voraussetzung: ein 64-Bit-System

Docker baut ab Version 29 keine Pakete mehr für das 32-Bit-Raspberry-Pi-OS. Du brauchst deshalb die 64-Bit-Version von Raspberry Pi OS, die auf dem Pi 3, Pi 4, Pi 5 und dem Zero 2 W läuft. Ob Dein System passt, prüfst Du per SSH mit:

Code
uname -m

Steht dort aarch64, bist Du richtig. Bei armv7l läuft ein 32-Bit-System, dann spielst Du Raspberry Pi OS (64-bit) mit dem Raspberry Pi Imager neu auf. Ältere Modelle wie der Pi 1 oder der erste Zero werden von Docker gar nicht unterstützt.

Für einen Pi, der dauerhaft Container laufen lässt, empfehle ich einen Raspberry Pi 5 mit 8 GB (Affiliate Link). Wenn Du nur ein, zwei leichte Dienste betreiben willst, reicht auch ein gebrauchter Raspberry Pi 4 (Affiliate Link). Bring das System vor der Installation auf den aktuellen Stand:

Code
sudo apt update
sudo apt full-upgrade -y

Docker aus dem offiziellen Repository installieren

Zuerst räumen wir eventuell vorhandene inoffizielle Pakete weg, die mit Docker kollidieren würden. Auf einem frischen System meldet apt hier nur, dass nichts davon installiert ist. Das ist in Ordnung.

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

Jetzt holen wir den Signaturschlüssel von Docker. Mit ihm prüft apt später, dass die Pakete wirklich von Docker stammen.

Code
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
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

Als Nächstes tragen wir das Repository als Paketquelle ein. Der Befehl liest den Codenamen Deines Systems (bei aktuellem Raspberry Pi OS trixie) und die Architektur (arm64) selbst aus, Du kannst ihn also unverändert kopieren:

Code
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

Die Ausgabe zeigt Dir den fertigen Inhalt der Datei. Prüf dort kurz, dass bei Suites wirklich trixie oder bookworm steht und bei Architectures der Wert arm64. Dann installieren wir Docker mit allen Bestandteilen, also der Engine, dem Kommandozeilenprogramm, containerd sowie den Plugins für Buildx und Compose:

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

Unter Debian und Raspberry Pi OS startet Docker danach automatisch und auch bei jedem Neustart. Ob alles geklappt hat, siehst Du mit:

Code
sudo docker run hello-world

Docker lädt dabei ein winziges Test-Image herunter und startet es. Erscheint „Hello from Docker!“, läuft die Installation.

Docker ohne sudo: die Gruppe docker

Damit Du nicht vor jeden Befehl sudo schreiben musst, nimmst Du Deinen Benutzer in die Gruppe docker auf. Die Gruppe legt das Paket bei der Installation selbst an.

Code
sudo usermod -aG docker $USER

Die neue Gruppe gilt erst nach einer neuen Anmeldung. Melde Dich also per exit ab und per SSH wieder an, danach funktioniert docker run hello-world ohne sudo.

Du solltest wissen, was Du damit tust: Laut Docker verleiht die Gruppe docker Rechte auf Root-Niveau. Wer Mitglied ist, kann über einen Container das ganze System verändern. Auf einem Pi, an dem nur Du arbeitest, ist das üblich und vertretbar. Nimm aber keine weiteren Benutzer in diese Gruppe auf, denen Du keinen Root-Zugang geben würdest.

Der erste Stack mit Docker Compose

Einzelne docker run-Befehle mit langen Parametern sind schnell vergessen. Mit Docker Compose beschreibst Du einen Dienst stattdessen in einer Datei und startest ihn mit einem kurzen Befehl. Als Beispiel nehmen wir Uptime Kuma, ein schlankes Werkzeug, das Deine Websites und Dienste überwacht.

Leg einen Ordner für den Stack an und wechsle hinein:

Code
mkdir -p ~/docker/uptime-kuma
cd ~/docker/uptime-kuma

Öffne mit nano compose.yaml eine neue Datei und füge diesen Inhalt ein:

Code
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

Speichere mit Strg + O, bestätige mit Enter und schließe den Editor mit Strg + X. Die Datei sagt Docker: Nimm das Image von Uptime Kuma in Version 2, starte es nach einem Neustart des Pi automatisch wieder, mach Port 3001 im Heimnetz erreichbar und speichere alle Daten im Unterordner data, damit sie ein Update des Containers überleben.

Jetzt startest Du den Stack im Hintergrund:

Code
docker compose up -d

Nach rund 20 Sekunden zeigt docker compose ps den Container mit dem Status Up und dem Zusatz (healthy). Öffne dann im Browser http://IP-DES-PI:3001 und ersetze IP-DES-PI durch die Adresse Deines Pi, die Du mit hostname -I herausfindest. Uptime Kuma begrüßt Dich mit der Einrichtung des Admin-Kontos. Ich habe genau diese Compose-Datei auf arm64 getestet, der Container lief nach 20 Sekunden und meldete sich als gesund.

Wenn Du Compose genauer verstehen willst, etwa wie Volumes, Netzwerke und .env-Dateien zusammenspielen, lies Docker Compose verstehen: Volumes, Netzwerke und .env.

Images für arm64: worauf Du achten musst

Der Raspberry Pi hat einen ARM-Prozessor, die meisten Server dagegen x86. Ein Image läuft auf dem Pi nur, wenn es eine Variante für arm64 (auch aarch64 genannt) gibt. Die großen Projekte wie Uptime Kuma, Pi-hole, Nextcloud oder Vaultwarden bauen das inzwischen alle mit. Auf Docker Hub siehst Du es unter dem Reiter „Tags“ in der Spalte „OS/ARCH“: Dort muss linux/arm64 stehen.

Fehlt die Variante, bricht der Start mit dieser Meldung ab:

Code
no matching manifest for linux/arm64/v8 in the manifest list entries

Dann hilft kein Trick, sondern nur ein anderes Image oder ein Rechner mit x86-Prozessor.

Docker-Daten auf die SSD legen

Docker schreibt Images, Container und Volumes nach /var/lib/docker. Auf einer microSD-Karte führt das dauerhafte Schreiben früher oder später zu Ausfällen, und die Karte ist außerdem langsam. Für einen Pi, der ernsthaft Container betreibt, lohnt sich deshalb eine NVMe-SSD im Format 2230 (Affiliate Link) mit passendem Adapter. Am einfachsten ist es, gleich das ganze System von der SSD zu starten. Dann liegt auch /var/lib/docker automatisch dort, und Du musst nichts umkonfigurieren. Wie das geht, steht in Raspberry Pi 5 von NVMe-SSD booten statt microSD-Karte.

Speicherplatz im Blick behalten und aufräumen

Mit jedem Update bleiben alte Image-Versionen liegen. Wie viel Platz Docker belegt, zeigt Dir:

Code
docker system df

Die Spalte RECLAIMABLE sagt, wie viel Du freigeben kannst. Ungenutzte Images entfernst Du mit:

Code
docker image prune -a

Der Befehl fragt vor dem Löschen nach und entfernt nur Images, die kein Container mehr benutzt. Laufende Dienste und Deine Volumes bleiben unberührt. Wie Du Container regelmäßig und kontrolliert aktualisierst, zeigt Docker-Container aktualisieren: Diun statt Watchtower.

Häufige Fehler

permission denied while trying to connect to the docker API: Dein Benutzer ist noch nicht in der Gruppe docker, oder Du hast Dich nach dem usermod noch nicht neu angemeldet. Mit groups siehst Du, ob docker in der Liste steht. Wenn nicht, melde Dich ab und wieder an.

docker: 'compose' is not a docker command: Das Compose-Plugin fehlt. Installiere es mit sudo apt install docker-compose-plugin nach. Der alte Befehl docker-compose mit Bindestrich gehört zu einer eingestellten Version und wird nicht mehr gebraucht.

E: Package 'docker-ce' has no installation candidate: Die Paketquelle stimmt nicht. Schau mit cat /etc/apt/sources.list.d/docker.sources nach, ob dort arm64 und ein gültiger Codename stehen. Steht dort armhf, läuft ein 32-Bit-System, das Docker für Raspberry Pi OS seit Version 29 nicht mehr unterstützt. Spiel dann die 64-Bit-Version auf.

Port bereits belegt: Meldet Compose address already in use, nutzt ein anderer Dienst den Port schon. Ändere in der compose.yaml die linke Zahl, zum Beispiel "3002:3001", und ruf die Seite dann über Port 3002 auf.

Wenn Deine Dienste später auch von außen oder per HTTPS erreichbar sein sollen, geht es mit Reverse Proxy mit Caddy: HTTPS für Dienste im Heimnetz weiter.

Artikel teilen

Weiterlesen.