Setting Up a Modded Valheim Server on Your Homelab with Docker Compose

I run a modded Valheim server on my homelab. I use Docker Compose to keep things tidy and reproducible. The setup runs on an old spare PC with Ubuntu Server and Portainer for quick management. This guide shows exactly what I do, with the compose file, tips for mods and how I update the server without downtime.

Getting Started with Valheim Server Setup

Overview of Valheim and Its Gameplay

Valheim is a survival sandbox built around exploration and building. It is designed for co‑op play. A dedicated server keeps the world online and stable. The server is lightweight compared with modern triple A games, which makes it ideal for a homelab node such as an old i7 7700k.

Importance of Modded Servers

Mods change gameplay and add longevity. Popular mods include quality of life tweaks and combat reworks. For a reliable modded games experience, the server and clients must match mods and versions. I run BepInEx and ValheimPlus on both client and server. If they mismatch, players will get kicked or see crashes.

Setting Up Your Environment

I use Ubuntu Server LTS on the homelab node. Hardware is not critical. CPU core count helps with many players. RAM matters if you run other services. I keep the server on its own Docker network and expose only the UDP ports Valheim needs. I also run Portainer as a container so I can restart or inspect logs from a web UI.

What I install first:

• Docker and the docker compose plugin (so I can run docker compose up).
• Portainer for container management.
• A persistent data path on an SSD or large HDD for world saves and mods.

Keep your world folder backed up. I snapshot the folder to another drive nightly with a simple rsync cron.

Configuring Docker Compose for Valheim

Installing Docker and Docker Compose

On Ubuntu, I run:

• sudo apt update
• sudo apt install -y docker.io docker-compose-plugin
• sudo usermod -aG docker $USER

That gives me the docker and the compose plugin so commands like docker compose up -d work. I start and enable Docker with systemctl if needed. Portainer I deploy as another container; it gives a web UI for logs, envs and container restarts.

Creating Your Docker Compose File

Here is the minimal docker-compose.yml I use. Replace the environment values with your server name, world and password.

version: ‘3.8’
services:
valheim:
image: lloesche/valheim-server
containername: valheim
restart: unless-stopped
ports:
– “2456-2458:2456-2458/udp”
environment:
– NAME=MyValheimServer
– WORLD=MyWorld
– PASSWORD=supersecret
– PUBLIC=1
– TZ=Europe/London
volumes:
– ./valheim-data:/config
shmsize: ‘1gb’

Key points:

• Expose UDP ports 2456 to 2458. The game uses UDP. TCP will not work.
• Put world saves and mods into the mounted ./valheim-data (or any persistent path). That keeps saves outside the container.
• Set TZ to keep timestamps readable.

For modded games, I mount a folder that contains BepInEx and ValheimPlus. The server image will pick those up if they are in the game directory structure inside /config. If you prefer, pick a Docker image already built for mods. I prefer to control the mod files directly.

Running Your Valheim Server

Start it with:

• docker compose up -d

Then check logs:

• docker compose logs -f valheim

If you are using Portainer, the UI shows logs and container status. If the server fails to create the world on first run, check permissions on the mounted volume. I usually chown the folder to my UID:GID or set PUID/PGID env vars if the image supports them.

When testing, join from the client by selecting “Join Game” and entering the server name and password. If the server does not appear in the server list, use direct connect with the IP and port.

Managing and Updating Your Server

I keep updates simple and low risk.

To update the container image:

1. docker compose pull
2. docker compose up -d

If you change mods:

1. Stop the server: docker compose stop
2. Update files in the mounted mod folder
3. Start the server: docker compose start

I avoid in-place edits while players are online. For minimal downtime, I run another container with the new image in a different compose project, copy the world saves over and switch DNS or port mapping. That is more advanced but useful when running several persistent services on one host.

Backups are simple rsync cron jobs:

• rsync -a –delete /home/valheim/valheim-data /mnt/backups/valheim-$(date +%F)

I keep at least three snapshots and rotate them.

Troubleshooting Common Issues

Ports and UDP are the most common problems. Check these items in order.

1. Firewall. Confirm UDP 2456-2458 are allowed on the host and on any upstream firewall. I use ufw on Ubuntu and run:

• sudo ufw allow 2456:2458/udp

1. Container logs. Use docker compose logs -f valheim to see startup errors. Permission denied on save files usually means the host mount has wrong ownership.

2. Mod mismatches. If clients crash or cannot connect, ensure the installed mod list and versions match exactly on client and server.

3. Server not appearing in the public list. Verify PUBLIC=1 if you want it public. Some home ISPs block game ports. Use a port test or try direct connect.

4. High CPU or memory. Check docker stats or Portainer to see per-container usage. Valheim will spike CPU when players are active. If the host is overloaded, consider moving the server to a box with more cores or reducing concurrent players.

5. Lost saves. If saves disappear after an update, check that the compose file mounts the save directory to a persistent host path. Without a mount, containers will drop data on recreation.

A few quick commands I use during troubleshooting:

• docker compose ps
• docker compose logs -f valheim
• docker compose exec valheim bash (only if the image provides bash)
• docker system df (check disk usage)

Final takeaways
Keep the server files persistent and backed up. Match mods between server and client. Use docker compose for repeatable deployments and Portainer for quick inspection. Run regular updates but stop the server before changing mods or world files. The setup is resilient and cheap to run on modest homelab hardware.