Panel installieren

Das Panel ist ein Container plus PostgreSQL. Eine Compose-Datei startet beides aus den veröffentlichten Images; dein Reverse Proxy stellt HTTPS davor.

Installieren

Du brauchst eine Maschine mit Docker und dem Compose-Plugin, eine Domain, die auf sie zeigt (z. B. panel.example.com), und einen Reverse Proxy (Beispiele unten).

Kopiere compose.yml und .env.example aus dem Ordner deploy/ im Repository des Panels in einen leeren Ordner, z. B. /opt/panel.

Leg .env an und setze die zwei Pflichtwerte:

cp .env.example .env
# POSTGRES_PASSWORD=<ein langes zufälliges Passwort, z. B. von: openssl rand -hex 24>
# PANEL_PUBLIC_URL=https://panel.example.com

Starte es:
Terminal-Fenster
```
docker compose up -d
```
Der erste Start legt den Master-Key in keys/master.key und die Datenbank an.
Lass deinen Reverse Proxy auf 127.0.0.1:8080 zeigen (Beispiele).
Öffne den Setup-Link aus dem Log:
Terminal-Fenster
```
docker compose logs panel | grep setup
```
Der Link enthält das Setup-Token, damit niemand, der ein frisches Panel im Internet findet, es übernehmen kann. Der Setup-Assistent fragt, wie du das Panel nutzt (Homelab oder Hosting, siehe Überblick), und legt dein Operator-Konto und den ersten Tenant an.

Weiter: Node hinzufügen. Ein Node auf derselben Maschine: Trag sein Enrollment-Token in .env als AGENT_ENROLLMENT_TOKEN=… ein und führe docker compose --profile agent up -d aus; andere Maschinen verwenden compose.agent.yml oder den Befehl, den das Panel zeigt.

Einstellungen in `.env`

Variable	Bedeutung
`POSTGRES_PASSWORD`	das Datenbankpasswort (Pflicht)
`PANEL_PUBLIC_URL`	die Adresse, über die Agents und E-Mails das Panel erreichen, z. B. `https://panel.example.com` (Pflicht)
`PANEL_CATALOGUE_URL`	der Spielkatalog, aus dem Spiele hinzugefügt werden (Standard: der öffentliche). Auch unter Admin → Settings.
`PANEL_DOCS_URL`	die Dokumentations-Website für die Hilfe-Links des Panels (`?`), Standard: diese Seite. Auch unter Admin → Settings.
`PANEL_BIND`, `PANEL_PORT`	wo das Panel veröffentlicht wird (Standard `127.0.0.1` und `8080`)
`TRUSTED_PROXY_NETWORK`	das Netzwerk deines Reverse Proxys (Standard `172.16.0.0/12`, die Netzwerke von Docker)
`PANEL_KEYS_DIR`	der Ordner mit dem Master-Key (Standard `./keys`)
`PANEL_IMAGE`, `AGENT_IMAGE`	das Panel-Image und das Agent-Image, das der Befehl unter Add node verwendet (Standard: das veröffentlichte `latest`)
`AGENT_ENROLLMENT_TOKEN`, `AGENT_SFTP_PORT`	für den Agent auf dieser Maschine (`--profile agent`)

Login-Provider kommen in panel.env (siehe panel.env.example und E-Mail und Anmeldung). Alle Einstellungen: Umgebungsvariablen.

Der Master-Key

keys/master.key verschlüsselt die Schlüssel, die Secrets in der Datenbank schützen (Steam-Passwörter, geheime Variablen, den Push-Schlüssel), sodass ein Datenbank-Dump allein nichts preisgibt. Der Schritt init der Compose-Datei legt ihn beim ersten Start an und macht ihn nur für das Panel lesbar; einen vorhandenen ersetzt er nie.

Das Profil Hosting verlangt ihn: Die Einrichtung und Admin → Settings lehnen Hosting ohne Master-Key ab, und ein Hosting-Panel ohne ihn startet nicht. Die Secrets anderer Leute dürfen nicht allein von der Datenbank abhängen.

Reverse Proxy

Das Panel lauscht auf 127.0.0.1:8080 und erwartet für HTTPS einen Reverse Proxy davor. HTTPS braucht es für Passkeys, die Handy-App und Push-Benachrichtigungen. Egal, welchen Proxy du verwendest:

Setze TRUSTED_PROXY_NETWORK auf das Netzwerk, aus dem der Proxy verbindet, damit das Panel die echten Client-Adressen und HTTPS erkennt. Ein Proxy auf derselben Maschine, der zu 127.0.0.1:8080 verbindet, kommt aus dem Netzwerk von Docker: Der Standard passt.
Lass WebSockets durch: Die Live-Konsole und die Agents verwenden sie.
Puffere die Antworten des Konsolen-Streams nicht (das Panel sendet X-Accel-Buffering: no für nginx).
Gib den Host-Header unverändert weiter: Live-Verbindungen von einer anderen Seite werden abgelehnt, indem er mit dem Origin des Browsers verglichen wird.
Sicherheits-Header (Content-Security-Policy, X-Frame-Options, nosniff, Referrer-Policy) setzt das Panel selbst; der Proxy fügt nur HSTS hinzu, wenn du es willst.
Erlaube große Request-Bodies, oder nimm hin, dass Browser große Dateien in kleineren Teilen hochladen: Uploads passen sich an, wenn ein Proxy 413 antwortet.

Caddy

Caddy holt das Zertifikat selbst und gibt WebSockets und den Host-Header standardmäßig weiter.

panel.example.com {
  reverse_proxy 127.0.0.1:8080 {
    flush_interval -1
  }
}

nginx

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    http2 on;
    server_name panel.example.com;
    ssl_certificate     /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;
    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 1h;
    }
}

Traefik

Mit Traefik in Docker tritt das Panel dem Netzwerk von Traefik bei, statt einen Port zu veröffentlichen. Neben compose.yml eine compose.override.yml (Compose liest sie automatisch):

services:
  panel:
    networks: [default, traefik]
    labels:
      traefik.enable: "true"
      traefik.docker.network: traefik
      traefik.http.routers.panel.rule: Host(`panel.example.com`)
      traefik.http.routers.panel.entrypoints: websecure
      traefik.http.routers.panel.tls.certresolver: letsencrypt
      traefik.http.services.panel.loadbalancer.server.port: "8080"

networks:
  traefik:
    external: true

Verwende die Namen von Netzwerk, Entry Point und Certificate Resolver deines Traefik. Setze TRUSTED_PROXY_NETWORK auf den Bereich des Traefik-Netzwerks (docker network inspect traefik).

Umstieg von `compose.panel.yml`

Frühere Versionen hatten compose.panel.yml und daneben eine master.key. Die neue compose.yml behält denselben Projektnamen, die Datenbank bleibt also:

docker compose -f compose.panel.yml down
mkdir -p keys && mv master.key keys/master.key
docker compose up -d

IPv6

Die Compose-Datei schaltet IPv6 für das Netzwerk des Panels ein, sodass auch Mailserver, Registries und Nodes funktionieren, die nur über IPv6 erreichbar sind.

Health Checks

GET /health/live: Der Prozess läuft.
GET /health/ready: Die Datenbank ist erreichbar.