Zum Inhalt springen
labkompass

Command Builder · Docker

Portainer-Installationsassistent

Fünf Fragen zu deinem Setup, danach die passenden Schritte: Docker aus dem offiziellen Repository, Portainer per Compose oder docker run, Setup-Token und erster Login, auf Wunsch der Agent für weitere Hosts. Die Erreichbarkeit regelt der Assistent über das Binden des Ports an eine Adresse — denn Docker-Portfreigaben umgehen ufw und firewalld.

Betriebssystem
Ist Docker schon installiert?
Von wo soll Portainer erreichbar sein?

Mit ip -br addr auf dem Server nachsehen. Bitte eigene Adresse eintragen.

Wie viele Docker-Hosts sollen verwaltet werden?
Installation mit

Optionen

Generierte Datei

# 1. Docker Engine aus dem offiziellen Docker-Repository (Debian)
#    Alte Pakete aus den Distributionsquellen entfernen (falls vorhanden):
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc docker-buildx podman-docker containerd runc | cut -f1)

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

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
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

#    Prüfen: Version ausgeben und Testcontainer starten
sudo docker version
sudo docker run --rm hello-world

# 2. Verzeichnis für Portainer anlegen und compose.yaml hineinlegen
#    (Inhalt: Reiter compose.yaml)
sudo mkdir -p /opt/portainer
cd /opt/portainer
sudo nano compose.yaml

# 3. Portainer starten
sudo docker compose up -d

# 4. Setup-Token aus dem Log holen — die Erstanmeldung verlangt ihn
sudo docker logs portainer 2>&1 | grep setup_token

# 5. Innerhalb von 5 Minuten im Browser öffnen: https://192.168.10.20:9443
#    Setup-Token eintragen, Admin-Konto anlegen (Passwort mind. 12 Zeichen).
#    Danach den Schritt „Set up Edge Compute“ mit Skip überspringen (nur für Edge Agents nötig).
#    Die Zertifikatswarnung beim ersten Aufruf ist erwartet (selbstsigniert).
#    Zu spät? Container neu starten und neuen Token holen:
#    sudo docker restart portainer

# 6. Prüfen: Container läuft, API antwortet mit der Version
sudo docker ps --filter name=portainer
curl -k https://192.168.10.20:9443/api/system/status

Das bedeuten die Parameter

Docker Engine
Installiert wird Docker aus dem offiziellen Repository von Docker, nicht das ältere docker.io-Paket der Distribution und nicht per snap.
Erreichbarkeit
Port 9443 wird an die LAN-IP des Servers gebunden — andere Schnittstellen (z. B. ein VPN- oder Docker-Netz) bekommen ihn nicht.
portainer/portainer-ce
lts folgt der Long-Term-Support-Linie, sts den kurzlebigeren Feature-Releases. Eine feste Version macht Updates planbar.

Was der Assistent voraussetzt

Einen Server mit Debian 12/13 oder Ubuntu 22.04/24.04/26.04, einen Benutzer mit sudo und eine feste IP-Adresse im Heimnetz. Die Befehle für Docker stammen aus der offiziellen Anleitung von Docker, die Portainer-Konfiguration aus der offiziellen Compose-Datei von Portainer — ergänzt um das Binden an eine Adresse und ohne den Port 8000, solange du keine Edge Agents nutzt.

Warum ein Setup-Token?

Eine frisch gestartete Portainer-Instanz hat noch kein Admin-Konto. Damit niemand im Netz schneller ist als du, verlangt Portainer beim Anlegen des Kontos einen einmaligen Token aus dem Container-Log — und das Konto muss innerhalb von fünf Minuten nach dem Start angelegt werden. Läuft die Frist ab, startest du den Container neu und holst den neuen Token.

Alle Optionen im Überblick

OptionBedeutungErklärung
Docker EngineIst Docker schon installiert?Installiert wird Docker aus dem offiziellen Repository von Docker, nicht das ältere docker.io-Paket der Distribution und nicht per snap.
·Nur im Heimnetz (LAN)Port 9443 wird an die LAN-IP des Servers gebunden — andere Schnittstellen (z. B. ein VPN- oder Docker-Netz) bekommen ihn nicht.
·Nur über VPN (WireGuard, Tailscale)Port 9443 wird an die VPN-Adresse des Servers gebunden. Erreichbar ist Portainer dann nur mit aktiver VPN-Verbindung.
·Hinter einem Reverse ProxyPortainer lauscht nur auf 127.0.0.1; der Reverse Proxy übernimmt HTTPS mit gültigem Zertifikat.
·Aus dem InternetTechnisch wie hinter dem Reverse Proxy — Portainer selbst bleibt auf 127.0.0.1. ⚠ Eine öffentlich erreichbare Portainer-Anmeldung ist ein direkter Weg zu Root-Rechten auf deinem Server.
·Portainer Agent (gleiches Netz oder VPN)Der Server verbindet sich zum Agent auf Port 9001 des anderen Hosts — dieser Host muss also erreichbar sein.
·Edge Agent (Host hinter NAT, z. B. VPS oder entfernter Standort)Der Edge Agent meldet sich von sich aus beim Server (Port 9443 und 8000) — der entfernte Host braucht keinen offenen Port.
AGENT_SECRETAGENT_SECRET verwenden (empfohlen)Portainer und Agent prüfen beim Verbinden dasselbe Geheimnis. Wird es nachträglich gesetzt, müssen alle bestehenden Agents es ebenfalls bekommen. ⚠ Das Geheimnis liegt in .env-Dateien, nicht in compose.yaml oder Befehlen.
portainer/portainer-cePortainer-Versionlts folgt der Long-Term-Support-Linie, sts den kurzlebigeren Feature-Releases. Eine feste Version macht Updates planbar.

Häufige Fragen

Wurden die Schritte getestet?

In einer Testumgebung am 10.10.2026: Docker per apt-Repository auf Debian 13 und Ubuntu 24.04 (Docker Engine 29.9.0, Compose 5.6.0), Portainer CE 2.45.2 per Compose auf Debian und per docker run auf Ubuntu, dazu Setup-Token, Agent und Edge Agent. Nicht geprüft wurden der systemd-Start des Docker-Dienstes und die Bindung an eine echte LAN- oder VPN-Adresse — die Beispieladressen musst du durch deine eigenen ersetzen.

Warum nicht einfach Port 9443 in ufw sperren?

Weil Docker veröffentlichte Ports an ufw und firewalld vorbei weiterleitet — die Regel greift dann nicht. Zuverlässig ist, den Port gleich an die passende Adresse zu binden: an die LAN-IP, an die VPN-Adresse oder an 127.0.0.1 hinter einem Reverse Proxy.

lts, sts oder eine feste Version?

lts folgt der Long-Term-Support-Linie mit Fehler- und Sicherheitskorrekturen, sts den häufigeren Feature-Releases. Für ein Homelab ist lts der ruhigere Weg; eine feste Versionsnummer macht zusätzlich nachvollziehbar, wann du aktualisierst. Agents sollten dieselbe Version wie der Server haben.

Passende Tools