/zomboid-dedicated-server

Linux based Docker image containing a Dedicated Server for Project Zomboid.

Primary LanguageShellOtherNOASSERTION

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

Build and Test Server Image Docker Repository on Quay

Docker Image Version (latest by date) Docker Image Size (latest by date) DockerHub Pulls

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:

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:

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.