Quickstart Linux

Quickstart Linux

← Home

Dieser Guide führt in 7 Schritten von einem leeren Debian-/Ubuntu-Host zum laufenden Project-Zomboid-B42-Coop-Server. Der Linux-Host ist der Haupt-Host des Projekts; Windows-Rollen deckt Setup-Windows ab.

Voraussetzungen

• Debian/Ubuntu-basierter Linux-Host mit sudo-Rechten (Empfehlung der Repo-Doku, docs/02-setup-linux.md)
• Pakete: curl, tar, python3-yaml, gettext-base (liefert envsubst); optional mcrcon und shellcheck (Paketliste 1:1 aus docs/02-setup-linux.md)
• Git zum Klonen des Repos

Hardware-Empfehlung

Host-RAM-Klasse → empfohlener Heap (RAM_XMX). Dieselbe Kanonik steht in ENV-Variablen, Performance-Guide und Hardware-Empfehlungen (Spalten dort: „Host-RAM" und „Heap Xmx") — Quelle ist der B42-Optimierungs-Guide b42-server-optimization-checklist.md.

Ausbaustufe	Host-RAM (Gesamt)	Heap Xmx (RAM_XMX)	Typischer Einsatz
Small	bis 8 GB	6–8 GB	Testserver, 1–2 Spieler, wenige Mods
Medium	8–24 GB	10–14 GB	Standard-Coop-Betrieb (Zielbild dieses Repos)
Large (stark modded)	24+ GB	16 GB	Viele Karten/Mods, volle Spielerzahl

Die Repo-Doku selbst empfiehlt 12–16 GB RAM und NVMe (Repo-Default der Empfehlung, docs/02-setup-linux.md).

Faustformel für den Java-Heap: ca. 6 GB Basis + 0,5 GB pro Spieler (Heuristik; wird auch als Kommentar in .env.example gepflegt). B42 braucht gegenüber B41 etwa 2 GB mehr (Community-Quelle: Community-Beobachtung). Wer z. B. 16 GB Heap fährt, sollte dem Host mindestens 24 GB RAM gönnen, damit OS und Page-Cache leben können (Heuristik) — daraus folgt, dass die Large-Zeile (16 GB Heap) Hosts mit „24+ GB Host-RAM" voraussetzt, nicht „16 GB Host-RAM". Das Repo setzt als Default RAM_XMX=12G (Repo-Default, .env.example). Heap-Tabellen siehe auch Performance-Guide, ENV-Variablen und Hardware-Empfehlungen (alle Stellen referenzieren dieselbe Kanonik aus dem B42-Optimierungs-Guide).

Ports

Der Server nutzt GAME_PORT=16261 und DIRECT_PORT=16262 (Repo-Default, .env.example). Beide müssen erreichbar sein — Firewall und Router weiter unten in Schritt 5 bzw. auf Ports-und-Netzwerk (dort auch der Quellenkonflikt 16261 UDP vs. TCP).

Steam-Account

Kein eigener Steam-Account nötig: Die Installation nutzt den anonymous-Login von SteamCMD (Community-Quelle: community-dokumentiertes SteamCMD-Verhalten; das Repo verwendet ihn in install.sh).

Schritt 1 — Repo klonen

git clone <repo-url> ProjectZomboiD && cd ProjectZomboiD

Optional und empfohlen: ein dedizierter Systemuser für den Serverbetrieb (1:1 aus docs/02-setup-linux.md):

sudo useradd -r -m -d /opt/pzserver pzserver  # dedizierter User

Schritt 2 — .env anlegen

cp .env.example .env && $EDITOR .env

Mindestens setzen:

Variable	Bedeutung
SERVER_NAME	Name der Server-Instanz (Default servertest, Repo-Default) — steuert -servername sowie die Namen von Sandbox- und Spawn-Dateien; die Haupt-INI heißt immer servertest.ini (Template-Basisname, Repo-Verhalten render-config.sh; Details Architektur)
ADMIN_PASSWORD	In-Game-Admin-Zugang; bleibt CHANGE_ME → nicht funktional
SERVER_PASSWORD	Spieler-Passwort für den Join
RCON_PASSWORD	Pflicht, solange RCON_ENABLED=true ist (Default, Repo-Default)

Alle weiteren Variablen (Pfade, Ports, Backup-Retention, Discord, GCP) erklärt ENV-Variablen. .env wird niemals committet (Repo-Regel: Secrets).

Schritt 3 — sudo make install

sudo make install    # SteamCMD + App 380870 + Configs

sudo, weil die Default-Pfade unter /opt/pzserver liegen (Repo-Default, .env.example). Das Skript scripts/install.sh ist idempotent — mehrfach ausführen schadet nicht (Repo-Verhalten, install.sh). Es tut Folgendes (1:1 aus install.sh):

1. Abhängigkeiten prüfen (curl, tar)
2. SteamCMD nach $STEAMCMD_DIR installieren, falls fehlt
3. Verzeichnisse $PZ_SERVER_DIR, $PZ_DATA_DIR, $BACKUP_DIR anlegen
4. Dedicated Server über SteamCMD laden und validieren (App-ID 380870 — Steam-App-ID des PZ Dedicated Servers, so vom Repo verwendet)
5. Configs rendern (render-config.sh) und Modliste generieren (mods-generate.sh)

Zeitbedarf: der erste Lauf lädt den kompletten Dedicated Server per SteamCMD inklusive Validierung — plant je nach Anbindung mehrere Minuten bis etwa eine halbe Stunde ein (Heuristik). Disk-Bedarf: als Größenordnung dient die Boot-Disk der GCP-Failover-Instanz im Repo mit 50 GB (Repo-Default, gcp/create-instance.sh); lokal für Server + Workshop-Mods + wachsende Backups mindestens ebenso viel einplanen (Heuristik).

Schritt 4 — make mods

make mods    # Modliste validieren + generieren

Läuft zuerst mods-validate.sh (prüft Duplikate und Dep-TODOs) und dann mods-generate.sh (YAML → WorkshopItems=/Mods=/Map= nach config/generated/workshop-items.txt, sortiert nach Load-Order-Kategorien) (Repo-Verhalten, Makefile). Details: Mods-Referenz.

Schritt 5 — systemd aktivieren

Basiert auf systemd/README.md, hier aber vollständig: Die Repo-README zeigt nur das Templating und die Installation von zomboid.service — die Timer-/Service-Units werden analog installiert, und auch __UPDATE_DAY__/__UPDATE_TIME__ (in zomboid-update.timer) müssen ersetzt werden, sonst startet der Update-Timer nie. Platzhalter je Datei (1:1 aus den Unit-Dateien): zomboid.service (__PZ_USER__, __REPO__, __PZ_SERVER_DIR__), zomboid-backup.service und zomboid-update.service (je __REPO__), zomboid-update.timer (__UPDATE_DAY__, __UPDATE_TIME__), zomboid-backup.timer (keine).

export REPO=$(pwd)
# Benoetigte Werte aus .env auslesen (kein 'source', da .env-Zeilen unquotierte
# Sonderzeichen enthalten koennen; Auslesen per grep: Heuristik)
PZ_USER=$(grep -E '^PZ_USER=' .env | cut -d= -f2-)
PZ_SERVER_DIR=$(grep -E '^PZ_SERVER_DIR=' .env | cut -d= -f2-)
UPDATE_DAY=$(grep -E '^UPDATE_DAY=' .env | cut -d= -f2-)
UPDATE_TIME=$(grep -E '^UPDATE_TIME=' .env | cut -d= -f2-)

for u in zomboid.service zomboid-backup.service zomboid-backup.timer \
         zomboid-update.service zomboid-update.timer; do
  sed -e "s|__PZ_USER__|${PZ_USER}|" -e "s|__REPO__|${REPO}|" \
      -e "s|__PZ_SERVER_DIR__|${PZ_SERVER_DIR}|" \
      -e "s|__UPDATE_DAY__|${UPDATE_DAY}|" -e "s|__UPDATE_TIME__|${UPDATE_TIME}|" \
      "systemd/$u" | sudo tee "/etc/systemd/system/$u" >/dev/null
done
sudo systemctl daemon-reload
sudo systemctl enable --now zomboid zomboid-update.timer zomboid-backup.timer

Differenz zur Repo-Doku: systemd/README.md zeigt nur den Service — Timer analog (Repo-Stand; die Schleife oben installiert alle fünf Units). Unbenutzte sed-Ersetzungen in Dateien ohne den jeweiligen Platzhalter sind harmlos (sed findet dann nichts zu ersetzen).

Die Timer fahren standardmäßig das Backup um 04:00 Uhr (zomboid-backup.timer, Repo-Default laut Unit-Datei) und das Update im Fenster UPDATE_DAY/UPDATE_TIME (Repo-Defaults: Tue 03:00, .env.example). Zusätzlich den Watchdog als Cron eintragen (minütlich, Repo-Vorgabe aus systemd/README.md):

* * * * * /pfad/zum/repo/scripts/monitor.sh

Firewall (1:1 aus docs/02-setup-linux.md):

sudo ufw allow 16261/udp && sudo ufw allow 16262/udp
sudo ufw allow from <deine-ip> to any port 27015 proto tcp   # RCON nur intern

Im Router UDP 16261 + 16262 auf die interne IP des Hosts weiterleiten (Anleitung docs/02-setup-linux.md). Hintergrund zu Protokollen: Ports-und-Netzwerk.

Schritt 6 — Erste Verbindung

Im Project-Zomboid-Client (Build 42 Stable, gleicher Branch wie der Server — Community-Quelle) über den Server-Browser per IP:16261 verbinden und das SERVER_PASSWORD eingeben (Port = GAME_PORT, Repo-Default). Mods zieht der Client beim ersten Join automatisch (Community-Quelle: Standard-Verhalten des Spiels; docs/03-setup-windows-client.md). ADMIN_PASSWORD wird vom Server vorgehalten (Repo-Default der Variable, .env.example); der exakte Login-Weg als Admin ist in dieser Doku nicht verifiziert — die clientseitige Prozedur unterscheidet sich je nach Version (Community-Quelle: unspezifisch).

Schritt 7 — Verifikation

make status       # systemd-Status + Healthcheck
make healthcheck  # Healthcheck einzeln

Gesund sieht so aus (Kriterien 1:1 aus healthcheck.sh):

• OK: Server-Prozess aktiv — der Serverprozess läuft
• OK: UDP 16261 gebunden — der Spiel-Port ist erreichbar (kurz nach dem Start kann er noch fehlen, solange der Server bootet)
• keine Meldung FAIL: Kritische Fehler im Log — die letzten 5 Minuten Journal enthalten kein OutOfMemory, Exception in thread oder FATAL (5-Minuten-Fenster, Repo-Verhalten healthcheck.sh)

Live mitverfolgen:

make logs    # journalctl -u zomboid -f

Stolperfallen

Falle	Symptom	Abhilfe
.env nie angepasst	Passwörter bleiben CHANGE_ME (Repo-Default-Platzhalter)	Schritt 2 sauber durchführen; ENV-Variablen
Ports zu / falsch geroutet	Client findet den Server nicht	Firewall-Regeln + Router-Weiterleitung prüfen: Ports-und-Netzwerk
Erster Start „hängt"	Kein UDP-Port, Healthcheck warnt	Weltgenerierung und erster Boot dauern einfach — Logs beobachten, warten (Heuristik)
Workshop-Downloads beim ersten Join	Ladebildschirm stockt	Client lädt alle Server-Mods vom Workshop — Zeit einplanen; bei „Workshop version mismatch": Steam → Dateien prüfen (Community-Quelle: docs/03)
Keine sudo-Session für make install	Makefile-Ziel scheitert auf Rechte	sudo make install nutzen, da /opt/pzserver Root gehört (Repo-Default-Pfade)
python3-yaml fehlt	mods-generate bricht mit FEHLER ab	sudo apt install python3-yaml (Fehlermeldung nennt das Paket, mods-generate.sh)
systemd-Unit ungetempt	Service startet nicht / falsche Pfade	Schritt 5 exakt ausführen — Platzhalter müssen vor der Installation ersetzt sein (systemd/README.md)

Weiter

• Architektur — was die Schritte unter der Haube bewirken
• Setup-Windows — Windows-Clients und Admin-/Testmaschine
• Makefile-Referenz — alle weiteren make-Targets
• Vertieft in Repo: docs/02-setup-linux.md, README.md