diff --git a/docs/docker/portainer/portainer.md b/docs/docker/portainer/portainer.md new file mode 100644 index 0000000..7d48784 --- /dev/null +++ b/docs/docker/portainer/portainer.md @@ -0,0 +1,172 @@ +# Portainer EE mit Remote-Agent (Hetzner) über SSH-Tunnel + +## Ziel + +Lokaler Portainer EE verwaltet zusätzlich einen entfernten Docker-Host (Hetzner), +ohne dass der Agent-Port (9001) öffentlich erreichbar ist. Der Key für die EE ist in Bitwarden hinterlegt. + +Die Verbindung erfolgt ausschließlich über einen SSH-Tunnel. + +--- + +# Architektur + +## Übersicht + +- Heimserver: Portainer EE +- Hetzner-Server: Portainer Agent +- Verbindung: SSH-Tunnel (autossh + systemd) +- Kein öffentlicher Port 9001 + +--- + +## ASCII Netzwerk-Skizze +``` +## Netzwerk- und Tunnel-Architektur + +``` + Internet + │ + │ + +-------------------+ + | Hetzner VPS | + |-------------------| + | Docker Host | + | | + | Portainer Agent | + | 0.0.0.0:9001 | + +---------┬---------+ + │ + │ localhost:9001 + │ +=========================== SSH Tunnel =========================== +ssh -L 0.0.0.0:9002:localhost:9001 root@hetzner-ip +==================================================================== + │ + │ 0.0.0.0:9002 (Host) + │ + +---------┴---------+ + | Heimserver | + |-------------------| + | | + | autossh Tunnel | + | listening on | + | 0.0.0.0:9002 | + | | + | Docker Bridge | + | 172.17.0.1 | + | | + | Portainer EE | + | connects to | + | 172.17.0.1:9002 | + +-------------------+ +``` +# Funktionsweise + +1. Der Portainer-Agent läuft auf Hetzner und lauscht auf Port 9001. +2. Dieser Port ist **nicht öffentlich relevant**, da keine direkte Nutzung erfolgt. +3. Der Heimserver baut per SSH einen Tunnel auf: + - Lokaler Port 9002 → Hetzner localhost:9001 +4. Portainer EE verbindet sich intern über: 172.17.0.1:9002 (docker bridge) +5. Der gesamte Traffic läuft verschlüsselt über SSH. +``` + +# 1. Portainer-Agent auf Hetzner +## docker-compose.yml + +``` yaml +version: "3.8" + +services: +portainer_agent: + image: portainer/agent:2.27.3 + container_name: portainer_agent + restart: unless-stopped + ports: + - "9001:9001" + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - /var/lib/docker/volumes:/var/lib/docker/volumes +``` + +Starten: docker compose up -d +Prüfen: ss -tlnp | grep 9001 +Erwartet: 0.0.0.0:9001 + +# 2. SSH-Tunnel automatisieren (Heimserver) +## autossh installieren +apt update +apt install autossh -y + +## systemd Service anlegen + +Datei: +/etc/systemd/system/portainer-hetzner-tunnel.service + +Inhalt: +``` ini +[Unit] +Description=SSH Tunnel to Hetzner Portainer Agent +After=network.target + +[Service] +User=root +Environment="AUTOSSH_GATETIME=0" +ExecStart=/usr/bin/autossh \ + -M 0 \ + -N \ + -o "ServerAliveInterval=30" \ + -o "ServerAliveCountMax=3" \ + -o "ExitOnForwardFailure=yes" \ + -o "StrictHostKeyChecking=no" \ + -i /root/.ssh/portainer_tunnel \ + -L 0.0.0.0:9002:localhost:9001 \ + root@65. + +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target + +## Service aktivieren +``` snippet +systemctl daemon-reload +systemctl enable portainer-hetzner-tunnel +systemctl start portainer-hetzner-tunnel +``` + +Status prüfen: +``` +systemctl status portainer-hetzner-tunnel +``` +Port prüfen: +``` +ss -tlnp | grep 9002 +``` +Erwartet: +``` +0.0.0.0:9002 +``` +## 3. Portainer EE konfigurieren +In der WebUI: +Environments → Add Environment → Agent +Adresse: 172.17.0.1:9002 +Hinweis: 172.17.0.1 ist die Docker-Bridge-IP des Hosts +Portainer läuft im Container +Der Tunnel läuft auf dem Host + +# Sicherheitsmodell +- Port 9001 nicht öffentlich erreichbar +- Kommunikation ausschließlich über SSH +- SSH-Key-basierte Authentifizierung +- Automatischer Reconnect via autossh +- Kein zusätzlicher VPN erforderlich + +# Troubleshooting +|Problem |Ursache | Prüfen +|connection refused |Agent nicht auf 9001 gemappt | - ports9001:9001 in der docker-compose +|SSH channel open failed |Agent lauscht nicht |keys vorhanden? +|Endpoint unreachable |Tunnel nicht aktiv +|curl localhost:9001 schlägt fehl |Agent läuft nicht korrekt + diff --git a/mkdocs.yml b/mkdocs.yml index 4b3afcd..3b2f22c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,8 +20,11 @@ nav: - Architektur: docker/architecture.md - Adguardhome: docker/adguardhome/adguardhome.md - Wikijs: docker/wikijs/wikijs.md - - It-Tools: docker/it-tools/it-tools.md - Heimdall: docker/heimdall/heimdall.md + - It-Tools: docker/it-tools/it-tools.md + - Protainer: docker/portainer/portainer.md + - Wikijs: docker/wikijs/wikijs.md + - Backup_Storage: - Backup: backup/backup.md