lloesche Valheim Server Docker Settings Explained

The lloesche valheim server docker search now leads to a maintained community project: the former repository address redirects to community-valheim-tools, which publishes the image under a new namespace. Its variables such as CROSSPLAY, BACKUPS_CRON and WORLD_NAME are the image maintainer’s interface, not official Valheim launch flags. This reference explains what those settings change, where persistent files belong and what to check before pointing the container at your crew’s world. It does not claim this example passed a join, restore or shutdown test.

Check the image name before copying an old Compose file#

The current image is ghcr.io/community-valheim-tools/valheim-server; older guides may still show ghcr.io/lloesche/valheim-server. The project continues under the community maintainer, and its latest listed release is v1.4.0, dated September 20, 2026. The public package metadata lists linux/amd64. That does not establish native ARM support, so check the exact architecture of a NAS or single-board computer before you install anything.

The current README and v1.4.0 release notes describe image behavior. Iron Gate’s dedicated-server manual describes the game’s own settings. Keep those sources separate: an environment variable with a Valheim-sounding name is not automatically an official game setting.

Keep the image, world and server files in separate places#

A container can be replaced without deleting files mounted from the host, but data left only inside the container layer goes with it. This example pins the image and maps two host folders: /config for worlds, settings and permission lists, and /opt/valheim for the downloaded server plus its SteamCMD depot cache. If you mount the latter, keep that cache paired with the server installation it belongs to.

services:
  valheim:
    image: ghcr.io/community-valheim-tools/valheim-server:1.4.0
    container_name: valheim
    restart: unless-stopped
    stop_grace_period: 2m
    ports:
      - "2456-2457:2456-2457/udp"
    volumes:
      - ./config:/config
      - ./server:/opt/valheim
    secrets:
      - server_password
    environment:
      SERVER_NAME: "Midgard Crew"
      WORLD_NAME: "Midgard"
      SERVER_PASS_FILE: /run/secrets/server_password
      SERVER_PUBLIC: "false"

secrets:
  server_password:
    file: ./secrets/server_password

The port mapping above is for the Steam route using the default start port. It is not a complete firewall or router configuration. stop_grace_period gives Compose up to two minutes before it force-kills a stopped container; it is a timeout allowance, not evidence that the server saved correctly.

Use a separate host folder for each service and keep it outside your game’s working directory. The generic Valheim Docker setup and restore walkthrough covers named volumes and a copied-world restore. This image-specific guide focuses on the settings that decide which paths the current container uses.

If you also plan server-side mods, see the Valheim Linux or Docker mods guide for BepInEx paths and what survives container recreation.

Set the name, world and password intentionally#

SERVER_NAME controls the server-browser name. WORLD_NAME selects the directory inside worlds_local; if that name does not match your existing world, the server may create or select another one. It does not rename the files on your behalf. For Valheim 1.0, an existing world is stored as a directory; older saves use a .db/.fwl basename. Confirm the current layout in /config/worlds_local before changing the value.

SERVER_PASS has a documented default of secret and a minimum length of five characters. Never keep that default for a shared server. The Compose example uses a file-backed secret so the password does not sit in the YAML or a shell command. Create ./secrets/server_password with a unique password, restrict access to that file, and add the path to your local ignore policy. Do not commit a live password or paste it into a public support post.

Other image variables can replace permission lists too: ADMINLIST_IDS, BANNEDLIST_IDS and PERMITTEDLIST_IDS each override the corresponding existing file when set. If you already manage those lists under /config, do not add an environment value unless you intend that behavior. The image README marks variable names and values as case-sensitive.

Choose Steam or crossplay as a separate network decision#

This image starts with CROSSPLAY=false, so its default is the Steam backend. CROSSPLAY=true is the image’s switch to the PlayFab relay; it is not the same text as Iron Gate’s -crossplay argument, even though the two settings select the same broad route. The maintainer README says crossplay opens an additional UDP port, 2458, alongside the default 2456 and 2457 ports.

For the Steam backend, publish the configured UDP start port and the next port. With the default SERVER_PORT=2456, that is 2456–2457. For the image’s crossplay mode, follow its current README for the extra port mapping and then check the firewall on the machine running Docker. The official manual says the crossplay relay does not require router port forwarding. Router forwarding, Docker’s port publishing and a host firewall rule are separate layers; do not copy one answer between them.

SERVER_PUBLIC=true controls whether the image asks for browser listing. It is not an access-control setting. A listed server still uses its password and permission policy. If you change the start port or backend, write down the values beside the server identity and check them again after an update. The broader dedicated-server route comparison helps separate image choice from where the machine runs.

Set backup retention and update timing#

The image creates a backup at startup and then hourly by default. BACKUPS=true enables that behavior, BACKUPS_CRON=5 * * * * schedules the periodic job for five minutes past the hour, and BACKUPS_DIRECTORY=/config/backups puts the files under the persistent config mount. BACKUPS_MAX_AGE=3 removes backups older than three days. BACKUPS_MAX_COUNT=0 means there is no count limit; the age limit still applies.

The backup job runs while the server is up. For Valheim 1.0’s multi-file worlds, the maintainer says it checks committed-save markers and retries up to three times when it detects a save changing during the read. If all retries miss a quiet point, it keeps the backup and logs a warning. That is useful behavior to understand, but it is not a restore test or an off-host copy. Keep the backup directory outside worlds_local and copy an independent recovery set elsewhere.

The image checks for Valheim updates every 15 minutes by default with UPDATE_CRON=*/15 * * * *. UPDATE_IF_IDLE=true means it waits until no players are connected before applying an update. A changed image tag and an updated game server inside the image are separate changes, so record both when planning a release. The general Docker guide explains a separate copied-world restore; use that procedure before relying on any backup set.

Read the restart clock and optional hooks carefully#

The default daily restart is RESTART_CRON=10 5 * * *, with RESTART_IF_IDLE=true. TZ=Etc/UTC sets the container’s time zone, so that schedule means 05:10 UTC rather than your local wall clock. Convert it for your region and revisit the conversion when daylight-saving time changes. The safe update guide covers the wider maintenance decision.

An event hook is a command executed at a named image event. For example, PRE_SERVER_SHUTDOWN_HOOK runs before the server shuts down and blocks shutdown until it returns. The current README says a pre-shutdown hook held longer than 90 seconds causes supervisord to hard-kill the process. POST_SERVER_SHUTDOWN_HOOK runs after the server has stopped. Keep hooks short, test their shell quoting with a disposable world and leave the container’s stop grace period longer than the work you expect it to do.

1. Check the effective time zone

   Read TZ and translate the cron expression into your own time zone. Do not assume the host and container clocks use the same zone.

2. Review each hook as shell code

   Confirm its environment and YAML quoting, then run it against a throwaway file before connecting it to a backup or external service.

The image’s optional hooks are not Valheim flags. Avoid storing tokens, webhook URLs or passwords directly in a Compose file that is shared with the whole crew.

Test a copy before pointing the container at the crew’s world#

Treat the configuration as a candidate until you check its actual mount paths, game build and expected world. This article reviewed the current image documentation; it did not run a disposable world, join from a client, restore a backup or test a graceful stop. Use a copy to check the behavior you need before replacing a live setup.

1. Record the version and paths

   Save the image tag or digest, WORLD_NAME, backend, port mappings and host paths for /config and /opt/valheim.

2. Start an isolated world

   Point the container at a new test folder, not the crew’s only save. Check the logs for the expected world name and the server-ready message Game server connected.

3. Stop and inspect the copy

   Stop with Compose, then confirm the container exits within its grace period and that the test world files remain under the mapped host directory. This is a result to observe, not a result this guide claims.

4. Verify backup and recovery separately

   Check a backup’s path and timestamp. Before trusting it, restore that copy to a different folder or isolated server and confirm it opens without writing to the original.

A self-hosted container remains a sensible route if someone in your crew wants to own image updates, storage and recovery. If you would rather manage the world through game controls instead of maintaining a Compose file and schedules, we recommend Game Hosting for Valheim: the integrated panel covers settings and scheduled restarts, and plans include three free backup slots that can be scheduled, restored, downloaded or locked. Those are documented product features, not a performance result or a promise that a particular save will restore. Renting also will not repair a broken world file or an incompatible client build.