Portainer installieren: Debian 13 und Ubuntu 24.04 mit Docker

Kurz gesagt: Installiere Docker Engine samt Compose-Plugin aus dem offiziellen apt-Repository von Docker, lade die offizielle compose.yaml von Portainer herunter und starte sie mit docker compose up -d. Danach öffnest du https://<HOST-IP>:9443, holst den Setup-Token aus dem Container-Log und legst innerhalb von fünf Minuten ein Admin-Konto mit mindestens 12 Zeichen langem Passwort an. Port 8000 brauchst du nur für Edge Agents.

Diese Anleitung richtet sich an alle, die auf einem frischen Debian-13- oder Ubuntu-24.04-Server eine Weboberfläche für Docker haben wollen. Sie zeigt den kompletten Weg vom leeren System bis zum ersten Login und erklärt unterwegs, an welchen Stellen du bewusst entscheiden solltest, statt Befehle nur abzuschreiben. Was Portainer ist und wann es sich lohnt, steht in Was ist Portainer?.

Voraussetzungen #

• Ein Server oder eine VM mit Debian 13 (trixie) oder Ubuntu 24.04 (noble), 64 Bit, mit Internetzugang. Auf Ubuntu 26.04 sind die Befehle laut Docker-Doku identisch, getestet wurde hier 24.04. Ob VM oder Bare Metal, ist egal; unter Proxmox ist eine VM der robuste Weg, siehe Docker in Proxmox: VM oder LXC?.
• Ein Benutzer mit sudo-Rechten und eine SSH-Verbindung zum Server.
• Eine feste IP-Adresse im Heimnetz, im Beispiel 192.168.10.20. Vergib sie am besten als feste Zuordnung im Router.
• Grundwissen zu Containern, Images und Volumes, siehe Docker-Grundlagen.

Lernziel: Am Ende läuft Portainer CE auf deinem Server, ist nur über HTTPS erreichbar, du hast ein Admin-Konto angelegt und kannst prüfen, welche Version läuft.

Was du installierst #

Drei Bausteine, in dieser Reihenfolge:

1. Docker Engine, der Dienst, der Container tatsächlich startet. Er läuft als Hintergrundprozess (Daemon) und nimmt Befehle über eine Socket-Datei entgegen, /var/run/docker.sock.
2. Docker Compose als Plugin, also der Befehl docker compose. Damit beschreibst du Container in einer YAML-Datei statt in langen Befehlszeilen.
3. Portainer CE (Community Edition, die kostenlose Variante) als Container. Er bekommt den Docker-Socket hineingereicht und steuert darüber die Engine.

Portainer belegt bis zu drei Ports, also Netzwerk-Eingänge des Containers:

Im Test mit Portainer CE 2.45.2 lauschte Port 9000 zwar im Container, war aber vom Host aus nicht erreichbar, weil die offizielle Compose-Datei ihn nicht veröffentlicht. Das ist gut so und sollte so bleiben.

Schritt 1: Konkurrierende Pakete entfernen #

Debian und Ubuntu bringen eigene Docker-Pakete mit, die sich mit den offiziellen Paketen von Docker beißen. Der folgende Befehl sucht sie und entfernt nur die, die tatsächlich installiert sind.

Auf Debian 13:

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

Auf Ubuntu 24.04 kommt zusätzlich das Paket docker-compose-v2 dazu:

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

Meldet apt, dass keines der Pakete installiert ist, ist das kein Fehler, du machst einfach weiter. Laufen auf dem Server schon Container aus diesen alten Paketen, sichere zuerst deren Daten: apt remove entfernt die Programme, und du musst die Container danach mit der neuen Engine neu starten.

Auf Ubuntu gibt es eine zweite Falle: Docker als Snap-Paket. Portainer rät ausdrücklich davon ab. Prüfe es mit:

snap list docker

Meldet snap, dass kein passendes Paket installiert ist, ist alles in Ordnung. Ist der Snap installiert, entscheide bewusst, ob du ihn entfernst (sudo snap remove docker). Damit verschwinden auch die Container dieser Installation; Daten vorher sichern.

Schritt 2: Das offizielle Docker-Repository einrichten #

Zuerst holst du die Werkzeuge zum Herunterladen und den Signaturschlüssel von Docker. Mit diesem Schlüssel prüft apt später, dass die Pakete wirklich von Docker stammen.

Auf Debian 13:

sudo apt update
sudo apt install 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

Dann trägst du die Paketquelle ein. Die Datei im deb822-Format (das neuere, mehrzeilige Format für apt-Quellen) liest den Codenamen deiner Version automatisch aus /etc/os-release, bei Debian 13 also trixie:

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

Auf Ubuntu 24.04 unterscheiden sich zwei Stellen: die URL endet auf /linux/ubuntu, und der Codename kommt bevorzugt aus UBUNTU_CODENAME (bei 24.04 noble):

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

Verwechsle die beiden Varianten nicht: Die Debian-Quelle kennt die Ubuntu-Codenamen nicht und umgekehrt. Meldet apt update einen Fehler zum Docker-Repository, schreib die Datei /etc/apt/sources.list.d/docker.sources mit der passenden Variante neu.

Schritt 3: Docker Engine und Compose installieren #

Der Befehl ist auf beiden Systemen gleich. Er installiert die Engine, das Kommandozeilenwerkzeug, die Container-Laufzeit containerd sowie die Plugins für Buildx und Compose:

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

Prüfe danach die Versionen:

sudo docker version --format '{{.Server.Version}}'
sudo docker compose version

Im Test lieferte das:

29.9.0
Docker Compose version v5.6.0

Bei dir können neuere Versionen stehen, das ist normal. Portainer selbst listet für 2.45.2 die Docker Engine 28.5.1 und 29.8.1 als geprüfte Versionen; in der Testumgebung lief 2.45.2 auch mit 29.9.0 problemlos. Ein kurzer Funktionstest lädt ein winziges Test-Image und startet es einmal:

sudo docker run --rm hello-world

Erscheint Hello from Docker!, funktioniert die Engine.

Laut Docker-Dokumentation startet der Dienst auf Debian und Ubuntu nach der Installation automatisch und auch nach jedem Neustart. Diesen Teil konnte die Testumgebung nicht prüfen, weil dort kein systemd lief. Kontrolliere ihn bei dir einmal selbst:

sudo systemctl status docker
sudo systemctl is-enabled docker

Erwartet sind active (running) und enabled. Steht dort disabled, aktivierst du den Autostart mit sudo systemctl enable --now docker.service containerd.service.

Schritt 4: Entscheiden, wer Docker bedienen darf #

Ohne sudo bekommt ein normaler Benutzer beim ersten docker-Befehl diese Meldung, im Test wörtlich so:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Der bequeme Ausweg ist die Gruppe docker, die das Paket bereits anlegt:

sudo usermod -aG docker $USER

Danach einmal ab- und wieder anmelden. Verstehe aber, was du damit tust: Wer Zugriff auf den Docker-Socket hat, kann einen Container mit dem Root-Dateisystem des Hosts starten und ist damit faktisch root. Die Docker-Dokumentation sagt das ausdrücklich. Auf einem Server, an dem nur du arbeitest, ist das eine vertretbare Abwägung. Teilst du dir den Server, bleib bei sudo docker …. In dieser Anleitung steht deshalb überall sudo.

Dasselbe gilt übrigens für Portainer selbst: Es bekommt den Socket, also volle Kontrolle über den Host. Wer sich in Portainer als Admin anmeldet, hat damit ebenfalls Root-Rechte auf dem Server.

Schritt 5: Portainer mit Docker Compose starten #

Lege ein Verzeichnis für die Compose-Datei an und lade die offizielle Datei der LTS-Linie herunter (LTS heißt Long Term Support, also die langsamer, aber länger gepflegte Versionsreihe):

sudo mkdir -p /opt/portainer
cd /opt/portainer
sudo curl -fsSL https://downloads.portainer.io/ce-lts/portainer-compose.yaml -o compose.yaml

Im Test hatte die Datei diesen Inhalt:

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:lts
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - 9443:9443
      - 8000:8000  # Remove if you do not intend to use Edge Agents
 
volumes:
  portainer_data:
    name: portainer_data
 
networks:
  default:
    name: portainer_network

Bevor du startest, lohnen drei kleine Änderungen. Öffne die Datei dafür mit einem Editor:

sudo nano /opt/portainer/compose.yaml

Ersetze in allen Beispielen 192.168.10.20 durch die Adresse deines Servers; ip -br addr zeigt sie dir. In nano speicherst du mit Strg+O und beendest mit Strg+X.

Port 8000 weglassen #

Solange du keine Edge Agents einsetzt, also keine entfernten Hosts, die sich von sich aus bei Portainer melden, brauchst du Port 8000 nicht. Jeder offene Port ist Angriffsfläche, also lösch die Zeile. Du kannst sie später jederzeit wieder ergänzen.

Ports an die LAN-IP binden #

Eine Angabe wie 9443:9443 veröffentlicht den Port auf allen Adressen des Hosts, und zwar an ufw und firewalld vorbei. Sicherer ist es, den Port gezielt an die Adresse zu binden, über die du Portainer erreichen willst:

    ports:
      - "192.168.10.20:9443:9443"

Dann ist Portainer nur unter dieser Adresse erreichbar. Die Bindung legt aber nur die Zieladresse fest, nicht, woher eine Anfrage kommen darf: Laut Docker-Doku können Geräte hinter einer zweiten Netzwerkkarte oder einer VPN-Schnittstelle desselben Hosts die Adresse per Routing trotzdem erreichen. Die Bindung ersetzt also keine Firewall-Regel. Warum Docker die Host-Firewall umgeht und wie du Zugriffe zusätzlich einschränkst, steht in Portainer sicher konfigurieren.

Feste Version statt lts #

Das Tag lts zeigt immer auf die aktuelle LTS-Version, im Test auf 2.45.2. Bequem, aber du siehst in der Datei nicht, welche Version wirklich läuft, und ein docker compose pull kann unbemerkt ein Update einspielen. Für nachvollziehbare Updates schreibst du die Version fest:

    image: portainer/portainer-ce:2.45.2

Die angepasste Datei sieht damit so aus:

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:2.45.2
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - "192.168.10.20:9443:9443"
 
volumes:
  portainer_data:
    name: portainer_data
 
networks:
  default:
    name: portainer_network

Starte Portainer im Verzeichnis /opt/portainer:

sudo docker compose up -d

Compose lädt das Image, legt das Volume portainer_data (dort speichert Portainer seine Datenbank) und das Netzwerk portainer_network an und startet den Container im Hintergrund.

Alternative: ein einzelner docker run-Befehl #

Wer keine Compose-Datei möchte, startet Portainer laut offizieller Doku so:

sudo docker volume create portainer_data
sudo docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts

Der erste Befehl legt das Datenvolume an, der zweite startet den Container mit denselben Einstellungen wie die Compose-Datei. Im Test lief die Compose-Variante auf Debian 13, die docker run-Variante auf Ubuntu 24.04. Auch hier gilt: -p 8000:8000 weglassen, wenn du keine Edge Agents brauchst, und -p 9443:9443 besser als -p 192.168.10.20:9443:9443 schreiben. Die Compose-Variante hat den Vorteil, dass die Konfiguration in einer Datei steht, die du sichern und versionieren kannst. Den Befehl für deine Kombination kannst du dir auch mit dem Portainer-Installations-Assistenten zusammenstellen.

Schritt 6: Ersteinrichtung im Browser #

Jetzt läuft eine Uhr: Laut Portainer-Doku muss das Admin-Konto innerhalb von fünf Minuten nach dem Start angelegt werden. So kann niemand, der zufällig im selben Netz ist, eine frische Instanz vor dir übernehmen.

Setup-Token aus dem Log holen #

Neue Instanzen verlangen seit Portainer 2.43 (bzw. 2.39.4 in der älteren LTS-Linie) einen Setup-Token. Er steht im Log des Containers:

sudo docker logs portainer 2>&1 | grep setup_token

Die Logzeile enthält setup_token=, gefolgt von 64 Hex-Zeichen (gekürzt):

... setup_token=<SETUP_TOKEN> ...

Kopiere den Wert hinter dem Gleichheitszeichen. Der Token gilt nur für diese eine Einrichtung, du musst ihn nicht aufbewahren.

Admin-Konto anlegen #

Öffne im Browser https://192.168.10.20:9443. Der Browser warnt vor dem Zertifikat: Portainer erzeugt beim ersten Start ein selbstsigniertes Zertifikat, im Log steht dazu no cert files found, generating self signed SSL certificates. Die Verbindung ist verschlüsselt, nur kann der Browser den Aussteller nicht prüfen. Für den ersten Login im Heimnetz bestätigst du die Ausnahme; ein eigenes Zertifikat ist Thema im Sicherheits-Guide.

Auf der Einrichtungsseite:

1. Benutzername: Vorgegeben ist admin. Du kannst ihn ändern; ein eigener Name macht Rateversuche mit dem Standardnamen zumindest wertlos.
2. Passwort: mindestens 12 Zeichen. Ein kürzeres Passwort lehnte Portainer im Test mit Password does not meet the requirements ab. Nimm am besten ein langes, zufälliges Passwort aus einem Passwortmanager.
3. Den kopierten Token fügst du in das Feld Setup token ein. Ohne oder mit falschem Token verweigert Portainer die Anlage; im Test lautete die Meldung Invalid or missing setup token.
4. Mit Create user legst du das Konto an. Den Link Restore Portainer from backup brauchst du nur, wenn du eine gesicherte Konfiguration zurückspielen willst.

Edge Compute: vorerst überspringen #

Als Nächstes zeigt Portainer die Seite Set up Edge Compute mit dem Schalter Enable Edge Compute features. Edge Compute brauchst du nur für Edge Agents, also entfernte Hosts, die sich von sich aus bei Portainer melden. Für einen einzelnen Server wählst du Skip; du kannst die Funktion später in den Einstellungen einschalten.

Willst du Edge Agents nutzen und schaltest die Funktion ein, solltest du eines wissen: Die Community Edition bietet keinen Warteraum, in dem du neue Edge Agents erst bestätigen müsstest. In den Edge-Compute-Einstellungen von Portainer CE 2.45.2 gibt es nur Enable Edge Compute features und Enforce use of Portainer generated Edge ID. Ein Edge Agent mit gültigem Edge Key verbindet sich direkt. Behandle den Edge Key deshalb wie ein Passwort; Details stehen in Portainer mit mehreren Servern. Mit Continue geht es weiter.

Das lokale Environment #

Danach startet der Einrichtungsassistent. Ein Environment ist in Portainer ein verwalteter Docker-Host. Den Host, auf dem Portainer selbst läuft, erkennt Portainer laut Doku automatisch und bindet ihn über den gemounteten Socket unix:///var/run/docker.sock ein. Mit Get Started arbeitest du direkt mit diesem lokalen Environment, das Portainer standardmäßig local nennt (so auch im Test mit 2.45.2). Add Environments brauchst du erst, wenn weitere Server dazukommen sollen.

Schritt 7: Prüfen, ob alles läuft #

Zuerst der Containerstatus:

sudo docker ps --filter name=portainer

So sieht die Ausgabe mit der angepassten Compose-Datei sinngemäß aus (gekürzt):

IMAGE                           STATUS         PORTS                                      NAMES
portainer/portainer-ce:2.45.2   Up 2 minutes   8000/tcp, 9000/tcp, 192.168.10.20:9443->9443/tcp   portainer

Entscheidend ist die Spalte PORTS: Nur 9443 hat einen Pfeil, ist also nach außen veröffentlicht. 8000/tcp und 9000/tcp ohne Pfeil lauschen nur im Container.

Dann fragst du die API nach der laufenden Version. -k lässt curl das selbstsignierte Zertifikat akzeptieren:

curl -k https://192.168.10.20:9443/api/system/status

Ältere Anleitungen nennen den Pfad /api/status; er antwortet noch, ist laut Portainer-Log aber veraltet. Die Antwort enthält die Versionsnummer, im Test:

{"Version":"2.45.2","InstanceID":"<INSTANCE_ID>"}

Hast du den Port nicht an eine IP gebunden, funktioniert auf dem Server auch curl -k https://localhost:9443/api/system/status. Mit Bindung an 192.168.10.20 antwortet localhost dagegen nicht, das ist erwartet.

Typische Probleme #

permission denied while trying to connect to the docker API: Du hast docker ohne sudo aufgerufen und bist nicht in der Gruppe docker. Lösung: sudo voranstellen oder bewusst der Gruppe beitreten (Schritt 4) und neu anmelden.

Bind for …:9443 failed: port is already allocated: Ein anderer Container oder Dienst belegt den Port. sudo ss -tlnp | grep 9443 zeigt, wer ihn hält; steht dort docker-proxy, ist es ein anderer Container, den sudo docker ps verrät. Lösung: den anderen Dienst umziehen oder Portainer auf einen anderen Host-Port legen, etwa "192.168.10.20:9444:9443".

Einrichtungsseite meldet Invalid or missing setup token: Der Token fehlt oder wurde unvollständig kopiert. Hol ihn erneut mit sudo docker logs portainer 2>&1 | grep setup_token.

Fünf Minuten verpasst: Portainer verweigert die Einrichtung, im Log steht ein Hinweis, dass die Instanz aus Sicherheitsgründen abgelaufen ist. Laut Doku reicht ein Neustart des Containers:

sudo docker stop portainer
sudo docker start portainer

Danach den Token erneut aus dem Log holen und die Einrichtung zügig abschließen.

Browser zeigt nur Client sent an HTTP request to an HTTPS server.: Du hast http:// statt https:// aufgerufen, Port 9443 spricht nur HTTPS. Rufe https://192.168.10.20:9443 auf.

Seite lädt gar nicht, Browser meldet Verbindungsfehler: Läuft der Container (sudo docker ps)? Stimmt die IP in der Port-Bindung mit der Adresse überein, die du im Browser aufrufst?

apt findet docker-ce nicht: Die Paketquelle fehlt oder passt nicht zur Distribution. Kontrolliere /etc/apt/sources.list.d/docker.sources: Auf Ubuntu muss URIs auf /linux/ubuntu enden, auf Debian auf /linux/debian.

Sicherheit und Betrieb #

• Portainer ist ein Root-Zugang. Über den Docker-Socket steuert Portainer den ganzen Host. Behandle das Admin-Passwort entsprechend und gib Portainer nie ungeschützt ins Internet frei. Warum der Socket so mächtig ist und wie du das Risiko begrenzt, erklärt Docker und Portainer absichern.
• Ports bewusst veröffentlichen. Binde Ports an eine konkrete IP und veröffentliche nur, was du brauchst: 9443 ja, 8000 nur für Edge, 9000 nie (intern spricht ihn höchstens ein Reverse Proxy an).
• Version festhalten. Mit fester Version im Image weißt du, was läuft, und entscheidest selbst über Updates.
• Daten liegen im Volume. Alles, was Portainer sich merkt, steckt im Volume portainer_data. Der Container ist austauschbar, das Volume nicht. Lösche es nie nebenbei, etwa mit docker volume prune -a oder docker compose down -v, sonst ist die gesamte Portainer-Konfiguration weg. Ein einfaches docker volume prune entfernt laut Docker-Doku nur anonyme Volumes und lässt portainer_data stehen.

Weiterlesen #

• Portainer sicher konfigurieren: der nächste Schritt nach dem ersten Login, mit Zugriffswegen, Zertifikat und Benutzerverwaltung.
• Portainer hinter einem Reverse Proxy: wenn du Portainer unter einem eigenen Namen mit gültigem Zertifikat erreichen willst.
• Docker und Portainer absichern: für alle, die verstehen wollen, warum der Docker-Socket das eigentliche Risiko ist.
• Portainer-Installations-Assistent: stellt Compose-Datei und Befehle für deine Kombination aus System, Ports und Version zusammen.