lloesche/valheim-server Docker image

Valheim Server in a Docker Container (with BepInEx and ValheimPlus support)
This project is hosted at https://github.com/lloesche/valheim-server-docker

Table of contents

<!-- vim-markdown-toc GFM -->

• Basic Docker Usage
• Environment Variables
  • Log filters
    • Log filter event hooks
      • Discord log filter event hook example
  • Event hooks
    • Event hook examples
      • Install extra packages
      • Copy backups to another location
      • Notify on Discord
  • Mod config from Environment Variables
• System requirements
• Deployment
  • Deploying with Docker and systemd
  • Deploying with docker compose
  • Deploying to Kubernetes
  • Deploying to AWS ECS
  • Deploying to Nomad
• Updates
• Backups
  • Manual backup
• Finding Your Server
  • In-game
    • Joining Directly via Hostname/IP
  • Steam Server Browser
  • Steam Server Favorites & LAN Play
• Admin Commands
  • Enable Admin Console
• Supervisor
  • Supervisor API
• Status web server
• Modding
  • BepInExPack Valheim
    • Configuration
  • ValheimPlus
    • Updates
    • Configuration
      • Disable server password
• Changing startup CMD in Portainer
• Synology Help
  • First install
  • Updating the container image to the latest version
    • Error after download of new container image
• QNAP NAS Help
  • Creating container
  • Updating image
  • QNAP ZFS issue
• OpenMediaVault Help
  • Permission denied error
• License
• Legal disclaimer

<!-- vim-markdown-toc -->

Basic Docker Usage

The name of the Docker image is ghcr.io/lloesche/valheim-server.

Volume mount the server config directory to /config within the Docker container.

If you have an existing world on a Windows system you can copy it from e.g.
C:\Users\Lukas\AppData\LocalLow\IronGate\Valheim\worlds_local to e.g.
$HOME/valheim-server/config/worlds_local and run the image with $HOME/valheim-server/config volume mounted to /config inside the container. The container directory /opt/valheim contains the downloaded server. It can optionally be volume mounted to avoid having to download the server on each fresh start.

$ mkdir -p $HOME/valheim-server/config/worlds_local $HOME/valheim-server/data
# copy existing world
$ docker run -d \
    --name valheim-server \
    --cap-add=sys_nice \
    --stop-timeout 120 \
    -p 2456-2457:2456-2457/udp \
    -v $HOME/valheim-server/config:/config \
    -v $HOME/valheim-server/data:/opt/valheim \
    -e SERVER_NAME="My Server" \
    -e WORLD_NAME="Neotopia" \
    -e SERVER_PASS="secret" \
    ghcr.io/lloesche/valheim-server

Warning: SERVER_PASS must be at least 5 characters long. Otherwise valheim_server.x86_64 will refuse to start!

A fresh start will take several minutes depending on your Internet connection speed as the container will download the Valheim dedicated server from Steam (~1 GB).

Do not forget to modify WORLD_NAME to reflect the name of your world! For existing worlds that is the filename in the worlds_local/ folder without the .db/.fwl extension.

If you want to play with friends over the Internet and are behind NAT make sure that UDP ports 2456-2457 are forwarded to the container host. (Remark: If you use crossplay, you don't need port forwarding! See official Valheim Dedicated Server Manual.pdf in the data/server folder.) Also ensure they are publicly accessible in any firewall.

Crossplay: To enable crossplay between different platforms add -crossplay to SERVER_ARGS:

    -e SERVER_ARGS="-crossplay"

There is more info in section Finding Your Server.

For LAN-only play see section Steam Server Favorites & LAN Play

For more deployment options see the Deployment section.

Granting CAP_SYS_NICE to the container is optional. It allows the Steam library that Valheim uses to give itself more CPU cycles. Without it you will see a message Warning: failed to set thread priority in the startup log.

Environment Variables

All variable names and values are case-sensitive!

Name	Default	Purpose
SERVER_NAME	My Server	Name that will be shown in the server browser
SERVER_PORT	2456	UDP start port that the server will listen on
WORLD_NAME	Dedicated	Name of the world without .db/.fwl file extension
SERVER_PASS	secret	Password for logging into the server - min. 5 characters!
SERVER_PUBLIC	true	Whether the server should be listed in the server browser (true) or not (false)
SERVER_ARGS		Additional Valheim server CLI arguments
ADMINLIST_IDS		Space separated list of admin SteamIDs in SteamID64 format. Overrides any existing adminlist.txt entries!
BANNEDLIST_IDS		Space separated list of banned SteamIDs in SteamID64 format. Overrides any existing bannedlist.txt entries!
PERMITTEDLIST_IDS		Space separated list of whitelisted SteamIDs in SteamID64 format. Overrides any existing permittedlist.txt entries!
UPDATE_CRON	*/15 * * * *	Cron schedule for update checks (disabled if set to an empty string or if the legacy UPDATE_INTERVAL is set)
IDLE_DATAGRAM_WINDOW	3	The time window, in seconds, to wait for incoming UDP datagrams on non-public servers before determining if the server is idle
IDLE_DATAGRAM_MAX_COUNT	30	The number of incoming UDP datagrams the container should tolerate (including useless datagrams such as mDNS, as well as useful datagrams like queries against the UDP query port and active connections by players) on non-public servers before deciding that the server is not idle
UPDATE_IF_IDLE	true	Only run update check if no players are connected to the server (true or false)
RESTART_CRON	0 5 * * *	Cron schedule for server restarts (disabled if set to an empty string)
RESTART_IF_IDLE	true	Only run daily restart if no players are connected to the server (true or false)
TZ	Etc/UTC	Container time zone
BACKUPS	true	Whether the server should create periodic backups (true or false)
BACKUPS_CRON	0 * * * *	Cron schedule for world backups (disabled if set to an empty string or if the legacy BACKUPS_INTERVAL is set)
BACKUPS_DIRECTORY	/config/backups	Path to the backups directory
BACKUPS_MAX_AGE	3	Age in days after which old backups are flushed
BACKUPS_MAX_COUNT	0	Maximum number of backups kept, 0 means infinity
BACKUPS_IF_IDLE	true	Backup even when no players have been connected for a while
BACKUPS_IDLE_GRACE_PERIOD	3600	Grace period in seconds after the last player has disconnected in which we will still create backups when BACKUPS_IF_IDLE=false
BACKUPS_ZIP	true	Compress Backups with zip. If set to false Backups will be stored uncompressed.
PERMISSIONS_UMASK	022	Umask to use for backups, config files and directories
STEAMCMD_ARGS	validate	Additional steamcmd CLI arguments
PUBLIC_TEST	false	Run the Public Test Beta version of Valheim server. Note that this simply extends existing STEAMCMD_ARGS by adding the appropriate beta flags to it.
VALHEIM_PLUS	false	Whether ValheimPlus mod should be loaded (config in /config/valheimplus, additional plugins in /config/valheimplus/plugins). Can not be used together with BEPINEX.
VALHEIM_PLUS_REPO	Grantapher/ValheimPlus	Which ValheimPlus Github repo to use. Useful for switching to forks.
VALHEIM_PLUS_RELEASE	latest	Which version of ValheimPlus to download. Will default to latest available. To specify a specific tag set to tags/0.9.9.8
BEPINEX	false	Whether BepInExPack Valheim mod should be loaded (config in /config/bepinex, plugins in /config/bepinex/plugins). Can not be used together with VALHEIM_PLUS.
SUPERVISOR_HTTP	false	Turn on supervisor's http server
SUPERVISOR_HTTP_PORT	9001	Set supervisor's http server port
SUPERVISOR_HTTP_USER	admin	Supervisor http server username
SUPERVISOR_HTTP_PASS		Supervisor http server password
STATUS_HTTP	false	Turn on the status http server. Only useful on public servers (SERVER_PUBLIC=true).
STATUS_HTTP_PORT	80	Status http server tcp port
STATUS_HTTP_CONF	/config/httpd.conf	Path to the busybox httpd config
STATUS_HTTP_HTDOCS	/opt/valheim/htdocs	Path to the status httpd htdocs where status.json is written
SYSLOG_REMOTE_HOST		Remote syslog host or IP to send logs to
SYSLOG_REMOTE_PORT	514	Remote syslog UDP port to send logs to
SYSLOG_REMOTE_AND_LOCAL	true	When sending logs to a remote syslog server also log local
PUID	0	UID to run valheim-server as
PGID	0	GID to run valheim-server as

There are a few undocumented environment variables that could break things if configured wrong. They can be found in defaults.

Log filters

Valheim server by default logs a lot of noise. These env variables allow users to remove unwanted lines from the log.

Prefix	Default	Purpose
VALHEIM_LOG_FILTER_EMPTY	true	Filter empty log lines
VALHEIM_LOG_FILTER_UTF8	true	Filter invalid UTF-8 characters
VALHEIM_LOG_FILTER_MATCH		Filter log lines exactly matching
VALHEIM_LOG_FILTER_STARTSWITH	(Filename:	Filter log lines starting with
VALHEIM_LOG_FILTER_ENDSWITH		Filter log lines ending with
VALHEIM_LOG_FILTER_CONTAINS		Filter log lines containing
VALHEIM_LOG_FILTER_REGEXP		Filter log lines matching regexp

The default filter removes:

• Empty log lines
• Log lines consisting of a single space (wtf?)
• A repeating line saying (Filename: ./Runtime/Export/Debug/Debug.bindings.h Line: 35)
• Lines flooding the log with Assertion Failed warnings on packet processing timeouts (See #104)
• If ValheimPlus is turned on lines starting with Fallback handler could not load library

Log filter event hooks

If an environment variable prefixed with ON_ exists for an identically named log filter, instead of removing the log line the contents of the variable will be executed when the filter matches with the log line piped on stdin.

Prefix	Purpose
ON_VALHEIM_LOG_FILTER_MATCH	Run command hook on log lines exactly matching
ON_VALHEIM_LOG_FILTER_STARTSWITH	Run command hook on log lines starting with
ON_VALHEIM_LOG_FILTER_ENDSWITH	Run command hook on log lines ending with
ON_VALHEIM_LOG_FILTER_CONTAINS	Run command hook on log lines containing
ON_VALHEIM_LOG_FILTER_REGEXP	Run command hook on regexp match

All environment variables except for VALHEIM_LOG_FILTER_EMPTY and VALHEIM_LOG_FILTER_UTF8 are prefixes. Meaning you can define multiple matches like so:

-e VALHEIM_LOG_FILTER_STARTSWITH=foo \
-e VALHEIM_LOG_FILTER_STARTSWITH_BAR=bar \
-e VALHEIM_LOG_FILTER_STARTSWITH_SOMETHING_ELSE="some other filter"
-e VALHEIM_LOG_FILTER_CONTAINS_Connected="Got character ZDOID from"
-e ON_VALHEIM_LOG_FILTER_CONTAINS_Connected="cat >> /tmp/character_login"

Discord log filter event hook example

Sends a Discord message whenever a player spawns

-e DISCORD_WEBHOOK="https://discord.com/api/webhooks/8171522530..." \
-e VALHEIM_LOG_FILTER_CONTAINS_Spawned="Got character ZDOID from" \
-e ON_VALHEIM_LOG_FILTER_CONTAINS_Spawned='{ read l; l=${l//*ZDOID from /}; l=${l// :*/}; msg="Player $l spawned into the world"; curl -sfSL -X POST -H "Content-Type: application/json" -d "{\"username\":\"Valheim\",\"content\":\"$msg\"}" "$DISCORD_WEBHOOK"; }'

See Notify on Discord below for proper quoting in env and compose files.

If you are running ValheimPlus and this filter triggers twice, check this ValheimPlus issue. The cause is a misconfigured BepInEx.cfg that causes all log lines to be duplicated.

Event hooks

The following environment variables can be populated to run commands whenever specific events happen.

Name	Default	Purpose
PRE_SUPERVISOR_HOOK		Command to be executed before supervisord is run. Startup is blocked until this command returns.
PRE_BOOTSTRAP_HOOK		Command to be executed before bootstrapping is done. Startup is blocked until this command returns.
POST_BOOTSTRAP_HOOK		Command to be executed after bootstrapping is done and before the server or any services are started. Can be used to install additional packages or perform additional system setup. Startup is blocked until this command returns.
PRE_BACKUP_HOOK		Command to be executed before a backup is created. The string @BACKUP_FILE@ will be replaced by the full path of the future backup zip file. Backups are blocked until this command returns.
POST_BACKUP_HOOK		Command to be executed after a backup is created. The string @BACKUP_FILE@ will be replaced by the full path of the backup zip file. Backups are blocked until this command returns. See Copy backups to another location for details.
PRE_UPDATE_CHECK_HOOK		Command to