Linux setup

Linux package 0.5.0-linux.1 contains the 0.5.0 map server, the indexer, the Java telemetry agent and a Python installer. The Windows downloads stay at 0.5.0. It is for Linux x86-64; ARM is not included. Python 3.8 or newer is needed only for setup. The web map is built in, so the server needs no Node, Go or Python packages. Players install nothing.

This is the first Linux package. Automated tests cover setup, the real Linux binaries and Java telemetry fixtures, and on a Linux dedicated server in Docker the agent passes its compatibility check, loads and feeds the map. No player has joined yet, so live multiplayer tracking and a HelmForge deployment still need to be validated. There is no Linux terrain rendering wizard or container image yet.

Run the installer as the same non-root account that runs Project Zomboid, with read access to the game installation. Do not use sudo. The game folder must contain an executable start-server.sh and jre64/bin/java. Use installation paths without spaces or shell punctuation.

Download the archive and its checksum file from the download section, then:

sha256sum -c PZLiveMap-0.5.0-linux.1-linux-amd64.tar.gz.sha256
tar -xzf PZLiveMap-0.5.0-linux.1-linux-amd64.tar.gz
cd PZLiveMap-0.5.0-linux.1-linux-amd64
python3 install.py --game /home/steam/pzserver --install-dir /home/steam/pzlivemap \
  --origin https://map.example.com --name 'My Zomboid Server'

Replace the example paths and address. Leave out --origin to test on localhost. The installer asks for administrator and team passwords, checks the installed game APIs, creates protected configuration and accounts, and indexes shops and loot. The administrator login is admin. It refuses an existing destination folder, so it cannot overwrite an installation, and a failed setup removes only the folder it created. It does not edit game files, profiles or saves, and restarts nothing.

Start the map with /home/steam/pzlivemap/start-map.sh. It listens on 127.0.0.1:3000 by default. In a container or for LAN access, pass --listen 0.0.0.0:3000 and the right --origin when you install, and restrict access at your firewall or proxy. Telemetry ingest stays on loopback.

At the next normal game stop and start, change the game's startup command to:

/home/steam/pzlivemap/start-game.sh -servername servertest

Keep your existing game arguments, including -servername, -cachedir and -nosteam where you use them. The wrapper runs the original launcher and adds the Java agent through JAVA_TOOL_OPTIONS, keeping any Java options you already have. Use it exactly once, and remove any older manual LiveMap -javaagent argument first. Steam updates do not replace the wrapper. Check compatibility again after game updates:

/home/steam/pzserver/jre64/bin/java -cp /home/steam/pzlivemap/tools/pzlivemap-agent.jar \
  pzlivemap.agent.Check /home/steam/pzserver

Moving from the old Lua integration? With the game stopped, remove only PZLiveMap from the profile's Mods= list and keep your other mods.

Game assets and rendered terrain are not included. Export a Map.pzmap with the Windows portable renderer, using the same game files as the dedicated server. Copy the package to Linux, stop the map process (the game can keep running), then run this from the extracted Linux package:

python3 import-map.py --install-dir /home/steam/pzlivemap \
  --game /home/steam/pzserver --profile /home/steam/Zomboid/Server/servertest.ini \
  --bundle /home/steam/Map.pzmap

The importer checks the map fingerprint, tile paths, counts and calibration before it switches to the new terrain. It backs up the configuration and keeps the previous terrain for rollback, so allow room for both copies plus 5 GiB. Restart the map after the import. The importer expects the JSON-format config/config.yaml this installer writes; if you have converted it to YAML, migrate by hand instead.

To migrate by hand, copy an activated tile folder from an existing Windows installation, copy its whole map section into the Linux config, and point tiles at the Linux folder. Keep every other Linux setting. Blank terrain before an import does not mean telemetry has failed.

As the game account, after installing:

mkdir -p ~/.config/systemd/user
cp /home/steam/pzlivemap/pzlivemap.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now pzlivemap.service
journalctl --user -u pzlivemap.service -f

To start without anyone logging in, a host administrator can enable lingering with sudo loginctl enable-linger steam, using your account name. The service starts only the map, not the game. Containers without a user systemd session should run start-map.sh from their own supervisor.

Use your own Cloudflare Tunnel: route map.example.com to http://127.0.0.1:3000 when the connector runs on the same host. The installer does not install or authorise Cloudflare. Use an HTTPS address and secure cookies for a public site, and a reverse proxy that supports WebSockets. Subpaths such as /pzmap are not supported; use a hostname of its own.

On a hosting panel, keep the whole installation on persistent storage and start the game with start-game.sh. The game and the map must share the snapshot folder under the same account, or with permissions set up for it. With separate containers, mount the agent and snapshot paths at the same absolute paths. HelmForge templates are not included or tested.

A map website on a different host needs its own secure transport for the snapshot, which the installer does not set up. Installing the map alongside the Linux game server is the supported setup for this package.

Stop the map before replacing its binaries, and stop the game normally too if you are updating the agent. Back up the LiveMap folder, extract the new archive somewhere separate, run its agent compatibility check, and replace only pzlivemap, pzindexer and tools/pzlivemap-agent.jar. Keep config, data and the launcher scripts. Start the game with the wrapper and restart the map. The installer is for fresh setups, not in-place upgrades.

If the map says the live player count is unavailable, look for PZLiveMap in the game logs, check that data/live/state.json updates about once a second, and make sure the game really started through the wrapper. A snapshot older than 15 seconds counts as unavailable. Check write permissions and Java compatibility before re-rendering terrain. Map logs go to stdout or the systemd journal.

To remove it, stop the game normally and restore its original startup command. Run systemctl --user disable --now pzlivemap.service, remove the copied unit file and run systemctl --user daemon-reload. Keep a backup of the data before deleting the installation folder. No Steam game files need restoring.

Questions or bugs? Email the version and what happened from the PZ LiveMap page.