Umgebungsvariablen

Kopieren Sie .env.example nach .env und füllen Sie aus, was Sie brauchen. Die wenigen tatsächlich erforderlichen stehen unter Erste Schritte → Installation. Der Release-Stack hat eine eigene, kürzere env.example (an jedem GitHub-Release angehängt und unter deploy/release); jede Variable darin ist hier beschrieben, und die .env.example des Repositorys ist die vollständige Liste. Ein leerer Wert in .env fällt auf den hier genannten Standard zurück; NODE_ENV fehlt absichtlich in der Datei, da das Release-Image immer mit NODE_ENV=production läuft und jeder Eintrag hier, selbst ein leerer, das überschreiben würde.

Kern

Variable	Standard	Zweck
`PORT`	`3000`	HTTP-Port des `api`-Prozesses.
`RESTOW_PUBLIC_URL`	keiner	Öffentliche Origin, die der Browser nutzt (nur Origin), z. B. `https://app.example.com` oder `http://localhost:5173`.
`RESTOW_APP_DOMAIN`	keiner	Öffentliche App-Domain für die Caddy-Edge (automatisches Let’s-Encrypt-TLS), z. B. `app.example.com`.
`RESTOW_API_URL`	keiner	Interne API-Basis-URL.
`RESTOW_MODE`	keiner	Betriebsmodus: `local` \| `public`. Wird vom Einrichtungsassistenten gesetzt; lässt sich hier festlegen.
`RESTOW_EDITION`	`community`	Edition, bis ein Lizenzschlüssel installiert ist: `community` \| `business` \| `service_provider`.
`RESTOW_LICENSE_PUBLIC_KEY`	im Release eingebaut	Optionale Überschreibung des Ed25519-Lizenzprüfschlüssels (roh, base64url).
`RESTOW_UPDATE_CHECK_URL`	leer: der Tab Updates entscheidet	Umgebungs-Override für die Update-Prüfung: ein Releases-Endpunkt über `https` (eine GitHub-URL `.../releases` oder `.../releases/latest` oder eine Releases-API von Forgejo oder Gitea). Ist er gesetzt, hat er Vorrang vor dem Tab unter Einstellungen, Updates: Die Prüfung ist an, die Quelle ist diese URL und dort schreibgeschützt, und ein gespeichertes Token wird nicht an sie gesendet. Leer heißt: Der Tab entscheidet, und die Prüfung ist aus, bis eine Administration sie einschaltet. Gelesen wird nur die Release-Liste; es werden keine Installationsdaten gesendet. Siehe Updates.
`LOG_LEVEL`	`info`	Log-Level von Worker und Scheduler: `debug` \| `info` \| `warn` \| `error`.
`RESTOW_DOCS_TROUBLESHOOTING_URL`	`https://docs.restowbackup.com/administrators/troubleshooting/`	Die Seite, auf die die Fehlererklärungen in der Web-Oberfläche für weitere Hilfe verweisen. Richten Sie sie auf Ihr eigenes Runbook, falls Sie eines pflegen.

RESTOW_VERSION (die laufende Version) wird zur Build-Zeit ins Image geschrieben; setzen Sie sie nicht in .env: ein leerer Wert dort würde sie verbergen.

Release-Images und Updater

Variable	Standard	Zweck
`RESTOW_IMAGE`	keiner (im Release-Stack erforderlich)	Das Anwendungs-Image mit Version, genutzt von `api`, `worker`, `scheduler` und dem Updater, zum Beispiel `ghcr.io/restow-backup/restow:0.1.0`. Im Quell-Stack lassen Sie es leer: Compose startet dann das selbst gebaute Image `restow:local`. Der optionale Updater schreibt diese Zeile.
`RESTOW_WEB_IMAGE`	keiner (im Release-Stack erforderlich)	Das Web-Image mit der Caddy-Edge, zum Beispiel `ghcr.io/restow-backup/restow-web:0.1.0`. Im Quell-Stack leer: `restow-web:local`. Auch diese Zeile schreibt der Updater.
`RESTOW_PROJECT_DIR`	`/srv/restow`	Absoluter Pfad auf dem Host des Verzeichnisses, das `docker-compose.yml` und `.env` enthält, zum Beispiel `/opt/restow`. Nur der optionale Updater braucht ihn; er bindet das Verzeichnis unter demselben Pfad ein.
`RESTOW_UPDATER_URL`	`http://updater:8090`	Wo die `api` den optionalen Updater sucht. Dort antwortet nichts, solange das Profil `updater` nicht läuft.

Der Updater (docker compose --profile updater up -d, Opt-in) bindet den Docker-Socket ein, und der ist auf dem Host gleichbedeutend mit root; lesen Sie zuerst Updates. Die folgenden Variablen liest nur der Updater-Container (ROLE=updater). Der Dienst updater bekommt keine .env; es gelten daher die Standardwerte, solange Sie eine Variable nicht unter environment dieses Dienstes in der Compose-Datei ergänzen.

Variable	Standard	Zweck
`RESTOW_UPDATER_PROJECT_DIR`	aus `RESTOW_PROJECT_DIR` gesetzt	Absoluter Host-Pfad des Compose-Projekts, unter demselben Pfad eingebunden.
`RESTOW_UPDATER_IMAGE_REPOSITORY`	`ghcr.io/restow-backup/restow`	Repository des Anwendungs-Images für den Modus `image`.
`RESTOW_UPDATER_WEB_IMAGE_REPOSITORY`	`ghcr.io/restow-backup/restow-web`	Repository des Web-Images für den Modus `image`.
`RESTOW_UPDATER_HEALTH_TIMEOUT_SECONDS`	`600`	Wie lange auf die neue api gewartet wird (Migrationen können dauern).
`RESTOW_UPDATER_MIN_FREE_MB`	`1024`	Erforderlicher freier Platz im Volume des Updaters.
`RESTOW_UPDATER_CLI_IMAGE`	`docker:27-cli`	Image, mit dem `docker` und `docker compose` ausgeführt werden.
`RESTOW_UPDATER_SOURCE_HOSTS`	jeder `https`-Host	Optionale, kommagetrennte Liste von Hosts, von denen ein `source`-Archiv heruntergeladen werden darf.

Edge (Caddy)

Variable	Standard	Zweck
`RESTOW_EDGE_TRUSTED_PROXIES`	nur Loopback	Gegenstellen, deren `X-Forwarded-For` die Edge behält (und ergänzt), statt es durch die eigene Adresse der Gegenstelle zu ersetzen: durch Leerzeichen getrennte CIDR-Bereiche oder `private_ranges`. Nur nötig, wenn ein weiterer Reverse Proxy vor Caddy steht.
`RESTOW_EDGE_HSTS`	`false`	`true` sendet `Strict-Transport-Security` (mit `includeSubDomains`). Setzen Sie es erst, wenn `RESTOW_APP_DOMAIN` eine echte, öffentlich auflösbare Domain ist, für die die Edge ihr eigenes gültiges TLS-Zertifikat terminiert (öffentlicher Modus). Der Wert wird wörtlich verglichen, muss also genau kleingeschrieben `true` lauten; alles andere lässt HSTS aus. Setzen Sie es nie für eine lokale oder IP-Installation: Browser bestünden dann auf HTTPS für einen Host, der es womöglich nie anbietet.

Datenbank

Variable	Standard	Zweck
`POSTGRES_PASSWORD`	keiner (erforderlich)	Passwort für den Postgres-Superuser, den Docker Compose anlegt. `POSTGRES_USER`/`POSTGRES_DB` sind standardmäßig `restow`.
`DATABASE_MIGRATION_URL`	keiner (erforderlich)	Der Datenbankeigentümer; führt nur Migrationen aus.
`DATABASE_URL`	keiner (erforderlich)	Die Anwendungsrolle, der Row Level Security unterliegt. Der Migrationsschritt legt sie mit dem hier angegebenen Namen/Passwort an.
`DATABASE_PROVIDER_URL`	keiner (erforderlich)	Die Installationsrolle (`BYPASSRLS`), genauso angelegt.

Drei Rollen, drei Verbindungszeichenfolgen, drei verschiedene Passwörter. Siehe Erste Schritte → Die drei Datenbank-Rollen. Die Prozesse starten nicht, wenn sich herausstellt, dass DATABASE_URL ein Superuser ist oder RLS umgehen kann.

Secrets und Kryptografie

Erzeugen Sie beide mit openssl rand -base64 32.

Variable	Zweck
`RESTOW_MASTER_KEY`	Erforderlich. 32-Byte-Schlüsselverschlüsselungsschlüssel (KEK), base64. Umschließt jeden Mandantenschlüssel; bewahren Sie eine Kopie offline auf. Siehe Restow selbst sichern.
`BETTER_AUTH_SECRET`	Erforderlich. Secret für die eigenen Tokens und Sitzungen des Auth-Systems.

Microsoft Entra (mandantenübergreifende App für Backup, Client Credentials)

Variable	Zweck
`ENTRA_CLIENT_ID`	Die Anwendungs-ID (Client-ID) der Backup-App.
`ENTRA_CLIENT_SECRET`	Client-Secret-Zugangsdaten (füllen Sie genau dieses oder den Zertifikatspfad aus).
`ENTRA_CLIENT_CERT_PATH`	Optional: Zertifikatspfad (PEM, privater Schlüssel + Zertifikat) statt eines Secrets. Wird bevorzugt genutzt, wenn beide gesetzt sind.
`ENTRA_AUTHORITY_HOST`	Optional: Authority-Host für souveräne Clouds. Standard `https://login.microsoftonline.com`.
`DIRECTORY_FULL_SYNC_HOURS`	Standard `24`. Stunden zwischen vollständigen Verzeichnis-Enumerationen; dazwischen laufen inkrementelle Abgleiche.

Wie Sie diese Werte erhalten, steht unter Erste Schritte → Microsoft 365 verbinden.

Endnutzer-SSO (delegiertes OIDC über Entra `common`)

Variable	Zweck
`ENTRA_SSO_CLIENT_ID`	Client-ID einer separaten App-Registrierung, die nur für die Anmeldung von Endnutzern genutzt wird (delegiert `openid profile email`, kein Datenzugriff).
`ENTRA_SSO_CLIENT_SECRET`	Deren Client-Secret.

Benachrichtigungen (Mail-Transport)

Variable	Zweck
`MAIL_TRANSPORT`	`smtp` \| `graph`.
`SMTP_HOST`, `SMTP_PORT`	SMTP-Server und -Port.
`SMTP_SECURE`	`true` für implizites TLS (wird auch bei Port 465 angenommen); sonst STARTTLS.
`SMTP_USER`, `SMTP_PASSWORD`	Optionale SMTP-Zugangsdaten.
`SMTP_FROM`	Absenderadresse.
`GRAPH_MAIL_SENDER`	Absenderpostfach für den Microsoft-Graph-`sendMail`-Transport.
`GRAPH_MAIL_TENANT_ID`	Entra-Mandant des Absenderpostfachs, falls der Einrichtungsassistent keinen nennt.

IMAP-Quellen

Variable	Standard	Zweck
`IMAP_ALLOW_INSECURE`	`false`	Erlaubt IMAP-Quellen ohne TLS. Nur Entwicklung; niemals in Produktion.
`IMAP_ALLOW_PRIVATE_NETWORKS`	nur vom Provider gespeicherte	`true` lässt jede IMAP-Quelle Loopback und private Netze erreichen; standardmäßig können das nur von einer Provider-Administration gespeicherte Server, und Mandanten-Administrationen sind auf öffentliche Server beschränkt.

Speicher

Variable	Standard	Zweck
`STORAGE_TARGET`	`local`	Zieltyp: `local` \| `s3`.
`STORAGE_LOCAL_PATH`	`/data/chunks`	Pfad im Container für das lokale Standardziel.
`STORAGE_COPY_LOCAL_PATH`	keiner	Optionales zweites Ziel, in das jeder Standard-Schreibvorgang zusätzlich kopiert wird (eine eingebundene NFS-/SMB-Freigabe).
`S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_PREFIX`	keiner	S3-kompatibles Ziel (Hetzner Object Storage, Garage, Wasabi, B2, AWS, …).
`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`	keiner	S3-Zugangsdaten.
`S3_FORCE_PATH_STYLE`	`true`	`false` für virtuell gehostete Bucket-Adressierung.

Mail-Datei-Import und -Export

Alles optional. Siehe Mail-Dateien importieren und exportieren.

Variable	Standard	Zweck
`RESTOW_IMPORT_DIR`	`./import` neben `docker-compose.yml`	Host-Verzeichnis, das in `api` und `worker` schreibgeschützt unter `/var/lib/restow/import` eingehängt wird. Jeder Mandant nutzt seinen eigenen Unterordner `<Verzeichnis>/<Mandanten-Slug>/`, den Sie selbst anlegen.
`IMPORT_DIR`	`/var/lib/restow/import`	Der Pfad in den Containern. Ändern Sie ihn nur zusammen mit dem Mount oben.
`IMPORT_MAX_FILE_BYTES`	10 GiB	Größte Datei, die der Upload im Browser annimmt, in Byte.
`IMPORT_UPLOAD_TTL_HOURS`	`48`	Stunden, die ein unfertiger oder ungenutzter Upload aufbewahrt wird, bevor er gelöscht wird.
`IMPORT_SEGMENT_BYTES`	8 MiB	Größe eines Upload-Stücks in Byte (erlaubt: 64 KiB bis 32 MiB).
`IMPORT_MAX_MESSAGE_BYTES`	256 MiB	Größte einzelne Nachricht, die in den Speicher gelesen wird.
`EXPORT_TTL_HOURS`	`24`	Stunden, die ein fertiger Export heruntergeladen werden kann, bevor seine Datei gelöscht wird.

Endpoint-Backup (Server und Clients)

Alles optional. Die Standardwerte passen zum Release-Stack; nur ein eigenes Image braucht Änderungen. Siehe Endpoint-Backup.

Variable	Standard	Zweck
`RESTIC_BINARY`	`restic` aus dem `PATH`	Die restic-Binärdatei, die `api` und `worker` für Aufbewahrung, Prüfungen, Restore-Tests, Durchsuchen und Downloads ausführen. Das Image liefert sie unter `/usr/local/bin/restic` mit.
`RESTOW_RESTIC_CACHE_DIR`	der Temp-Ordner	Wo restic seine Caches je Endpoint ablegt. Ein Ordner auf einem Volume, zum Beispiel `/data/restic-cache`, erhält sie über Neustarts hinweg und beschleunigt das Durchsuchen.
`RESTOW_AGENT_DIR`	`/srv/agent`	Wo das Image die Agent-Binärdateien ablegt.
`RESTOW_AGENT_INSTALL_DIR`	`/srv/agent/install`	Wo das Image die Installationsskripte ablegt.

Worker

Variable	Standard	Zweck
`WORKER_CONCURRENCY`	`2`	Parallele Jobs je Warteschlange in einem Worker-Prozess.
`WORKER_TENANT_CONCURRENCY`	`2`	Parallele Jobs je Mandant in einem Worker-Prozess.
`WORKER_POLL_SECONDS`	`2`	Polling-Intervall von pg-boss.
`WORKER_SHUTDOWN_TIMEOUT_MS`	`30000`	Wie lange das Herunterfahren auf einen Prüfpunkt laufender Jobs wartet.
`WORKER_CANCEL_POLL_MS`	`15000`	Wie oft ein laufender Job prüft, ob er abgebrochen wurde.
`WORKER_PROGRESS_FLUSH_ITEMS`	`50`	Fortschritt wird alle N Elemente geschrieben …
`WORKER_PROGRESS_FLUSH_MS`	`2000`	… oder mindestens alle M Millisekunden.

Webhooks (werden vom Worker zugestellt)

Variable	Standard	Zweck
`WEBHOOK_POLL_MS`	`5000`	Polling-Intervall für fällige Zustellungen.
`WEBHOOK_CONCURRENCY`	`4`	Parallele Zustellungen.
`WEBHOOK_TIMEOUT_MS`	`10000`	Timeout je Versuch.
`RESTOW_WEBHOOK_ALLOW_PRIVATE`	abgelehnt	`true` erlaubt Webhook-Ziele in Loopback- und privaten Netzen.

Scheduler

Variable	Standard	Zweck
`SCHEDULER_TICK_MS`	`30000`	Tick-Intervall.
`SCHEDULER_LEADER_RETRY_MS`	`15000`	Leader-Wiederholung.
`SCHEDULER_BATCH_SIZE`	`200`	Fällige Zeitpläne je Tick.
`SCHEDULER_DEFER_MS`	`3600000`	Verzögerung, bevor ein nicht planbarer Zeitplan (ungültiger Cron-Ausdruck) erneut betrachtet wird.
`SCHEDULER_LOCK_KEY`	keiner	Postgres-Advisory-Lock-Key für die Leader-Wahl; nur ändern, wenn zwei Installationen eine Datenbank teilen.

Journal-SMTP-Empfänger (Archiv)

Alles optional; der Empfänger ist aus, bis JOURNAL_SMTP_PORT gesetzt ist. Einrichtung, DNS, Port 25 und Zertifikat: Exchange-Journaling.

Variable	Standard	Zweck
`JOURNAL_SMTP_PORT`	keiner (Empfänger aus)	Port, auf dem der SMTP-Journal-Empfänger des Archivs lauscht. Der Empfänger startet nur, wenn dieser Wert gesetzt ist. Exchange Online liefert an Port 25. Die `.env.example` des Repositorys setzt 25; die `env.example` des Release-Stacks lässt ihn leer.
`JOURNAL_SMTP_BIND`	`127.0.0.1`	Nur im Release-Stack: die Host-Adresse, auf der der Port veröffentlicht wird. Setzen Sie sie zusammen mit `JOURNAL_SMTP_PORT=25` auf `0.0.0.0`, um Journal-Reports von Exchange Online zu empfangen; sie müssen den Empfänger direkt erreichen, nicht über Caddy.
`JOURNAL_HOSTNAME`	keiner	Der Hostname, an den Exchange Online zustellt, zum Beispiel `archive.example.com`: nur der Hostname, ohne Schema, Pfad, Port und Mailadresse. Er bildet die Journal-Adressen der Mandanten, `journal+<token>@<Host>`; veröffentlichen Sie ihn im DNS. Ohne gültigen Wert zeigt Restow keine vollständige Adresse.
`JOURNAL_TLS_CERT_PATH`	keiner	Pfad zur Zertifikatskette (PEM, Blatt zuerst) einer öffentlich vertrauten Stelle, passend zu `JOURNAL_HOSTNAME`. Exchange Online verlangt TLS, daher startet der Empfänger ohne Zertifikat nicht und greift nie auf ein eingebautes zurück. Im Release-Stack: `/etc/restow/journal-tls/fullchain.pem`.
`JOURNAL_TLS_KEY_PATH`	keiner	Pfad zum privaten Schlüssel (PEM, nicht mit Passphrase verschlüsselt), der zum Zertifikat gehört. Beide Pfade müssen gesetzt sein. Im Release-Stack: `/etc/restow/journal-tls/privkey.pem`.
`JOURNAL_TLS_DIR`	`./journal-tls`	Compose-Datei beider Stacks: das Host-Verzeichnis, das schreibgeschützt in die `api` unter `/etc/restow/journal-tls` eingehängt wird. Legen Sie `fullchain.pem` und `privkey.pem` dorthin. Erneuerte Dateien werden innerhalb von fünf Minuten ohne Neustart übernommen.
`JOURNAL_ALLOW_INSECURE`	leer (aus)	`true` startet den Empfänger ohne Zertifikat und ohne STARTTLS anzubieten. Nur lokale Entwicklung, nie in Produktion: Exchange Online stellt an so einen Empfänger nicht zu, und Mail liefe unverschlüsselt durchs Netz. Wird ignoriert, solange ein Zertifikat konfiguriert ist.
`JOURNAL_MAX_SIZE_MB`	`150`	Größter angenommener Journal-Report, in MB. Größere Reports werden abgewiesen.