Makefile Referenz

Makefile-Referenz — das Server-CLI

← Home

make ist der Einstieg für alle Betriebstätigkeiten dieses Repos: Installation, Konfiguration rendern, Mods verwalten, Start/Stop, Updates, Backups, Healthcheck, GCP-Failover-Sync. Alles läuft über dieselben 16 Targets (Anzahl: Repo-Default, 1:1 aus dem Makefile).

Ohne Argument zeigt make die Hilfe an — das Makefile setzt .DEFAULT_GOAL := help (Repo-Default):

make          # identisch zu: make help

Überblick: alle Targets

Target	Befehl dahinter	Kurzbeschreibung
help	grep über die ##-Kommentare des Makefiles	Alle Befehle anzeigen (Default-Ziel)
install	bash scripts/install.sh	Erstinstallation (SteamCMD, App 380870, Verzeichnisse)
render	bash scripts/render-config.sh	Configs aus Templates + .env generieren
mods	bash scripts/mods-validate.sh && bash scripts/mods-generate.sh	Modliste aus mods.yaml generieren + validieren
spawns	bash scripts/spawns-generate.sh	Spawn-Configs aus spawns.yaml generieren
validate	bash scripts/mods-validate.sh + shellcheck	mods.yaml + Shell-Skripte pruefen
start	sudo systemctl start zomboid	Server starten (systemd)
stop	sudo systemctl stop zomboid	Server stoppen
restart	sudo systemctl restart zomboid	Server neustarten
status	sudo systemctl status zomboid --no-pager || true + bash scripts/healthcheck.sh || true	Server-Status + Healthcheck
logs	sudo journalctl -u zomboid -f	Live-Logs anzeigen
update	bash scripts/update.sh	Sicheres Update (Backup -> Update -> Healthcheck -> Rollback)
backup	bash scripts/backup.sh	Manuelles Backup
restore	bash scripts/restore.sh	Backup wiederherstellen (interaktiv)
healthcheck	bash scripts/healthcheck.sh	Healthcheck einzeln ausfuehren
failover-sync	bash gcp/sync-backups.sh	Backups in GCP-Bucket spiegeln

Alle Befehle und Beschreibungen: Repo-Default (1:1 aus dem Makefile).

Details je Target

make help

make help

Listet alle Targets mit ihren ##-Kurzbeschreibungen auf (Repo-Default). Erster Anlaufpunkt, wenn man ein Kommando vergessen hat.

make install

sudo make install

Backend scripts/install.sh (idempotent, mehrfach ausführbar — Skriptkopf):

1. Prüft Abhängigkeiten curl und tar
2. Installiert SteamCMD nach ${STEAMCMD_DIR}, falls weder steamcmd im PATH noch ${STEAMCMD_DIR}/steamcmd.sh existiert (Download als tar.gz von der Steam-CDN, entpackt ins Zielverzeichnis)
3. Legt ${PZ_SERVER_DIR}, ${PZ_DATA_DIR}, ${BACKUP_DIR} an (mkdir -p)
4. Lädt/validiert den Dedicated Server: steamcmd.sh +force_install_dir $PZ_SERVER_DIR +login anonymous +app_update 380870 validate +quit
5. Rendert Configs (render-config.sh) und generiert die Modliste (mods-generate.sh)

Typische Ausgabe (Logformat aller Skripte, 1:1 aus common.sh: [YYYY-MM-DD HH:MM:SS] [INFO] <msg>): [INFO] === ProjectZomboiD Installation === und am Ende Installation fertig. plus nächste Schritte (systemd, Firewall). Benutzen bei Erstinstallation und nach Korrekturen an Pfaden oder .env. sudo empfohlen, weil die Standardpfade unter /opt/pzserver liegen (Repo-Quickstart im README nutzt sudo make install).

make render

make render

Backend scripts/render-config.sh: rendert alle config/templates/*.tmpl per envsubst mit 12 .env-Variablen nach ${PZ_DATA_DIR}/Server/, kopiert das Sandbox-Preset als ${SERVER_NAME}_SandboxVars.lua und die Spawn-Dateien (generierte haben Vorrang). Typische Ausgabe: Gerendert: /opt/pzserver/Zomboid/Server/servertest.ini und Sandbox-Preset 'coop-balanced' aktiv. — Details: Server-Konfiguration. Benutzen nach jeder .env- oder Template-Änderung, danach make restart.

make mods

make mods

Backend: erst mods-validate.sh (prüft mods.yaml auf doppelte workshop_id/mod_id sowie fehlende oder deaktivierte Abhängigkeiten aktiver Mods — solche harten Fehler → Exit 1; TODO-Platzhalter-Workshop-IDs im Bereich 3600000000–3600000099 erzeugen nur eine Warnung), dann mods-generate.sh (erzeugt config/generated/workshop-items.txt mit WorkshopItems=/Mods=/Map= in Kategorie-Load-Order library → framework → map → gameplay → qol, B42-Backslash vor jeder Mod-ID, Muldraugh, KY immer zuletzt in der Map-Zeile). Typische Ausgabe: [mods-validate] OK - 8 aktive Mods, keine Fehler (Zahl beispielhaft, abhängig von mods.yaml). Benutzen nach jeder Änderung an mods.yaml. Details: Mods-Referenz.

make spawns

make spawns

Backend scripts/spawns-generate.sh: erzeugt aus spawns.yaml die Lua-Dateien servertest_spawnregions.lua und servertest_<key>.lua unter config/generated/spawns/. Typische Ausgabe: [spawns-generate] servertest_ravencreek.lua: N Punkte und [spawns-generate] OK -> .../config/generated/spawns. Danach make render ausführen, damit die Dateien ins Serververzeichnis kopiert werden. Details: Spawn-System.

make validate

make validate

Backend: mods-validate.sh (wie oben) plus shellcheck scripts/*.sh scripts/lib/*.sh, falls shellcheck installiert ist — sonst erscheint shellcheck nicht installiert - uebersprungen (1:1 aus dem Makefile). Benutzen vor Commits; dieselben Checks laufen in der CI (Repo-Default: .github/workflows/ci.yml prüft shellcheck + mods-validate).

make start / stop / restart

sudo make start
sudo make stop
sudo make restart

Direkte systemd-Aufrufe (sudo systemctl start|stop|restart zomboid, 1:1 aus dem Makefile). Voraussetzung: die Unit ist installiert laut systemd/README.md (Platzhalter ersetzen, systemctl enable --now zomboid). Das sudo steht bereits im Makefile-Befehl — kein zweites sudo nötig. Caveat: Der direkte systemd-Start ist community-seitig umstritten (SIGTERM-/„Unclean shutdown"-Diskussion, Community-Quelle: pzwiki) — dieses Repo fährt trotzdem den systemd-Weg; vor Stopps im Update-Zyklus wird per RCON angekündigt (announce.sh), und die Unit erlaubt 120 Sekunden TimeoutStopSec (jeweils Repo-Default). Details zur Unit: systemd-Referenz.

make status

make status

Kombiniert systemctl status zomboid --no-pager mit scripts/healthcheck.sh (beide mit || true — make status schlägt also nie fehl, 1:1 aus dem Makefile). Typische Ausgabe des Healthchecks: [INFO] OK: Server-Prozess aktiv, [INFO] OK: UDP 16261 gebunden — oder [ERROR] FAIL: Kein Server-Prozess gefunden. Erster Blick bei Problemen.

make logs

make logs

sudo journalctl -u zomboid -f (1:1) — Live-Log der systemd-Unit, beenden mit Strg+C. Mit sudo, weil Journal-Lesezugriff nötig ist. Für Docker-Betrieb stattdessen docker compose logs -f (siehe Docker-Betrieb).

make update

make update

Backend scripts/update.sh (sicherer Update-Zyklus, 1:1):

1. Discord-Notify „Update-Zyklus gestartet"
2. In-Game-Ansage (announce.sh, RCON-Countdown) + systemctl stop zomboid
3. Pre-Update-Backup (backup.sh pre-update) als Rollback-Anker
4. SteamCMD: +app_update 380870 validate
5. Configs + Modliste neu rendern
6. Start, 45 Sekunden warten (Repo-Default), dann Healthcheck
7. Schlägt der Healthcheck fehl: Auto-Rollback — Stop, entpacken des pre-update-*.tar.gz nach ${PZ_DATA_DIR}, Start, erneuter Healthcheck; schlägt auch der fehl: Discord-Warnung „manuell pruefen!"

Mit --dry-run zeigt das Skript nur die Schritte an (Skriptkopf). Typische Erfolgs-Ausgabe: Update erfolgreich. Details: Updates-und-Rollback.

make backup

make backup

Backend scripts/backup.sh (Label daily): packt Saves + Server aus ${PZ_DATA_DIR} als ${BACKUP_DIR}/daily-<timestamp>.tar.gz, loggt die Größe, rotiert alte daily-Backups nach RETENTION_DAILY (7, Repo-Default) und löscht daily-Backups älter als RETENTION_WEEKLY * 7 Tage (28 Tage, Repo-Default). Details: Backup-und-Restore.

make restore

make restore

Backend scripts/restore.sh — interaktiv: listet alle ${BACKUP_DIR}/*.tar.gz (neueste zuerst), fragt Nummer waehlen: und eine Bestätigung (j/N) ab. Dann (1:1): Server stoppen → Sicherheits-Backup pre-restore → tar nach ${PZ_DATA_DIR} entpacken → Server starten → nach 45 Sekunden Healthcheck (Repo-Default). Details: Backup-und-Restore.

make healthcheck

make healthcheck

Backend scripts/healthcheck.sh, drei Prüfungen (1:1):

1. Läuft ein ProjectZomboid-Prozess bzw. ist die Unit zomboid aktiv?
2. Ist UDP ${GAME_PORT} (Default 16261) gebunden (ss -ulnp)? Fehlschlag hier ist nur eine Warnung — der Server kann noch starten
3. Gibt es in den letzten 5 Minuten kritische Logzeilen (OutOfMemory|Exception in thread|FATAL) im Journal?

Exit-Code 0 = gesund. Wird auch von make status, update.sh und dem Cron-Watchdog monitor.sh benutzt. Details: Monitoring-und-Alerts.

make failover-sync

make failover-sync

Backend gcp/sync-backups.sh: spiegelt ${BACKUP_DIR} per gsutil -m rsync -r in den GCP-Bucket gs://${GCP_BUCKET} (1:1). Voraussetzungen: gsutil installiert, GCP-Variablen in .env gesetzt. Details: GCP-Failover.

Typische Arbeitsabläufe

Mod hinzufügen: $EDITOR mods.yaml (Eintrag ergänzen) → make mods (validieren + generieren) → make restart — der Server liest die neue Modliste erst nach dem Neustart.

Problem prüfen: make status (Prozess + Port + Log-Fehler auf einen Blick) → bei FAIL make logs (Live-Log mitlesen).

Vor einem manuellen Eingriff sichern: make backup — Snapshot vor riskanten Änderungen.

Stolperfallen

• Unknown target: Tippfehler wie make stat enden in make: *** No rule to make target 'stat'. Stop. — make help zeigt die exakten Namen.
• Fehlende .env: Skripte mit need_env-Guard brechen mit .env fehlt. Erst: cp .env.example .env und Werte setzen. ab (1:1 aus common.sh). make render, install, update, restore und failover-sync sind betroffen. Ohne .env greifen trotzdem die Defaults aus common.sh (z. B. SERVER_NAME=servertest) — für start/stop/restart reicht das.
• sudo und Umgebung: Die systemd-Targets bringen ihr eigenes sudo mit; ein zusätzliches sudo make ... ist unnötig. sudo leert die Umgebung — kein Problem: common.sh lädt die .env selbst, ein -E ist nie nötig (Heuristik, abgeleitet aus common.sh). Empfehlung des Repos: sudo nur bei make install.
• Docker-Pfad statt systemd: make start/stop/restart/status/ logs steuern ausschließlich die systemd-Unit zomboid. Läuft der Server in Docker (Docker-Betrieb), sind diese Targets wirkungslos — dort per docker compose operieren.

Weiter: ENV-Variablen · Skripte-Referenz