The release of Valheim, the Viking-themed survival sandbox game developed by Iron Gate Studio, represents a significant milestone in the cooperative gaming landscape. The title’s procedural generation algorithms, complex crafting systems, and demanding boss encounters have fostered a massive community of players who value persistent, shared worlds. For many, the default local hosting options are insufficient for their needs. Local hosting often results in latency issues when the host disconnects, and it places an undue burden on the host’s hardware resources. The solution to these architectural limitations is the deployment of a dedicated server. However, managing the underlying software stack for a dedicated server—specifically the SteamCMD installation, binary updates, and process supervision—can be cumbersome for the average administrator. This is where containerization technologies, specifically Docker, provide a transformative advantage. By encapsulating the Valheim server within a Docker container, administrators gain a reproducible, isolated, and easily manageable environment that handles complex operational tasks such as automatic updates and backups without requiring manual intervention. This guide provides an exhaustive technical breakdown of deploying Valheim dedicated servers using Docker, focusing on the most prominent community-maintained images, specifically lloesche/valheim-server, community-valheim-tools/valheim-server, and mbround18/valheim. The analysis covers system prerequisites, configuration variables, volume management, modding support via BepInEx, and advanced operational procedures such as backups and performance tuning.
System Prerequisites and Environmental Requirements
Before initiating the deployment of a Valheim server, it is critical to establish a robust foundation on the host machine. The stability and performance of the server depend heavily on the underlying infrastructure. The first requirement is the presence of a functioning container runtime. Specifically, Docker Engine version 20.10 or higher is required. This version threshold ensures compatibility with modern container features, including advanced networking modes and volume management capabilities that are essential for server persistence. In addition to the core engine, Docker Compose version 2 is necessary. Docker Compose allows for the definition of multi-container applications and, in the context of a single server, provides a declarative way to manage the service lifecycle, environment variables, and network bindings. Administrators should verify the installation of these tools by executing version checks. The command docker --version confirms the engine release, while docker compose version ensures the orchestrator is present and up to date.
Hardware resources are the second critical pillar of the deployment architecture. Valheim is a CPU-intensive application, particularly when the game world contains a high density of player-built structures. The physics engine and the simulation of entity behaviors require significant processing power. Consequently, a minimum of 2GB of RAM is required to run a basic server. However, for worlds that are larger, more populated, or contain extensive architectural projects, 4GB of RAM is strongly recommended. This additional memory helps prevent garbage collection pauses in the Unity engine, which can cause noticeable stutters or lag for connected clients. Furthermore, it is imperative that the host machine has the Valheim game client installed via Steam. While the dedicated server is a separate binary, the authentication and update processes often rely on the Steam Client infrastructure to validate ownership and fetch the latest server files. Without the base game on the host or a valid Steam account configured for the server, the deployment may fail during the initial download phase.
The lloesche/valheim-server Image: Architecture and Features
The lloesche/valheim-server Docker image, maintained by lloesche, is widely recognized as the most popular and robust solution for hosting Valheim servers in a containerized environment. This image is designed to be a comprehensive all-in-one package. It does not merely wrap the server binary; it integrates a suite of operational features that reduce administrative overhead. Key features include automatic server updates, integrated world backup mechanisms, and native support for the BepInEx modding framework, which includes compatibility with ValheimPlus. The image is hosted on Docker Hub and is regularly updated to reflect changes in the upstream Valheim server binaries. The architectural design of this image prioritizes ease of use while maintaining the flexibility required for advanced configurations. By default, the image handles the installation of SteamCMD, downloads the server files, and manages the process lifecycle. This abstraction allows administrators to focus on game-related settings rather than low-level system administration.
The container exposes several critical directories that must be mapped to the host system for data persistence. The primary configuration directory within the container is /config. This directory contains the world files, server settings, and mod plugins. Mapping this directory to a host volume ensures that server configurations and world data are not lost when the container is stopped or removed. A secondary directory, /opt/valheim, contains the actual server binary and engine files. While the container can manage this directory internally, mapping it to a host volume is an optional but recommended practice for large-scale deployments. Mounting /opt/valheim prevents the container from re-downloading the entire server binary on every fresh start, which significantly reduces startup time and bandwidth usage. For users migrating from a Windows-based local server, the world data can be copied from the local AppData directory, specifically C:\Users\Username\AppData\LocalLow\IronGate\Valheim\worlds, to the host directory that will be mounted to /config. This migration path ensures that existing progress is preserved when moving to a Dockerized environment.
Quick Start Deployment via Docker Run
For administrators who prefer a direct command-line approach over a declarative configuration file, the docker run command provides a rapid method to instantiate a Valheim server. This method is ideal for testing or for environments where a simple, single-container setup is sufficient. The command requires several flags to define the network, environment, and volume mappings. The -d flag runs the container in detached mode, allowing it to operate in the background. The --name flag assigns a human-readable identifier to the container, such as valheim, which simplifies subsequent management commands. Network configuration is handled via the -p flag. Valheim utilizes three consecutive UDP ports for communication: the main game port, the query port, and the relay port. The standard range is 2456 to 2458. Therefore, the command must map these ports from the host to the container using the syntax -p 2456-2458:2456-2458/udp.
Environment variables are used to define the server’s identity and security settings. The SERVER_NAME variable sets the name that appears in the community server browser. The WORLD_NAME variable defines the name of the save file and the world instance. The SERVER_PASS variable sets the password required for players to join the server. It is crucial to note that the server password must be at least five characters long and cannot be a substring of the server name. This restriction is enforced by the Valheim server engine to prevent configuration errors. Volume mappings are defined using the -v flag. The command -v valheim-config:/config creates a named volume for configuration data, while -v valheim-data:/opt/valheim maps the server binaries. The final part of the command specifies the image to use: lloesche/valheim-server. Upon execution, the container will pull the image if not present, download the SteamCMD server files, and start the server process. The output in the logs will indicate when the server is ready for connections.
Advanced Configuration with Docker Compose
For production environments and more complex deployments, Docker Compose is the preferred method. It allows for the definition of the service in a YAML file, which promotes version control and reproducibility. A comprehensive docker-compose.yml file should include all necessary configurations to ensure the server runs smoothly. The service definition begins with the image specification, lloesche/valheim-server, and a unique container name. The ports section explicitly maps the three required UDP ports: 2456, 2457, and 2458. This explicit mapping is safer than range mapping as it clearly defines each port’s role. The environment section is where the server’s behavior is defined. Variables such as SERVER_NAME, WORLD_NAME, and SERVER_PASS are set here. Additional variables control visibility and updates. The SERVER_PUBLIC variable, when set to true, makes the server visible in the community server list, allowing players to discover and join it without a direct IP address.
Update and backup configurations are critical for maintaining server integrity. The UPDATE_CRON variable defines the schedule for automatic server updates. For example, */15 * * * * instructs the container to check for and apply updates every 15 minutes. The UPDATE_IF_IDLE variable ensures that updates only occur when no players are connected, preventing disruptions during active gameplay. Backup settings are equally important. The BACKUPS variable enables the automatic backup system. While the reference material does not detail all backup variables for the lloesche image, the presence of this variable indicates that the image supports scheduled backups of the world files. This feature protects against data corruption or accidental deletion. Administrators can also define additional environment variables to fine-tune the server experience, such as setting the server difficulty, enabling ping displays, or configuring the maximum number of players. The use of Docker Compose ensures that these settings are preserved across container restarts and updates.
Volume Management and Data Persistence
Data persistence is the cornerstone of any dedicated server deployment. Without proper volume management, all world progress and configuration changes would be lost whenever the container is restarted or removed. The lloesche/valheim-server image relies on two primary volumes: /config and /opt/valheim. The /config directory is the most critical for end-users. It contains the worlds and worlds_local directories, which store the map data, player inventories, and building structures. It also contains the bepinex directory for mod plugins and the backups directory for automated save copies. Mapping this directory to a host path, such as $HOME/valheim-server/config, ensures that the data survives container lifecycle events. The /opt/valheim directory contains the SteamCMD-downloaded server files. While these files can be recreated by the container, mapping this directory saves significant time and bandwidth during restarts.
For users migrating from a local Windows installation, the process involves copying the existing world data to the host directory. The source path on Windows is typically C:\Users\Username\AppData\LocalLow\IronGate\Valheim\worlds. This data should be copied to the host directory that is mapped to /config within the container. For example, if the host directory is $HOME/valheim-server/config, the world files should be placed in $HOME/valheim-server/config/worlds. It is important to ensure that the directory structure matches what the server expects. Some newer versions of the game or community forks may use worlds_local instead of worlds. Administrators should verify the directory structure of their existing save files and replicate it accurately in the host volume. Failure to do so may result in the server creating a new, empty world upon startup, effectively losing all previous progress.
The Community Fork: community-valheim-tools/valheim-server
The lloesche/valheim-server project has been forked and maintained by the community under the name community-valheim-tools/valheim-server. This fork is hosted on GitHub Container Registry (GHCR) and acts as a drop-in replacement for the original image. The community fork aims to address maintenance gaps and incorporate additional features requested by the user base. The image name for this fork is ghcr.io/community-valheim-tools/valheim-server. The architecture and volume mappings are identical to the original lloesche image, ensuring that existing configurations can be migrated with minimal effort. The primary volume mount point for configuration remains /config, and the server binaries are stored in /opt/valheim. This consistency allows administrators to switch between the two images simply by changing the image name in their Docker Compose file or run command.
The community fork includes additional documentation and support for various NAS platforms, such as Synology, QNAP, and OpenMediaVault. This is a significant advantage for users who are not running standard Linux servers but are using consumer-grade network-attached storage devices as their server hosts. The documentation provides specific instructions for configuring Docker on these platforms, ensuring that the server can be deployed in a wider variety of home laboratory environments. The fork also includes a status web server, which allows administrators to monitor the health and performance of the server via a web interface. This feature provides real-time metrics on CPU usage, memory consumption, and player count, facilitating proactive management of server resources. The community fork represents a collaborative effort to improve the reliability and feature set of the Valheim Docker image, making it a viable alternative for users who require additional support or features.
Alternative Image: mbround18/valheim
Another prominent option for deploying a Valheim server via Docker is the mbround18/valheim image. This image offers a different configuration model compared to the lloesche and community-valheim-tools images. It utilizes a different set of environment variables and volume mappings. The primary environment variables include PORT, NAME, WORLD, PASSWORD, TZ, and PUBLIC. The PORT variable defines the base port for the server, and the image automatically handles the query port by adding 1 to this value. For example, if PORT is set to 2456, the query port will be 2457. The NAME and WORLD variables correspond to the server name and world name, respectively. The PASSWORD variable sets the join password. The TZ variable sets the timezone for the server, which affects in-game day/night cycles and log timestamps. The PUBLIC variable, when set to 1, makes the server visible in the community list.
The mbround18 image also supports advanced automation features through additional environment variables. AUTO_UPDATE and AUTO_UPDATE_SCHEDULE control the automatic update process, using a cron-like syntax for scheduling. AUTO_BACKUP, AUTO_BACKUP_SCHEDULE, AUTO_BACKUP_REMOVE_OLD, and AUTO_BACKUP_DAYS_TO_LIVE manage the backup lifecycle. This allows administrators to define how often backups are created, how long they are retained, and whether old backups are automatically deleted. The AUTO_BACKUP_ON_UPDATE and AUTO_BACKUP_ON_SHUTDOWN variables ensure that backups are taken before critical events that could lead to data loss. The volume mappings for this image are different: saves are stored in /home/steam/.config/unity3d/IronGate/Valheim, and the server files are in /home/steam/valheim. Backups are stored in /home/steam/backups. This image automatically launches with the proper environment variables for BepInEx, enabling mod support out of the box. This makes it a convenient choice for users who want a simpler configuration model with built-in automation.
Modding with BepInEx and ValheimPlus
One of the most powerful features of the Dockerized Valheim server is the support for modding via the BepInEx framework. BepInEx is a Unity modding framework that allows for the injection of custom code into the game engine. This enables a wide range of modifications, from quality-of-life improvements to major gameplay changes. The lloesche/valheim-server and community-valheim-tools/valheim-server images support BepInEx by default. To enable it, the BEPINEX environment variable must be set to true. Once enabled, the container will initialize the BepInEx framework and look for mod files in the /config/bepinex/plugins directory. Administrators can place mod DLL files in this directory on the host system, and they will be loaded by the server on startup.
ValheimPlus is one of the most popular mods for Valheim, offering numerous quality-of-life features such as improved inventory management, faster building placement, and customizable game settings. To install ValheimPlus, administrators need to download the DLL file and place it in the plugins directory. The command docker cp MyMod.dll valheim-server:/config/bepinex/plugins/ can be used to copy the file from the host to the container. After placing the mod files, the server must be restarted to load the mods. The command docker compose restart valheim will stop and start the server, triggering the mod loading process. The logs will indicate whether the mods were loaded successfully. It is important to ensure that the mods are compatible with the current version of the Valheim server. Incompatible mods can cause the server to crash or behave unpredictably. The use of BepInEx allows for a highly customized server experience, catering to the specific needs of the player community.
Backup Strategies and Disaster Recovery
Data loss is a critical risk in any server deployment. Implementing a robust backup strategy is essential for preserving world progress and configuration. The lloesche/valheim-server image supports both automatic and manual backups. Automatic backups are configured via the BACKUPS environment variable and can be scheduled using cron expressions. Manual backups can be created using Docker commands. The command docker exec valheim-server ls -la /config/backups/ lists existing backups within the container. To create a manual backup, the command docker cp valheim-server:/config/worlds_local ./valheim-backup-$(date +%Y%m%d) copies the world data from the container to the host system. The $(date +%Y%m%d) portion of the command inserts the current date into the filename, ensuring that backups are uniquely identified.
Restoring from a backup is equally straightforward. The command docker cp ./valheim-backup-20260101/. valheim-server:/config/worlds_local/ copies the backup files back into the container’s world directory. After restoring the files, the server must be restarted using docker compose restart valheim to load the restored world. The mbround18/valheim image offers more granular control over backups, with variables for scheduling, retention, and automatic deletion. This allows for a more automated backup lifecycle, reducing the need for manual intervention. Regardless of the image used, it is recommended to maintain multiple backup copies and store them in a separate location from the server files. This ensures that even in the event of a host failure, the world data can be recovered. Regular testing of backup and restore procedures is also important to verify that the process works as expected.
Performance Monitoring and Optimization
Valheim servers are inherently CPU-intensive, especially as the world grows in complexity. Monitoring performance is crucial to identify bottlenecks and optimize the server experience. Docker provides built-in tools for monitoring container resource usage. The command docker stats valheim-server displays real-time metrics for CPU usage, memory usage, network I/O, and block I/O. This information can help administrators determine if the server is running within its resource limits. If the CPU usage is consistently high, it may indicate that the server is struggling to keep up with the simulation demands. In such cases, consider upgrading the host hardware or limiting the number of concurrent players.
The server logs can also provide valuable insights into performance issues. The command docker compose logs valheim | grep -i "warning\|error" filters the logs for warnings and errors. These messages can indicate problems such as memory leaks, network latency, or mod conflicts. Addressing these issues promptly can prevent server crashes and improve the overall stability of the game. For large worlds with many structures, consider increasing the CPU resources allocated to the container. Docker allows for fine-grained control over CPU shares and limits, enabling administrators to prioritize the server process if needed. Additionally, optimizing the server configuration by adjusting settings such as the simulation radius and entity limits can help reduce the load on the CPU. Regular performance audits and proactive tuning are essential for maintaining a smooth and responsive server experience.
Stopping and Cleaning Up the Server
Proper shutdown procedures are important to ensure that data is saved and the server state is preserved. The lloesche/valheim-server image saves the world data automatically when the container is stopped. The command docker compose down stops the server and removes the container. However, it does not remove the volumes, ensuring that the world data and configuration are preserved. If the intention is to completely remove the server, including all data, the command docker compose down -v should be used. This command stops the server, removes the container, and deletes the associated volumes. This action is irreversible and will result in the permanent loss of all world data and configuration. Administrators should use this command with extreme caution and only after ensuring that all necessary backups have been created.
For the mbround18/valheim image, the shutdown process is similar. The docker compose down command stops the server and removes the container. The AUTO_BACKUP_ON_SHUTDOWN variable ensures that a backup is taken before the server shuts down, providing an additional layer of protection against data loss. This feature is particularly useful for unattended servers that may need to be restarted frequently. By automating the backup process during shutdown, administrators can ensure that the latest world state is always preserved. This reduces the risk of data loss due to unexpected power failures or system crashes. Proper shutdown procedures and automated backups are essential components of a robust server management strategy.
Conclusion
The deployment of a Valheim dedicated server via Docker represents a significant advancement in the ease and reliability of private server hosting. By leveraging containerization, administrators can isolate the server environment, automate updates and backups, and simplify mod management. The lloesche/valheim-server image stands out as a mature and feature-rich option, offering robust support for BepInEx and automated maintenance tasks. The community-valheim-tools/valheim-server fork provides additional platform support and monitoring features, making it a suitable choice for diverse hardware environments. The mbround18/valheim image offers an alternative configuration model with built-in automation for updates and backups. Each of these solutions caters to different administrative preferences and technical requirements. The key to a successful deployment lies in understanding the underlying architecture, properly configuring volume mappings, and implementing rigorous backup and monitoring practices. As the Valheim community continues to grow, the use of Dockerized servers will likely become the standard for dedicated hosting, offering a seamless and scalable solution for players and server administrators alike. The ability to quickly provision, update, and recover a server ensures that the Norse realm remains a stable and enjoyable environment for all participants.