Anleitung: Docker-Installation auf einem Raspberry Pi 5

Mit Docker kannst du Anwendungen auf dem Raspberry Pi 5 in Containern betreiben. Das ist besonders praktisch für Dienste wie Webserver, Datenbanken, Home Assistant, Pi-hole, Portainer oder eigene kleine Serverprojekte.

Ziel dieser Anleitung: Du installierst Docker Engine auf einem Raspberry Pi 5 mit Raspberry Pi OS 64-bit, richtest den Docker-Dienst ein, aktivierst den Benutzerzugriff ohne ständiges sudo und prüfst die Installation mit einem Testcontainer.

1. Voraussetzungen prüfen

Für einen Raspberry Pi 5 wird Raspberry Pi OS 64-bit empfohlen. Docker unterstützt auf modernen Raspberry-Pi-Systemen besonders gut die Architektur arm64.

Systemarchitektur anzeigen

uname -m

Die Ausgabe sollte idealerweise so aussehen:

aarch64

Ausgabe	Bedeutung
`aarch64`	64-bit ARM-System, empfohlen für Raspberry Pi 5
`armv7l`	32-bit ARM-System, für neue Docker-Versionen weniger empfehlenswert

Wichtig: Für den Raspberry Pi 5 solltest du nach Möglichkeit Raspberry Pi OS 64-bit verwenden. Bei 32-bit-Systemen kann es je nach Docker-Version Einschränkungen geben.

2. System aktualisieren

Bevor Docker installiert wird, sollte das Betriebssystem aktualisiert werden. So vermeidest du Paketkonflikte und startest mit einem sauberen Fundament.

sudo apt update
sudo apt upgrade -y

Falls während der Aktualisierung ein Neustart empfohlen wird, führe ihn aus:

sudo reboot

Nach dem Neustart wieder per Terminal oder SSH verbinden.

3. Alte Docker-Pakete entfernen

Falls bereits ältere oder inoffizielle Docker-Pakete installiert wurden, sollten diese vorher entfernt werden. Das betrifft zum Beispiel docker.io oder alte Compose-Pakete.

sudo apt remove -y docker.io docker-compose docker-doc podman-docker containerd runc

Hinweis: Wenn das System meldet, dass einige Pakete nicht installiert sind, ist das normal. Dann gibt es einfach nichts zu entfernen.

4. Benötigte Pakete installieren

Docker wird über ein offizielles Paket-Repository installiert. Dafür werden zuerst einige Hilfsprogramme benötigt.

sudo apt install -y ca-certificates curl gnupg

Danach wird der Ordner für Schlüsseldateien angelegt:

sudo install -m 0755 -d /etc/apt/keyrings

5. Docker-Schlüssel hinzufügen

Damit dein Raspberry Pi die Docker-Pakete überprüfen kann, wird der offizielle GPG-Schlüssel von Docker gespeichert.

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Die Berechtigungen für die Schlüsseldatei setzen:

sudo chmod a+r /etc/apt/keyrings/docker.gpg

6. Docker-Repository einrichten

Nun wird die Paketquelle von Docker eingetragen. Auf Raspberry Pi OS 64-bit basiert das System in der Regel auf Debian, deshalb wird das Debian-Repository von Docker verwendet.

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Danach die Paketliste erneut aktualisieren:

sudo apt update

Wichtig: Wenn hier ein Fehler zur Debian-Version erscheint, prüfe mit cat /etc/os-release, ob dein System wirklich auf einer unterstützten Raspberry-Pi-OS- oder Debian-Version basiert.

7. Docker Engine installieren

Jetzt werden Docker Engine, Docker CLI, Containerd, Buildx und das Docker-Compose-Plugin installiert.

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

Paket	Funktion
`docker-ce`	Docker Engine
`docker-ce-cli`	Docker-Befehle im Terminal
`containerd.io`	Container-Laufzeitumgebung
`docker-buildx-plugin`	Erweiterte Build-Funktionen
`docker-compose-plugin`	Docker Compose als moderner Befehl `docker compose`

8. Docker-Dienst prüfen

Nach der Installation sollte Docker automatisch gestartet sein. Prüfe den Dienst mit:

sudo systemctl status docker

Wenn Docker aktiv ist, erkennst du eine Zeile ähnlich dieser:

Active: active (running)

Falls Docker nicht läuft, kannst du den Dienst manuell starten:

sudo systemctl start docker

Damit Docker nach einem Neustart automatisch startet:

sudo systemctl enable docker

9. Docker-Testcontainer ausführen

Mit dem folgenden Befehl wird ein kleiner Testcontainer gestartet. Docker lädt dabei ein Test-Image herunter und führt es aus.

sudo docker run hello-world

Wenn alles funktioniert, erscheint eine Erfolgsmeldung von Docker.

Erfolg: Wenn hello-world ohne Fehlermeldung läuft, ist Docker korrekt installiert.

10. Docker ohne sudo verwenden

Standardmäßig benötigt Docker Administratorrechte. Damit dein Benutzer Docker-Befehle ohne sudo ausführen kann, wird er zur Gruppe docker hinzugefügt.

sudo usermod -aG docker $USER

Danach einmal abmelden und wieder anmelden oder den Raspberry Pi neu starten:

sudo reboot

Nach dem Neustart kannst du Docker ohne sudo testen:

docker run hello-world

Sicherheitshinweis: Benutzer in der Gruppe docker haben weitreichende Rechte auf dem System. Füge daher nur vertrauenswürdige Benutzer dieser Gruppe hinzu.

11. Docker Compose prüfen

Docker Compose wird heute normalerweise als Plugin verwendet. Der Befehl lautet daher nicht mehr zwingend docker-compose, sondern:

docker compose version

Eine gültige Ausgabe sieht zum Beispiel so aus:

Docker Compose version v2.x.x

Hinweis: Der alte Befehl docker-compose mit Bindestrich gehört zur älteren Compose-Variante. Bei neuen Installationen ist docker compose ohne Bindestrich die richtige Wahl.

12. Nützliche Docker-Befehle

Befehl	Beschreibung
`docker ps`	Zeigt laufende Container an
`docker ps -a`	Zeigt alle Container an, auch gestoppte
`docker images`	Zeigt heruntergeladene Images an
`docker stop NAME`	Stoppt einen Container
`docker start NAME`	Startet einen vorhandenen Container
`docker rm NAME`	Löscht einen gestoppten Container
`docker rmi IMAGE`	Löscht ein Image
`docker logs NAME`	Zeigt die Protokolle eines Containers an

13. Beispiel: Ersten Webserver-Container starten

Zum Test kannst du einen kleinen Nginx-Webserver starten. Dieser Container stellt eine Webseite auf Port 8080 bereit.

docker run -d \
  --name test-nginx \
  -p 8080:80 \
  --restart unless-stopped \
  nginx:latest

Danach kannst du im Browser die IP-Adresse deines Raspberry Pi mit Port 8080 öffnen:

http://IP-DES-RASPBERRY-PI:8080

Die IP-Adresse kannst du mit folgendem Befehl anzeigen:

hostname -I

Wenn du den Testcontainer wieder entfernen möchtest:

docker stop test-nginx
docker rm test-nginx

14. Docker aktualisieren

Docker wird nach der Einrichtung des offiziellen Repositorys über die normale Paketverwaltung aktualisiert.

sudo apt update
sudo apt upgrade -y

Danach kannst du die installierte Docker-Version prüfen:

docker --version
docker compose version

15. Häufige Fehler

permission denied: Benutzer ist noch nicht in der Gruppe docker oder die Sitzung wurde noch nicht neu gestartet.
Unable to locate package docker-ce: Docker-Repository wurde nicht korrekt eingerichtet oder sudo apt update wurde vergessen.
Cannot connect to the Docker daemon: Docker-Dienst läuft nicht oder wurde nicht gestartet.
Container ist nicht erreichbar: Portfreigabe mit -p prüfen und sicherstellen, dass die richtige IP-Adresse verwendet wird.
Falsche Architektur: Bei Raspberry Pi 5 möglichst Raspberry Pi OS 64-bit verwenden.

16. Fazit

Docker ist nun auf dem Raspberry Pi 5 installiert und einsatzbereit. Du kannst jetzt Container starten, Dienste dauerhaft betreiben und später komplexere Anwendungen mit docker compose verwalten. Damit wird der Raspberry Pi 5 zu einem kleinen Container-Server für dein Heimnetz oder Labor.