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:

External Resources:

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

Prerequisites

Directories

Two directories are required to be present on the host:

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:

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

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.

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.