Apache Guacamole auf einem Raspberry Pi installieren

Apache Guacamole auf dem Raspberry Pi verwandelt deinen Mini-Rechner in ein clientloses Remote-Desktop-Gateway. Statt für jedes System einen eigenen Client für RDP, VNC oder SSH zu installieren, öffnest du deine Geräte einfach im Webbrowser – egal ob vom Laptop, Tablet oder Smartphone. In dieser Schritt-für-Schritt-Anleitung installierst du Apache Guacamole auf einem Raspberry Pi als Docker-Container und sicherst den Zugang optional mit einer Zwei-Faktor-Authentifizierung ab.

Wir setzen dabei bewusst auf Docker, denn so läuft Guacamole samt Datenbank, dem guacd-Daemon und der Weboberfläche in einem einzigen, sauber gekapselten Container. Falls du mit Containern noch nicht vertraut bist, verschafft dir unser Beitrag Was ist Docker? zuerst den nötigen Überblick. Das gleiche Prinzip funktioniert übrigens auch auf anderen Homeserver-Plattformen wie Unraid oder Proxmox.

Voraussetzungen

Damit die Installation reibungslos gelingt, solltest du folgende Dinge bereithalten:

• Einen Raspberry Pi 4 (oder neuer) mit mindestens 2 GB RAM – 4 GB sind für flüssigeres Arbeiten empfehlenswert.
• Ein aktuelles 64-Bit-Betriebssystem, zum Beispiel Raspberry Pi OS (Bookworm).
• Terminal-Zugriff über einen Benutzer mit sudo-Rechten (lokal oder per SSH).
• Eine stabile Internetverbindung zum Herunterladen der Docker-Images.

Apache Guacamole auf dem Raspberry Pi installieren – Schritt für Schritt

Die Einrichtung gliedert sich in drei überschaubare Schritte: System aktualisieren, Docker installieren und schließlich den Guacamole-Container starten. Arbeite die Abschnitte am besten der Reihe nach ab.

Schritt 1: Raspberry Pi auf den neuesten Stand bringen

Bevor du neue Software installierst, solltest du das System aktualisieren. So stellst du sicher, dass alle Pakete und Sicherheitsupdates aktuell sind:

sudo apt update
sudo apt upgrade -y

sudo apt update lädt die aktuellen Paketlisten aus den Repositories, während sudo apt upgrade -y alle installierten Pakete aktualisiert und Rückfragen automatisch bestätigt. Je nach letztem Update kann dieser Vorgang ein paar Minuten dauern.

Schritt 2: Docker installieren

Für den Betrieb von Guacamole brauchst du Docker. Beachte vorab zwei Punkte rund um die Firewall, damit es später keine Überraschungen gibt:

• Nutzt du ufw oder firewalld, umgehen von Docker freigegebene Container-Ports deine bestehenden Firewall-Regeln. Details dazu findest du in der Docker-Dokumentation zu ufw.
• Docker ist nur mit iptables-nft und iptables-legacy kompatibel. Eigene Regeln solltest du deshalb über die DOCKER-USER-Kette einbinden (siehe Paketfilterung und Firewalls).

Richte zunächst das offizielle Docker-Repository ein. Damit erhältst du stets aktuelle und signierte Docker-Pakete direkt von Docker selbst:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/raspbian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/raspbian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Sind Repository und GPG-Schlüssel eingerichtet, installierst du Docker mit allen wichtigen Komponenten in einem Rutsch:

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

Damit ist Docker einsatzbereit. Mit docker --version kannst du die erfolgreiche Installation kurz überprüfen.

Schritt 3: Apache Guacamole als Docker-Container starten

Jetzt folgt der eigentliche Kern der Anleitung. Der folgende Befehl lädt das Guacamole-Image für den Raspberry Pi herunter und startet den Container. Ersetze </path/to/config> durch einen echten Pfad auf deinem Pi, in dem die Konfiguration dauerhaft gespeichert wird:

docker run \
  -p 8080:8080 \
  -v </path/to/config>:/config \
  -v /etc/localtime:/etc/localtime:ro \
  -e TZ="UTC" \
  -e EXTENSIONS="auth-totp" \
  flcontainers/guacamole

Ich empfehle ausdrücklich, die Erweiterung auth-totp zu aktivieren. Sie fügt dem Login einen zweiten Faktor hinzu und erhöht die Sicherheit spürbar – gerade wenn Guacamole später aus dem Netzwerk erreichbar ist.

Sobald der Container heruntergeladen und gestartet ist, erreichst du die Weboberfläche über die IP-Adresse deines Raspberry Pi, gefolgt vom Port 8080:

http://[RASPBERRY_PI_IP]:[PORT]

Die aktuelle IP-Adresse deines Raspberry Pi zeigt dir der Befehl hostname -I an.

Beim ersten Aufruf meldest du dich mit dem Benutzernamen guacadmin und dem Passwort guacadmin an. Wichtig: Ändere dieses Standardpasswort umgehend und lege für den Alltag ein eigenes Benutzerkonto an.

Apache Guacamole absichern

Guacamole liefert die Verbindung standardmäßig unverschlüsselt über HTTP aus. Für den dauerhaften Betrieb – und erst recht für den Zugriff aus dem Internet – solltest du den Dienst deshalb hinter einen Reverse Proxy wie NGINX oder Traefik setzen und ein gültiges SSL-Zertifikat einrichten. In Kombination mit der zuvor aktivierten TOTP-Erweiterung erhältst du so einen verschlüsselten und mehrfach abgesicherten Zugang zu deinen Systemen.

Fazit

Mit Apache Guacamole auf einem Raspberry Pi baust du dir eine schlanke, leistungsfähige Remote-Desktop-Lösung, die komplett im Webbrowser läuft und keine zusätzliche Client-Software benötigt. Dank Docker ist die Installation in wenigen Minuten erledigt und lässt sich später problemlos aktualisieren oder auf andere Hardware übertragen. Ergänzt um Zwei-Faktor-Authentifizierung und einen Reverse Proxy erhältst du einen sicheren Fernzugriff auf all deine Geräte – von überall.

Häufige Fragen zu Apache Guacamole auf dem Raspberry Pi

Läuft Apache Guacamole flüssig auf einem Raspberry Pi?

Ja. Für den Heimgebrauch reicht ein Raspberry Pi 4 mit 2 bis 4 GB RAM gut aus. Guacamole selbst ist ressourcenschonend, da die eigentliche Rechenlast auf den entfernten Systemen liegt. Bei vielen gleichzeitigen Sitzungen oder grafikintensiven Desktops profitierst du allerdings von mehr Arbeitsspeicher.

Welche Protokolle unterstützt Apache Guacamole?

Guacamole unterstützt die gängigen Remote-Protokolle RDP (Windows), VNC und SSH sowie Telnet und Kubernetes-Konsolen. Damit greifst du über eine einzige Oberfläche auf Windows-, Linux- und macOS-Systeme zu.

Wie ändere ich das Standardpasswort guacadmin?

Melde dich mit guacadmin / guacadmin an und öffne oben rechts die Einstellungen unter „Preferences“. Dort kannst du das Passwort ändern. Für den produktiven Einsatz empfiehlt es sich, ein separates Administratorkonto anzulegen und das Standardkonto zu deaktivieren.

Kann ich Guacamole auch ohne Docker installieren?

Grundsätzlich ja – eine native Installation aus den Quellpaketen ist möglich, aber deutlich aufwendiger, weil Tomcat, guacd und die Datenbank einzeln eingerichtet werden müssen. Der Docker-Weg aus dieser Anleitung ist für die meisten Nutzer schneller, wartungsärmer und leichter reproduzierbar.

Wie erreiche ich Guacamole sicher aus dem Internet?

Öffne niemals den Port 8080 direkt im Router. Nutze stattdessen einen Reverse Proxy mit SSL-Verschlüsselung, ein VPN wie WireGuard oder einen Tunnel-Dienst. In Verbindung mit der TOTP-Zwei-Faktor-Authentifizierung ist dein Zugang so bestmöglich geschützt.