Zoraxy mit Docker Compose: Reverse Proxy mit Weboberfläche einrichten

Wer mehrere Webdienste hinter einer einzigen IP-Adresse betreibt, braucht einen Reverse Proxy, der Anfragen anhand des Hostnamens an den richtigen Container weiterreicht. Traefik und Caddy erledigen das über Konfigurationsdateien oder Labels. Zoraxy geht einen anderen Weg: Der in Go geschriebene Proxy bringt eine vollständige Weboberfläche mit, in der Sie Proxy-Regeln, Zertifikate, Weiterleitungen und Zugriffsregeln per Klick pflegen. Das Projekt steht unter AGPL-3.0 und hat auf GitHub rund 5.500 Sterne. Diese Anleitung richtet Zoraxy 3.3.4 per Docker Compose ein, inklusive Backup, Restore und Update.

Voraussetzungen

Zoraxy ist genügsam. Im Test belegte der Konfigurationsordner nach der Einrichtung rund 80 KB, der Container war nach etwa vier Sekunden erreichbar. Das Image gibt es laut Docker Hub für amd64 und arm64.

• Ein Linux-Server oder VPS mit Docker Engine und Docker Compose v2, 1 bis 2 CPU-Kerne und 1 GB RAM genügen ohne die Option FASTGEOIP. Diese benötigt laut Projektdokumentation rund 1 GB zusätzlichen Arbeitsspeicher.
• Freie Ports 80 und 443 auf dem Host. Läuft dort schon ein Webserver oder ein anderer Proxy, startet Zoraxy nicht (siehe Troubleshooting).
• Für echte Zertifikate eine Domain, deren DNS-Einträge auf den Server zeigen, und von außen erreichbare Ports 80 und 443.
• Port 8000 für die Weboberfläche, der nur aus Ihrem internen Netz oder per VPN erreichbar sein sollte.

Schritt 1: Projektordner und compose.yaml anlegen

Die offizielle Compose-Datei im Repository nutzt :latest, bindet den Docker-Socket ein und aktiviert FASTGEOIP. Für einen planbaren Betrieb schreiben Sie die Version fest, lassen den Socket zunächst weg und schalten die speicherhungrige GeoIP-Option ab. Legen Sie den Ordner an:

mkdir -p /opt/zoraxy/config /opt/zoraxy/plugin
cd /opt/zoraxy

Die Datei .env enthält nur den Versions-Tag:

ZORAXY_TAG=v3.3.4

Die compose.yaml sieht so aus. Der Dienst whoami ist ein winziger Test-Webserver, mit dem Sie die erste Proxy-Regel prüfen. Später ersetzen Sie ihn durch Ihre eigentlichen Anwendungen.

services:
  zoraxy:
    image: zoraxydocker/zoraxy:${ZORAXY_TAG}
    container_name: zoraxy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
      - "8000:8000"
    volumes:
      - ./config:/opt/zoraxy/config/
      - ./plugin:/opt/zoraxy/plugin/
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      TZ: "Europe/Berlin"
      FASTGEOIP: "false"

  whoami:
    image: traefik/whoami:v1.12.0
    restart: unless-stopped

Eckdaten	Wert
Image	zoraxydocker/zoraxy:v3.3.4 (letztes stabiles Release vom 22.08.2026; latest zeigt auf denselben Stand)
Ports	80/tcp (HTTP), 443/tcp und 443/udp (HTTPS, HTTP/3), 8000/tcp (Weboberfläche, per PORT änderbar)
Volumes	/opt/zoraxy/config/ (Konfiguration, Datenbank, Zertifikate), /opt/zoraxy/plugin/ (Plugins)
Env	TZ, FASTGEOIP, optional PORT, NOAUTH (nie auf true setzen), MDNS, ZEROTIER
Healthcheck	im Image enthalten (nc -vz 127.0.0.1 $PORT)

Die Versionen v3.3.5-rc1 bis rc3 auf Docker Hub sind Release Candidates und gehören nicht auf ein Produktivsystem.

Verifizieren: docker compose config gibt die Datei ohne Fehler aus und zeigt beim Image zoraxydocker/zoraxy:v3.3.4.

Schritt 2: Container starten und Admin-Konto anlegen

docker compose up -d
docker compose ps
docker compose logs zoraxy | grep "Zoraxy started"

Im Log erscheint Zoraxy started. Visit control panel at http://localhost:8000. Öffnen Sie nun http://SERVER-IP:8000. Eine frische Instanz zeigt statt der Anmeldung das Formular Account Setup.

Genau hier liegt der wichtigste Sicherheitspunkt: Solange kein Konto existiert, kann jeder, der Port 8000 erreicht, das Root-Konto anlegen. Im Test meldete /api/auth/userCount vor der Einrichtung 0. Erledigen Sie diesen Schritt deshalb direkt nach dem Start und geben Sie Port 8000 nie ungeschützt ins Internet frei. Nach dem ersten Konto ist die Registrierung gesperrt; ein zweiter Versuch endete im Test mit Root management account already exists. Ein falsches Passwort quittiert Zoraxy mit Invalid username or password.

API-Aufrufe ohne Anmeldung leitet Zoraxy mit 307 auf /login.html um, Formulare sind zusätzlich per CSRF-Token geschützt.

Verifizieren: docker compose ps zeigt zoraxy als Up (healthy), nach dem Anlegen des Kontos landen Sie im Dashboard mit dem Status Online, Serving request on port: 443.

Schritt 3: Erste Proxy-Regel anlegen

Öffnen Sie im Menü Create Proxy Rule. Unter Matching Keyword / Domain tragen Sie den Hostnamen ein, unter dem der Dienst erreichbar sein soll, unter Target IP Address or Domain Name with port das Ziel. Weil Zoraxy und whoami im selben Compose-Netz laufen, genügt der Dienstname mit Port: whoami:80. Dienste direkt auf dem Host erreichen Sie über host.docker.internal, andere Server per IP-Adresse und Port.

Eine frische Installation läuft im HTTPS-Modus und leitet Port 80 per 307 auf HTTPS um. Soll ein Dienst zusätzlich per HTTP erreichbar sein, aktivieren Sie unter Advance Settings die Option Allow plain HTTP access. Im Test lieferte eine Regel ohne diese Option auf Port 80 307 nach https://, mit Option direkt 200. Solange kein eigenes Zertifikat hinterlegt ist, antwortet Zoraxy auf Port 443 mit einem selbst signierten Fallback-Zertifikat (CN=Zoraxy Self-host). Echte Zertifikate holt der eingebaute ACME-Client unter ACME Client, sobald Ihre Domain öffentlich auf den Server zeigt.

Prüfen können Sie die Regel auch ohne DNS-Eintrag, indem Sie den Host-Header selbst setzen:

curl -s -H 'Host: whoami.example.test' http://localhost/

Im Test kam diese Antwort des Backends zurück (gekürzt):

Hostname: c33b72c72130
Host: whoami.example.test
X-Forwarded-For: 172.18.0.1
X-Forwarded-Proto: http
X-Real-Ip: 172.18.0.1

Auffällig ist X-Forwarded-For: 172.18.0.1: Wegen der Docker-Portweiterleitung sieht Zoraxy nicht die echte Client-Adresse, sondern das Gateway der Docker-Bridge. Für Zugriffslisten nach IP-Adresse in Zoraxy ist das relevant; eine Host-Firewall oder ein VPN sind hier die verlässlichere Wahl.

Verifizieren: Die Regel erscheint unter HTTP Proxy mit grünem Schalter, und der curl-Aufruf liefert HTTP 200 mit dem Hostnamen des Backend-Containers.

Schritt 4: Docker-Socket nur bewusst einbinden

Die offizielle Compose-Datei bindet /var/run/docker.sock ein. Zoraxy nutzt ihn nur für die Schaltfläche Pick from Docker Containers. Wer Zugriff auf den Socket hat, kann Container mit Host-Rechten starten und kontrolliert damit den Server. Ausgerechnet dem Dienst, der am stärksten dem Internet ausgesetzt ist, sollten Sie diese Macht nicht geben. Auch :ro schützt nur die Socket-Datei, nicht die API-Befehle.

Ohne Socket funktioniert Zoraxy vollständig, nur die Containerauswahl bleibt leer. Im Test lieferte die Schaltfläche dann {"error":"List docker container failed"}, im Log stand dial unix /var/run/docker.sock: connect: no such file or directory. Tragen Sie Ziele einfach von Hand ein, wie in Schritt 3.

Verifizieren: docker inspect zoraxy --format '{{range .Mounts}}{{.Destination}} {{end}}' listet nur /opt/zoraxy/config/ und /opt/zoraxy/plugin/.

Schritt 5: Konfiguration sichern

Zoraxy speichert alles im Ordner config: die BoltDB-Datenbank sys.db mit Benutzerkonto und Sitzungsschlüssel, die Proxy-Regeln als Dateien unter conf/proxy/, Zertifikate unter conf/certs/ sowie sys.uuid. Weil die Datenbank im laufenden Betrieb geöffnet ist, stoppen Sie den Container kurz und archivieren dann den ganzen Projektordner:

cd /opt/zoraxy
docker compose stop zoraxy
sudo tar czf /backup/zoraxy-$(date +%F).tar.gz config plugin compose.yaml .env
docker compose start zoraxy
tar tzf /backup/zoraxy-$(date +%F).tar.gz | grep -E 'sys.db|proxy/'

Das Archiv war im Test knapp 7 KB groß und enthielt config/sys.db, config/sys.uuid und config/conf/proxy/whoami.example.test.config.

Zusätzlich bietet die Oberfläche unter Utilities, Reiter System, die Open Config Tools zum Export. Im Test lieferte der Export mit Datenbank ein ZIP mit acht Dateien, darunter sys.db und die Proxy-Regel, aber ohne sys.uuid. Für ein vollständiges Abbild ist das tar-Archiv daher die bessere Wahl.

Behandeln Sie das Backup wie ein Passwort: Es enthält den Sitzungsschlüssel. Im Test war eine vor dem Backup ausgestellte Anmeldung nach dem Restore sofort wieder gültig. Wer das Archiv besitzt, kann sich also ohne Passwort eine gültige Sitzung bauen. Bewahren Sie es verschlüsselt auf.

Verifizieren: tar tzf listet config/sys.db und Ihre Proxy-Regeln, und docker compose ps zeigt Zoraxy nach dem Start wieder als healthy.

Schritt 6: Wiederherstellung nach Totalverlust

Ein Backup ist erst etwas wert, wenn die Rücksicherung klappt. Im Test wurde der Ordner komplett gelöscht und Zoraxy neu gestartet. Ergebnis: userCount stand wieder auf 0, die Einrichtungsseite war offen für jeden, und Anfragen an whoami.example.test landeten nur noch in der HTTPS-Umleitung. So stellen Sie den Stand wieder her:

cd /opt/zoraxy
docker compose down
sudo rm -rf config plugin
sudo tar xzf /backup/zoraxy-2026-10-22.tar.gz
docker compose up -d

Nach dem Restore meldete /api/auth/userCount wieder 1, die Anmeldung mit dem bisherigen Passwort klappte, die Regel whoami.example.test stand wieder in der Liste und der curl-Aufruf mit Host-Header lieferte HTTP 200 vom Backend.

Verifizieren: Die Anmeldeseite fragt nach Benutzername und Passwort statt nach Account Setup, und curl -s -o /dev/null -w '%{http_code}' -H 'Host: IHRE-DOMAIN' http://localhost/ liefert den erwarteten Status.

Schritt 7: Zoraxy aktualisieren

Zoraxy aktualisieren Sie, indem Sie den Tag in der .env ändern und das Image neu ziehen. Sichern Sie vorher wie in Schritt 5. Der Weg wurde von v3.3.3 auf v3.3.4 getestet:

sed -i 's/ZORAXY_TAG=v3.3.3/ZORAXY_TAG=v3.3.4/' .env
docker compose pull zoraxy
docker compose up -d
curl -s http://localhost:8000/api/info/x | grep Version

Compose meldete Container zoraxy Recreated, der Endpunkt /api/info/x zeigte danach "Version": "3.3.4". Beim Start prüft Zoraxy mit Checking required config update, ob die Konfiguration migriert werden muss (Variable CFGUPGRADE, standardmäßig aktiv). Benutzerkonto und Proxy-Regel blieben erhalten, die Weiterleitung lieferte weiter HTTP 200. Allerdings war die bestehende Browser-Sitzung nach dem Update ungültig, eine erneute Anmeldung war nötig. Ein einfacher Neustart ohne Versionswechsel behielt die Sitzung dagegen. Lesen Sie vor jedem Update die Release Notes auf GitHub.

Verifizieren: docker compose ps zeigt das neue Image als healthy, /api/info/x nennt die neue Version, und Ihre Proxy-Regeln antworten wie vorher.

Troubleshooting

Symptom	Ursache und Lösung
Bind for 0.0.0.0:80 failed: port is already allocated beim Start	Ein anderer Dienst belegt Port 80 oder 443. Mit sudo ss -ltnp | grep -E ':(80|443) ' finden, stoppen, dann docker compose up -d --force-recreate. Im Test blieb nach dem Konflikt nur der whoami-Container oben, Zoraxy startete erst nach Freigabe des Ports.
HTTP-Aufruf landet per 307 auf HTTPS	Standardverhalten im HTTPS-Modus. In der Regel Allow plain HTTP access aktivieren oder direkt HTTPS nutzen.
Browser warnt vor dem Zertifikat	Es greift das selbst signierte Fallback-Zertifikat. Zertifikat über den ACME-Client anfordern; dafür müssen DNS und Port 80 von außen stimmen.
Backend gestoppt, Zoraxy liefert trotzdem HTTP 200	Im Test antwortete Zoraxy 3.3.4 bei gestopptem Backend mit HTTP 200 und leerem Inhalt statt mit einem 502. Ein Monitoring, das nur den Statuscode prüft, merkt den Ausfall nicht. Prüfen Sie im Monitoring auf einen erwarteten Inhalt oder nutzen Sie den eingebauten Uptime Monitor.
List docker container failed	Kein Docker-Socket eingebunden. Ziele von Hand eintragen (siehe Schritt 4).
Forbidden - CSRF token not found in request	Skript ohne CSRF-Token. Token aus dem Meta-Tag zoraxy.csrf.Token der Seite lesen und als Header X-CSRF-Token mitsenden, Cookies per Cookie-Jar behalten.
Nach Neuinstallation wieder Account Setup	Der Ordner config fehlt oder ist leer. Backup zurückspielen (Schritt 6), Port 8000 bis dahin sperren.

Logs finden Sie mit docker compose logs zoraxy und dauerhaft im Ordner config/log/, dort mit jeder weitergeleiteten Anfrage samt Ziel und Statuscode.

Häufige Fragen

Ist Zoraxy eine Alternative zu Nginx Proxy Manager?

Ja, beide richten sich an Admins, die Regeln lieber in einer Oberfläche pflegen. Zoraxy bringt zusätzlich Stream-Proxy, Zugriffsregeln, Uptime-Monitor, SSO-Anbindung und Plugins in einem Go-Binary mit, ohne Datenbank-Container.

Kann ich den Port der Weboberfläche ändern?

Ja, über die Variable PORT. Laut Docker-README gehört dort nur die Zahl hinein, also PORT: "8443" ohne Doppelpunkt. Passen Sie die Portzuordnung in der compose.yaml entsprechend an.

Wie schütze ich die Weboberfläche zusätzlich?

Geben Sie Port 8000 in der Firewall nur für Ihr Admin-Netz oder Ihr VPN frei oder binden Sie ihn an 127.0.0.1 und greifen per SSH-Tunnel zu. Die Variable NOAUTH schaltet die Anmeldung komplett ab und hat auf einem erreichbaren Server nichts verloren.

Fazit

Zoraxy ist ein schlanker Reverse Proxy für alle, die Hostnamen, Zertifikate und Weiterleitungen lieber klickend verwalten. Installation und erste Regel sind in wenigen Minuten erledigt, Backup und Restore beschränken sich auf einen einzigen Ordner und haben im Test einwandfrei funktioniert. Achten Sie auf drei Punkte: Admin-Konto sofort anlegen und Port 8000 abschotten, den Docker-Socket weglassen und das Backup wegen des enthaltenen Sitzungsschlüssels sicher verwahren. Wer Konfiguration lieber als Datei versioniert, greift zu Traefik oder Caddy.

Weiterführende Anleitungen und Quellen

• Traefik als Docker-Reverse-Proxy mit HTTPS einrichten
• Caddy als Reverse Proxy: automatisches HTTPS im Vergleich zu Nginx und Traefik
• Nginx als Reverse Proxy mit TLS einrichten
• Zoraxy auf GitHub
• Zoraxy Docker-README mit allen Umgebungsvariablen
• Release Notes Zoraxy v3.3.4
• Image zoraxydocker/zoraxy auf Docker Hub