drummercraig/valheim-server repository overview

⁠Valheim Dedicated Server

A Docker-based Valheim dedicated server on Ubuntu 24.04 with BepInEx mod support, automatic backups, scheduled restarts, and Thunderstore mod management.

⁠Features

• One-command startup - Pull image and run
• BepInEx mod loader - Full mod support with automatic updates
• Thunderstore integration - Auto-download mods from URLs in modlinks.txt or remote Gist
• AzuAntiCheat support - Automatic whitelist/greylist management
• Automatic backups - Scheduled world backups with rotation
• Scheduled restart - Daily restart at configurable time (when server is empty)
• Idle restart - Restart after period of inactivity
• Crossplay support - Xbox/PC cross-platform play

⁠Quick Start (Experienced Users)

# Pull image
docker pull drummercraig/valheim-server:latest

# Create directory structure
mkdir -p valheim-server && cd valheim-server

# Download required files (option 1: all at once)
curl -L https://gist.github.com/drummercraig/0e1709e9775dd671593d8494c452497c/archive/1ce85ade66f0dc545fda1f9c868bd3c57a95d437.zip -o gist.zip \
  && unzip gist.zip && mv 0e1709e9775dd671593d8494c452497c-*/* . \
  && rm -rf gist.zip 0e1709e9775dd671593d8494c452497c-* && chmod +x *.sh

# Download required files (option 2: individual files)
curl -O https://gist.githubusercontent.com/drummercraig/0e1709e9775dd671593d8494c452497c/raw/docker-run.sh
curl -O https://gist.githubusercontent.com/drummercraig/0e1709e9775dd671593d8494c452497c/raw/valheim.env.example
curl -O https://gist.githubusercontent.com/drummercraig/0e1709e9775dd671593d8494c452497c/raw/modlinks.txt.example
chmod +x docker-run.sh

# Copy example files and configure
cp valheim.env.example valheim.env
cp modlinks.txt.example modlinks.txt

# Configure (edit SERVER_NAME, WORLD_NAME, SERVER_PASS, PUID, PGID)
nano valheim.env

# Configure mods (add Thunderstore URLs, one per line)
nano modlinks.txt # (or Gist configuration, see detailed instructions)

# Optional: Set custom container name (edit CONTAINER_NAME variable)
nano docker-run.sh

# Create directories and configuration files to prep adminlist.txt, modlinks.txt etc.
# (optional - auto-created on first start)
./docker-run.sh setup

# AzuAntiCheat (optional - if using this mod)
nano AzuAntiCheatWhitelist.txt  # auto-created from modlinks.txt
nano AzuAntiCheatGreylist.txt   # optional client mods

# Open firewall (Ubuntu/Debian)
sudo ufw allow 2456:2457/udp && sudo ufw allow 2456:2457/tcp

# Start server
./docker-run.sh
./docker-run.sh logs

⁠Commands

./docker-run.sh              # Start server
./docker-run.sh stop         # Stop server
./docker-run.sh restart      # Restart server
./docker-run.sh logs         # View logs (Ctrl+C to exit)
./docker-run.sh status       # Check if running
./docker-run.sh shell        # Shell into container
./docker-run.sh mods         # Run mod manager on host
./docker-run.sh setup        # Create directories and files

Important: Always use ./docker-run.sh commands instead of direct docker commands (like docker restart). The script handles directory migrations, volume mounts, and configuration updates that won't apply if you restart the container directly.

⁠Directory Structure

valheim-server/
├── docker-run.sh                    # Server control script
├── valheim.env                      # Server configuration
├── modlinks.txt                     # Thunderstore mod URLs
├── AzuAntiCheatWhitelist.txt        # Anticheat whitelist (auto-created)
├── AzuAntiCheatGreylist.txt         # Anticheat greylist (auto-created)
├── valheim_data/                    # Game files (managed by Steam)
├── valheim_config/
│   └── valheim/                     # Valheim config directory
│       ├── worlds_local/            # World saves
│       ├── characters_local/        # Character saves
│       ├── adminlist.txt            # Admin Steam IDs
│       ├── bannedlist.txt           # Banned Steam IDs
│       └── permittedlist.txt        # Permitted Steam IDs
├── valheim_config/bepinex/
│   ├── plugins/                     # Mod DLLs
│   ├── config/                      # Mod configs
│   └── patchers/                    # Patcher mods
└── valheim_backups/                 # World backups

⁠Environment Variables

⁠Ports

⁠Detailed Guide (New Users)

⁠Prerequisites

• Docker installed on your system
  • Linux: curl -fsSL https://get.docker.com | sh
• Terminal access (Linux terminal)
• Open ports on your firewall/router for player connections

⁠Step 1: Create Server Directory

Open a terminal and create a folder for your server:

mkdir valheim-server
cd valheim-server

⁠Step 2: Download Server Files

Download the required files from the configuration gist⁠ using the commands in the Quick Start⁠ section above.

Copy example files to create your configuration:

cp valheim.env.example valheim.env
cp modlinks.txt.example modlinks.txt

⁠Step 3: Find Your User ID

The server needs to run with correct file permissions. Find your user/group ID:

id

You'll see output like: uid=1000(yourname) gid=1000(yourname)

Note the numbers after uid= and gid=.

⁠Step 4: Configure Your Server

Open valheim.env in a text editor:

nano valheim.env

Required changes:

Save and exit (in nano: Ctrl+X, then Y, then Enter).

⁠Step 5: Configure Mods (Optional)

If you want mods, edit modlinks.txt:

nano modlinks.txt

Add Thunderstore URLs, one per line:

# Lines starting with # are comments
https://thunderstore.io/c/valheim/p/ValheimModding/Jotunn/
https://thunderstore.io/c/valheim/p/Azumatt/AzuAntiCheat/

The mod manager automatically downloads and installs these when the server starts.

UPDATE_MODS behavior (set in valheim.env):

• UPDATE_MODS=true (default):

  • Syncs mods to match modlinks.txt on every server start
  • Downloads new or updated mods from Thunderstore
  • Removes mods no longer in modlinks.txt
  • Add/remove URLs and restart to apply changes
  • Config files in valheim_config/bepinex/config/ are preserved

• UPDATE_MODS=false:

  • Keeps existing mods intact (no sync on restart)
  • Only downloads mods that aren't already installed
  • Outdated mods are not updated (warning shown in logs)
  • Removed mods from modlinks.txt will NOT be deleted
  • Use this if you want to pin specific mod versions

⁠AzuAntiCheat Configuration (Optional)

If you're using the AzuAntiCheat⁠ mod, the mod manager automatically handles whitelist/greylist setup:

• AzuAntiCheatWhitelist.txt - Mods clients MUST have (auto-created from modlinks.txt)
• AzuAntiCheatGreylist.txt - Mods clients MAY have (optional client-side mods)

Both files use the same format as modlinks.txt (Thunderstore URLs, one per line).

To customize:

# Edit whitelist (required mods - defaults to your modlinks.txt)
nano AzuAntiCheatWhitelist.txt

# Edit greylist (optional client mods like UI improvements)
nano AzuAntiCheatGreylist.txt

The mod manager downloads these mods to valheim_config/bepinex/config/AzuAntiCheat_Whitelist/ and AzuAntiCheat_Greylist/ for the anticheat to verify.

⁠Remote Mod Lists (Gist)

Instead of using local files, you can fetch mod lists from remote URLs (e.g., GitHub Gists). This is useful for:

• Managing mods for multiple servers from one location
• Sharing mod lists with friends who run their own servers
• Updating mods without SSH access to the server

Setting up a GitHub Gist:

1. Go to gist.github.com⁠ and sign in
2. Create a new gist with your mod URLs (one per line, same format as modlinks.txt)
3. Click "Raw" on the file to get the raw URL
4. Copy the URL and paste it into valheim.env

Example valheim.env configuration:

MODLINKS_URL=https://gist.githubusercontent.com/username/gistid/raw/modlinks.txt
WHITELIST_URL=https://gist.githubusercontent.com/username/gistid/raw/whitelist.txt
GREYLIST_URL=https://gist.githubusercontent.com/username/gistid/raw/greylist.txt

When a URL is set, the remote file takes priority over the local file. Leave the URL empty to use local files.

Note: After updating your gist, restart the server to fetch the new mod list: ./docker-run.sh restart

⁠Step 6: Open Firewall Ports

Players need to connect through your firewall.

Ubuntu/Debian (UFW):

sudo ufw allow 2456:2457/udp
sudo ufw allow 2456:2457/tcp

RHEL/CentOS/Fedora (firewalld):

sudo firewall-cmd --permanent --add-port=2456-2457/udp
sudo firewall-cmd --permanent --add-port=2456-2457/tcp
sudo firewall-cmd --reload

For crossplay, also open port 2458:

# UFW
sudo ufw allow 2458/udp && sudo ufw allow 2458/tcp

# firewalld
sudo firewall-cmd --permanent --add-port=2458/udp
sudo firewall-cmd --permanent --add-port=2458/tcp
sudo firewall-cmd --reload

⁠Step 7: Start Your Server

./docker-run.sh

First startup takes 5-15 minutes as it:

1. Downloads the Docker image
2. Downloads Valheim via Steam (~1GB)
3. Installs BepInEx mod loader
4. Downloads mods from your modlinks.txt
5. Starts the server

Watch progress with:

./docker-run.sh logs

Press Ctrl+C to stop watching (server keeps running).

Your server is ready when you see: Game server connected

⁠Step 8: Connect to Your Server

1. Open Valheim and select your character
2. Click Join Game tab
3. Click Add Server
4. Enter: YOUR-IP:2456
   • Same network: use local IP (e.g., 192.168.1.100:2456)
   • Over internet: use public IP (find at whatismyip.com⁠)
5. Click Connect and enter your password

⁠Configuration Reference

⁠Server Identity

⁠Container Permissions

⁠Mod Management

When UPDATE_MODS=true, mods are synced to match modlinks.txt on every server start:

• New mods are downloaded from Thunderstore
• Updated mods are replaced with the latest version
• Mods removed from modlinks.txt are deleted
• AzuAntiCheat whitelist/greylist directories are synced similarly

Simply edit modlinks.txt and restart the server to add, update, or remove mods.

Plugin config files in valheim_config/bepinex/config/ are preserved. Set UPDATE_MODS=false to keep existing plugins and only download missing mods (removed mods will not be deleted).

⁠AzuAntiCheat Files

If using the AzuAntiCheat mod, these files control which mods clients can use:

Both use Thunderstore URLs, one per line (same format as modlinks.txt).

⁠World Modifiers

⁠Set Keys

⁠Scheduled Restart

Restarts the server at a specific time daily (when no players connected).

⁠Idle Restart

Restarts the server after a period of inactivity.

⁠Backups

⁠Startup Options

⁠Managing Your Server

⁠Update Game

The game updates automatically on restart:

./docker-run.sh restart

⁠Update Mods

When UPDATE_MODS=true, mods are freshly downloaded on every server start (plugins/patchers directories are cleared first). To add or remove mods:

1. Edit modlinks.txt (add or remove Thunderstore URLs)
2. Restart the server: ./docker-run.sh restart

Mods will automatically sync to match modlinks.txt on restart.

To manually run the mod manager without restarting:

./docker-run.sh mods

⁠View Backups

Backups are stored in valheim_backups/ with timestamps:

ls valheim_backups/

⁠Restore from Backup

./docker-run.sh stop
cp -r valheim_backups/YYYYMMDD_HHMMSS/worlds_local/* valheim_config/valheim/worlds_local/
./docker-run.sh

⁠Add Server Admins

Add Steam IDs (one per line) to valheim_config/valheim/adminlist.txt:

76561198012345678
76561198087654321

⁠Troubleshooting

⁠Permission Denied Errors

• Verify PUID and PGID match your id command output
• Run: sudo chown -R $(id -u):$(id -g) valheim_data valheim_config valheim_backups

⁠Server Won't Start

• Check logs: ./docker-run.sh logs
• Verify Docker is running: docker ps
• Check port availability: sudo lsof -i :2456

⁠Can't Connect

• Verify server is running: ./docker-run.sh status
• Check password is 5+ characters and doesn't contain server name
• Verify firewall ports are open
• For internet play, ensure router port forwarding is configured

⁠Mods Not Working

• Verify ENABLE_BEPINEX=true in valheim.env

• Check mod URLs are valid Thunderstore links

• Review logs for errors: ./docker-run.sh logs

• Ensure mods are compatible with current Valheim version

• Drummer's Place⁠

⁠Resources

• Thunderstore Mods⁠
• Valheim Wiki⁠
• Docker Documentation⁠