ENV Variablen

ENV-Variablen (.env)

← Home · Zurück: Makefile-Referenz

Die .env im Repo-Wurzelverzeichnis ist die zentrale Steuerdatei: Name, Passwörter, Pfade, Ports, Heap-Größe, Backup-Aufbewahrung, Update-Fenster und GCP-Failover. Alle Werte fließen per make render in die Server-Configs — Details dazu in Server-Konfiguration.

Grundlagen

• .env wird niemals committet (Repo-Regel, 1:1 aus README: „.env wird niemals committet (Secrets!)"). Die .gitignore des Repos deckt .env, .env.local und docker/.env explizit ab.
• Vorlage: cp .env.example .env — dann Werte ausfüllen. Alle im Folgenden genannten Beispielwerte sind die Repo-Defaults aus .env.example (Repo-Default).
• scripts/lib/common.sh lädt die .env beim Start jedes Skripts (set -a; source .env; set +a) und setzt Fallback-Defaults, falls Werte fehlen. Diese Defaults existieren (1:1 aus common.sh): SERVER_NAME=servertest, PZ_USER=pzserver, PZ_SERVER_DIR=/opt/pzserver/server, PZ_DATA_DIR=/opt/pzserver/Zomboid, STEAMCMD_DIR=/opt/pzserver/steamcmd, BACKUP_DIR=/opt/pzserver/backups, RAM_XMX=12G, GAME_PORT=16261, DISCORD_WEBHOOK_URL= (leer), RETENTION_DAILY=7, RETENTION_WEEKLY=4 — alle (Repo-Default).
• Fehlt die .env komplett, brechen Skripte mit Guards ab: .env fehlt. Erst: cp .env.example .env und Werte setzen. (1:1 aus common.sh, need_env).

Variablen-Referenz

Server-Basis

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
SERVER_NAME	Interner Servername (Datei-Prefix aller Server-Configs)	servertest	Bestimmt servertest.ini-Namen, Sandbox- und Spawn-Datei-Präfixe	common.sh (Default), render-config.sh, systemd-Unit (-servername), docker-compose
PUBLIC_NAME	Servername in der Serverliste	ProjectZomboiD Coop	Nur Anzeige — nicht mit SERVER_NAME verwechseln	render-config.sh → PublicName
DESCRIPTION	Beschreibung in der Serverliste	Privater Coop-Server (Build 42)	—	render-config.sh → PublicDescription
MAX_PLAYERS	Maximale Spielerzahl	8	Wirkt erst nach make render + Restart	render-config.sh → MaxPlayers, docker-compose
ADMIN_PASSWORD	Passwort für In-Game-Admin-Funktionen	CHANGE_ME	Unbedingt ändern; niemals dem Server-Passwort gleichsetzen	render-config.sh → AdminPassword
SERVER_PASSWORD	Join-Passwort für Spieler	CHANGE_ME	Leer = öffentlicher Join trotz Public=false möglich (Heuristik)	render-config.sh → Password
RCON_PASSWORD	Passwort für RCON-Fernsteuerung	CHANGE_ME	Aktuelles Template hat keine ${RCON_PASSWORD}-Zeile — wird nur in der envsubst-Liste geführt (Clone-Befund). Leer lassen bricht die Update-Ansagen (announce.sh nutzt es für mcrcon)	render-config.sh (VARS-Liste), announce.sh (mcrcon -p)
RCON_PORT	TCP-Port für RCON	27015	Nicht öffentlich freigeben (siehe Ports-und-Netzwerk)	render-config.sh → RCONPort, announce.sh (mcrcon -P)
RCON_ENABLED	RCON an/aus	true/false	true ist Repo-Default — bei Nichtnutzung auf false setzen; nur true sendet die Update-Ansagen (announce.sh-Guard)	render-config.sh → RCON, announce.sh (Guard)

Pfade (Linux-Haupt-Host)

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
PZ_USER	Dedizierter Linux-User für den Dienst	pzserver	Muss existieren (docs/02: useradd -r -m -d /opt/pzserver pzserver)	common.sh, systemd-Platzhalter __PZ_USER__
PZ_HOME	Basisverzeichnis des Setups	/opt/pzserver	Konventionswert — wird von keinem Skript direkt gelesen (Clone-Befund)	nur .env.example
PZ_SERVER_DIR	Installationsverzeichnis des Dedicated Servers	/opt/pzserver/server	Änderung erfordert Neu-Installation	common.sh, install.sh, update.sh, systemd __PZ_SERVER_DIR__
PZ_DATA_DIR	Spiel-/Saves-Verzeichnis (Zomboid-Ordner)	/opt/pzserver/Zomboid	Enthält Saves — Backups greifen genau hier an	common.sh, render-config.sh, install.sh, backup.sh, restore.sh, update.sh
STEAMCMD_DIR	Installationsort von SteamCMD	/opt/pzserver/steamcmd	Änderung nur vor make install sinnvoll	common.sh, install.sh, update.sh

Java-Heap

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
RAM_XMX	Maximaler Java-Heap (-Xmx)	12G (Repo-Default)	In der systemd-Unit als -Xmx${RAM_XMX}; docker-compose als XMX — Anpassung braucht Neustart. Kopfzeile der .env.example: „Basis ~6G + 0.5G/Spieler"	common.sh, systemd-Unit, docker-compose, docs/09

Ports

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
GAME_PORT	Haupt-Spielport (DefaultPort)	16261	Firewall + Router müssen ihn freigeben	common.sh, render-config.sh → DefaultPort, healthcheck.sh, install.sh (UFW-Hinweis)
DIRECT_PORT	Zweiter UDP-Port (UDPPort)	16262	Wird oft vergessen — ohne ihn keine Verbindungen	render-config.sh → UDPPort

Discord

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
DISCORD_WEBHOOK_URL	Webhook für Alerts (Backup, Update, Crash)	URL oder leer	Leer = Benachrichtigungen deaktiviert (no-op); curl-Fehler landen nur als Warnung im Log	common.sh (notify)

Backups

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
BACKUP_DIR	Zielverzeichnis der tar.gz-Backups	/opt/pzserver/backups	Docker-Variante mountet ../backups — Pfad relativ zum docker/-Ordner	common.sh, backup.sh, restore.sh, gcp/sync-backups.sh
RETENTION_DAILY	Anzahl behaltener daily-Backups	7 (Repo-Default)	Rotation läuft nur bei backup.sh-Aufrufen	common.sh, backup.sh
RETENTION_WEEKLY	Wochen-Aufbewahrung (in * 7 Tagen)	4 (Repo-Default)	Löscht daily-Backups älter als 28 Tage (Repo-Default: 4 × 7)	common.sh, backup.sh

Update-Fenster

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
UPDATE_DAY	Wochentag des automatischen Updates	Tue	Englische Wochentagskürzel; Eintrag erst nach systemd-Installation wirksam	systemd-Platzhalter __UPDATE_DAY__ → zomboid-update.timer
UPDATE_TIME	Uhrzeit des Updates	03:00	Nur relevant, wenn der Update-Timer aktiviert ist	systemd-Platzhalter __UPDATE_TIME__ → zomboid-update.timer

GCP-Failover

Variable	Zweck	Format/Beispiel	Stolperfalle	Genutzt in
GCP_PROJECT	GCP-Projekt-ID	CHANGE_ME	Nur für Failover-Einrichtung nötig	gcp/create-instance.sh
GCP_ZONE	GCP-Zone	europe-west3-a	Bucket-Region im Skript ist fest europe-west3 (Repo-Default)	gcp/create-instance.sh
GCP_INSTANCE	Name der Failover-VM	pz-failover	Instanz wird nach Erstellung gestoppt (Konzept)	gcp/create-instance.sh
GCP_BUCKET	GCS-Bucket für Backup-Sync	pz-backups-CHANGE_ME	Muss global eindeutig sein; wird bei Bedarf angelegt	gcp/create-instance.sh, gcp/sync-backups.sh
FAILOVER_SLOTS	Spieler-Slots im Failover-Betrieb	3 (Repo-Default)	Dient als Doku/Wertebasis — startup-script.sh setzt SLOTS=3 hart (Clone-Befund)	.env.example (Wert entspricht gcp/startup-script.sh)
FAILOVER_XMX	Heap im Failover-Betrieb	8G (Repo-Default)	Dito: startup-script.sh setzt XMX=8G hart (Clone-Befund)	.env.example (Wert entspricht gcp/startup-script.sh)

Details zum Failover-Konzept: GCP-Failover.

Docker-Variablen

Der Docker-Pfad nutzt einen minimalen Satz aus docker/.env.docker.example (1:1, Repo-Default):

SERVER_NAME=servertest
MAX_PLAYERS=8
RAM_XMX=12G
ADMIN_PASSWORD=CHANGE_ME
SERVER_PASSWORD=CHANGE_ME

docker-compose.yml nimmt diese als env_file: .env auf und leitet SERVER_NAME, MAX_PLAYERS und XMX (aus RAM_XMX, Fallback 12G) als Container-Environment weiter. Alles Weitere regelt das Image. Details: Docker-Betrieb.

Empfehlungen

RAM_XMX-Größen (Host-RAM-Klasse → empfohlener Heap) — dieselbe Tabelle steht in Quickstart-Linux, Performance-Guide und Hardware-Empfehlungen (Spalten dort: „Host-RAM" und „Heap Xmx"):

Klasse	Host-RAM (Gesamt)	Empfohlenes RAM_XMX (Heap)	Quelle/Label
Small	≤ 8 GB	6–8 GB	Community-Quelle (B42-Optimierungs-Guide: b42-server-optimization-checklist)
Medium	8–24 GB	10–14 GB	Community-Quelle (B42-Optimierungs-Guide: b42-server-optimization-checklist)
Large / Modded	24+ GB	16 GB	Community-Quelle (B42-Optimierungs-Guide: b42-server-optimization-checklist)

• Faustformel: ~6 GB Basis + 0,5 GB pro Spieler (Heuristik; Kopfzeile der .env.example nennt dieselbe Formel — Repo-Default-Empfehlung)
• B42 braucht rund 2 GB mehr als B41 (Community-Quelle: Community-Beobachtung)
• Bei 16 GB Heap sollte der Host mindestens 24 GB RAM haben, damit OS und Page-Cache überleben (Heuristik) — daher steht die Large-Zeile in der Tabelle oben unter „24+ GB Host-RAM" und nicht unter „16 GB Host-RAM"
• Xms gleich Xmx setzen — das Repo übergibt -Xmx${RAM_XMX} an den Start; Xms-Gleichsetzung empfiehlt docs/09 für ProjectZomboid64.json (Repo-Default-Empfehlung)
• Heap-Tabelle auch in Performance-Guide (Abschnitt 1), Quickstart-Linux (Hardware-Empfehlung) und Hardware-Empfehlungen (inkl. CPU-/Storage-Einordnung) — alle Stellen referenzieren diese selbe Kanonik aus dem B42-Optimierungs-Guide.

ADMIN_PASSWORD vs. SERVER_PASSWORD: SERVER_PASSWORD (Password in der INI) ist das Join-Passwort, das jeder Spieler beim Verbinden eingibt. ADMIN_PASSWORD (AdminPassword) gehört dagegen den Admin-Funktionen im Spiel — genau dieser In-Game-Admin-Login-Befehl ist in dieser Doku nicht verifiziert und wird daher hier bewusst nicht angegeben (Quellen-Hinweis des Projekts). Beide Passwörter unterschiedlich und stark wählen (Heuristik).

RCON_ENABLED: RCON erlaubt Fernsteuerung (Announce-Skripte nutzen es). Der Port RCON_PORT darf nie öffentlich exponiert werden — nur lokal oder per VPN/SSH-Tunnel nutzen, Firewall-Regeln siehe Ports-und-Netzwerk (Heuristik/Best Practice, konsistent mit docs/02).

Ändern und Anwenden

Reihenfolge (aus dem Render-Verhalten von scripts/render-config.sh):

$EDITOR .env        # 1. Wert ändern
make render         # 2. Templates neu rendern -> ${PZ_DATA_DIR}/Server/
make restart        # 3. Server neu starten, damit die Config gelesen wird

Ein laufender Server liest Änderungen nicht automatisch ein — ohne Restart bleibt der alte Stand aktiv (Heuristik, abgeleitet aus dem Render-Workflow; docs/09 zeigt dasselbe Muster für RAM_XMX).

Weiter: Server-Konfiguration · GCP-Failover