lloesche/valheim-server Docker image

Valheim

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

Basic Docker Usage
Environment Variables
System requirements
Deployment
Updates
Backups
- Manual backup
Finding Your Server
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
OpenMediaVault Help
- Permission denied error
License
Legal disclaimer

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