Project Zomboid Dedicated Server

Disclaimer

Note: This image is not officially supported by Valve, nor by The Indie Stone.

If issues are encountered, please report them on the GitHub repository

Badges

Description

Dedicated Server for Project Zomboid using Docker, and optionally Docker-Compose. Built almost from scratch to be the smallest Project Zomboid Dedicated Server around!

Note: This Image is "rootless", and therefore should not be run as the root user. Attempting to do so will prevent the server from starting ( see #8 , #14).

Bare-Minimum instructions to get a server running:

# Pull the latest image:
docker pull renegademaster/zomboid-dedicated-server:latest

# Make two folders
mkdir ZomboidConfig ZomboidDedicatedServer

# Run the server (with bare minimum options):
docker run --detach \
    --mount type=bind,source="$(pwd)/ZomboidDedicatedServer",target=/home/steam/ZomboidDedicatedServer \
    --mount type=bind,source="$(pwd)/ZomboidConfig",target=/home/steam/Zomboid \
    --publish 16261:16261/udp --publish 16262:16262/udp \
    --name zomboid-server \
    docker.io/renegademaster/zomboid-dedicated-server:latest

The default behaviour of the Container is not to automatically restart after a crash to give the user time to investigate the cause of the issue. You may however want to change the restart policy to automatically recover from an unexpected failure. The following options will help to recover from such a situation:

• --restart=unless-stopped will restart the container every time that it exits unless the Container is stopped using the Docker/Podman API.
• --restart=on-failure[:max-retries] will restart the container only if it exits with a non-zero exit code. Optionally, it can also be configured to only restart a fixed number of times to help prevent crash-loops.

These same options can be set in the docker-compose.yaml file.

Assurance / Testing

For every commit, the server is built and started briefly using GitHub Actions. This is to ensure that the server always works, and makes it less likely that there will be a version released that does not function. The main configurations are changed and checked after starting the server to verify that it is possible for a user to configure their instance. Custom Ports and Remote RCON commands are also used during the validation to ensure that the user can host the server using any Port combination of their choice. You can view the previous Action runs here.

Links

Source:

• GitHub Repository

Images:

Provider	Image	Pull Command
GitHub Packages	ghcr.io/renegade-master/zomboid-dedicated-server	docker pull ghcr.io/renegade-master/zomboid-dedicated-server:x.y.z docker pull ghcr.io/renegade-master/zomboid-dedicated-server:latest
DockerHub	docker.io/renegademaster/zomboid-dedicated-server	docker pull docker.io/renegademaster/zomboid-dedicated-server:x.y.z docker pull docker.io/renegademaster/zomboid-dedicated-server:latest
Red Hat Quay	quay.io/renegade_master/zomboid-dedicated-server	docker pull quay.io/renegade_master/zomboid-dedicated-server:x.y.z docker pull quay.io/renegade_master/zomboid-dedicated-server:latest

External Resources:

• Dedicated Server Wiki
• Dedicated Server Configuration
• Steam DB Page

Prerequisites

Directories

Two directories are required to be present on the host:

Name	Directory	Description
Configuration Data	ZomboidConfig	For storing the server configuration and save files.
Installation Data	ZomboidDedicatedServer	For storing the server game data.

These folders must be created in the directory that you intend to run the Docker image from. This could be a folder that you have created in some kind of "server directory", or it could be the root of this repository after you have cloned it down. If these folders are not present when the Docker image starts, you will get permissions errors ( see #8 , #14 , #17) because the Docker engine will create the folders at Container runtime. This creates them under the root user on the host which causes permissions conflicts.

The 'Configuration Data' folder is where the server configuration and save files are stored. This folder can be opened and edited just like if you were running the server without Docker. You can backup your save files, or edit the server configuration files. You should start the server once successfully before attempting to edit files in the 'Configuration Data' folder. Once the files are generated, it is safe to edit them. Most configuration option changes will require a restart of the server to properly take effect. Most of these settings are also configurable from the in-game Admin menu.

The 'Installation Data' folder is where the server game data is stored. This folder can be opened and edited, but a full restart of the server can sometimes reset changes to this folder during file verification. Therefore, the recommended way to change files that would be stored in this folder is to use the Environment Variables in the 'Optional Arguments' table provided by the Docker image.

Ports

There are a total of three ports that can be utilised by the server, but only two are strictly required:

Name	Default Port	Description	Required
DEFAULT_PORT	16261	Port used by the server to listen for connections.	yes
RCON_PORT	27015	Port used by the server to listen for RCON connections/commands.	no
UDP_PORT	16262	Additional Port used by the server to facilitate Client connections.	yes

All Ports are configurable to use different Port numbers, however you must be aware that by changing a Port in the game configuration files, that you must also expose the changed (or default) Port in the Docker run command --publish ... or present under the services.zomboid-server.ports configuration key of the Docker-Compose file. Also, it is essential that these Ports are not blocked by a firewall. If you are behind a router and/or firewall, you will almost definitely need to open these Ports in order for anyone else outside your network to connect to the server. Port forwarding, and opening Ports in hosted servers is not within the scope of this project. To get instructions for your specific use case you will need to ask your ISP, Server Provider, or consult the instructions on your Third-Party Router.

The strictly required Ports (QUERY_PORT and GAME_PORT) are used by the server to listen for connections and communicate with connected clients. These Ports must be assigned a value, and must be accessible from the Internet (i.e. "forwarded").

If you intend to use RCON to interact with the server, then it follows that that Port (RCON_PORT) must also be open for connections. This is not required if you do not intend to use RCON, and in this scenario, keeping it closed enhances the security of your server. If you do not wish to use RCON, then it does not need to be present in the Docker run command, nor in the Docker-Compose file.

Instructions

The server can be run using plain Docker, or using Docker-Compose. The end-result is the same, but Docker-Compose is recommended for ease of configuration.

Optional environment variables

Argument	Description	Values	Default
ADMIN_PASSWORD	Server Admin account password	[a-zA-Z0-9]+	changeme
ADMIN_USERNAME	Server Admin account username	[a-zA-Z0-9]+	superuser
BIND_IP	IP to bind the server to	0.0.0.0	0.0.0.0
GAME_VERSION	Game version to serve	[a-zA-Z0-9_]+	public
GC_CONFIG	Specifices Java GC to use	[a-zA-Z0-9_]+	ZGC
MAP_NAMES	Map Names (e.g. North;South)	map1;map2;map3	Muldraugh, KY
MAX_RAM	Maximum amount of RAM to be used	([0-9]+)m	4096m
STEAM_VAC	Use Steam VAC anti-cheat	(true|false)	true
TZ	Set the timezone for the container	[A-Z]+	UTC
USE_STEAM	Create a Steam Server, or a Non-Steam Server	(true|false)	true

Config file environment variables

The following environment variables will automatically overwrite values in the server's config.ini file (located at /home/steam/Zomboid/Server/[name].ini). Editing these values directly in the .ini file will result in them being overwritten with either the default value, or the configured environment variable.

Any other values can and should be edited directly in the .ini file.

Argument	Description	.ini variable	Values	Default
AUTOSAVE_INTERVAL	Interval between autosaves in minutes	SaveWorldEveryMinutes	[0-9]+	15m
DEFAULT_PORT	Port for other players to connect to	DefaultPort	1000 - 65535	16261
MAX_PLAYERS	Maximum players allowed in the Server	MaxPlayers	[0-9]+	16
MOD_NAMES	Workshop Mod Names (e.g. ClaimNonResidential;MoreDescriptionForTraits)	Mods	mod1;mod2;mod
MOD_WORKSHOP_IDS	Workshop Mod IDs (e.g. 2160432461;2685168362)	WorkshopItems	2160432461;2685168362;
PAUSE_ON_EMPTY	Pause the Server when no Players are connected	PauseEmpty	(true|false)	true
PUBLIC_SERVER	If set to false only Pre-Approved/Allowed players can join the server (NOTE: Do not confuse with the Public option in the .ini)	Open	(true|false)	true
RCON_PASSWORD	Password for authenticating incoming RCON commands	RCONPassword	[a-zA-Z0-9]+	changeme_rcon
RCON_PORT	Port to listen on for RCON commands	RCONPort	(true|false)	27015
SERVER_NAME	Publicly visible Server Name	PublicName	[a-zA-Z0-9]+	ZomboidServer
SERVER_PASSWORD	Server password	Password	[a-zA-Z0-9]+
UDP_PORT	Additional Port for facilitating Client connections	SteamPort1	1000 - 65535	8766

Docker

The following are instructions for running the server using the Docker image.

1. Acquire the image locally:

   • Pull the image from DockerHub:

     docker pull renegademaster/zomboid-dedicated-server:<tagname>

   • Or alternatively, build the image:

     git clone https://github.com/Renegade-Master/zomboid-dedicated-server.git \
         && cd zomboid-dedicated-server
     
     docker build -t docker.io/renegademaster/zomboid-dedicated-server:<tag> -f docker/zomboid-dedicated-server.Dockerfile .

2. Run the container:

   *Note: Arguments inside square brackets are optional. If the default ports are to be overridden, then the published ports below must also be changed*

   mkdir ZomboidConfig ZomboidDedicatedServer
   
   docker run --detach \
       --mount type=bind,source="$(pwd)/ZomboidDedicatedServer",target=/home/steam/ZomboidDedicatedServer \
       --mount type=bind,source="$(pwd)/ZomboidConfig",target=/home/steam/Zomboid \
       --publish 16261:16261/udp --publish 16262:16262/udp [--publish 27015:27015/tcp] \
       --name zomboid-server \
       [--restart=no] \
       [--env=ADMIN_PASSWORD=<value>] \
       [--env=ADMIN_USERNAME=<value>] \
       [--env=AUTOSAVE_INTERVAL=<value>] \
       [--env=BIND_IP=<value>] \
       [--env=GAME_PORT=<value>] \
       [--env=GAME_VERSION=<value>] \
       [--env=GC_CONFIG=<value>] \
       [--env=MAP_NAMES=<value>] \
       [--env=MAX_PLAYERS=<value>] \
       [--env=MAX_RAM=<value>] \
       [--env=MOD_NAMES=<value>] \
       [--env=MOD_WORKSHOP_IDS=<value>] \
       [--env=PAUSE_ON_EMPTY=<value>] \
       [--env=PUBLIC_SERVER=<value>] \
       [--env=QUERY_PORT=<value>] \
       [--env=RCON_PASSWORD=<value>] \
       [--env=RCON_PORT=<value>] \
       [--env=SERVER_NAME=<value>] \
       [--env=SERVER_PASSWORD=<value>] \
       [--env=STEAM_VAC=<value>] \
       [--env=TZ=<value>] \
       [--env=USE_STEAM=<value>] \
       docker.io/renegademaster/zomboid-dedicated-server[:<tagname>]

3. Optionally, reattach the terminal to the log output (*Note: this is not an Interactive Terminal*)

   docker logs --follow zomboid-server

4. Once you see LuaNet: Initialization [DONE] in the console, people can start to join the server.

Docker-Compose

The following are instructions for running the server using Docker-Compose.

1. Download the repository:

   git clone https://github.com/Renegade-Master/zomboid-dedicated-server.git \
       && cd zomboid-dedicated-server

2. Make any configuration changes you want to in the docker-compose.yaml file. In the services.zomboid-server.environment section, you can change values for the server configuration.

   *Note: If the default ports are to be overridden, then the published ports must also be changed*

3. Run the following commands:

   • Make the data and configuration directories:

     mkdir ZomboidConfig ZomboidDedicatedServer

   • Pull the image from DockerHub:

     docker-compose up --detach

   • Or alternatively, build the image:

     docker-compose up --build --detach

4. Optionally, reattach the terminal to the log output (*Note: this is not an Interactive Terminal*)

   docker-compose logs --follow

5. Once you see LuaNet: Initialization [DONE] in the console, people can start to join the server.