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

• 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

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!

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.

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.

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.