PhValheim Server

Need help?

Navigation

What is it?

PhValheim is a two-part world and client manager for Valheim (with aspirations of becoming game agnostic), it keeps server and client files in lock-step, ensuring all players have the same experience.

PhValheim is constently being improved. Make sure you maintain backups of your stateful data, beyond what PhValheim already backs up.

Why?

Valheim is a fantastic game and the more we play the more we want. Modding Valheim is simple to do but difficult to manage across all players. Keeping the remote server and clients in-sync are nearly impossible without something like PhValheim. While mod managers work well (Thunderstore and Nexus Mods), they don't work in a federated manner, eventaully resulting in clients being out of sync with each other and the remote server. PhValheim's primary goal is to solve this problem.

PSA

Mods are great and PhValheim makes it stupid simple to install them but keep in mind that the primary reason your game may not be working is due to the combination of mods you're using. Not all mods are made equal and most mods become "broken" after a major game update. If you have issues with your game running, please be sure to deploy a vanilla world (no mods selected) before submitting an issue.

What are the features of PhValheim?

• Runs in a single Docker container
• Login with Steam (SteamAPIKey is required)
• Quickly deploy unique worlds at the click of a button, with any combination of mods.
• Deploy any world with a specified Seed, or NULL will deploy a "default" Seed, provided during container deployment.
• Automatically deploys "required" mods, ensuring mandatory mods are always running.
• Manage a unique "allowlist" of users for each world.
• Global and unique world logs files for every aspect of PhValheim and its running processes.
• Update a world and all linked mods at the click of a button.
• Stores copies of recently downloaded mods for reuseability.
• Automatically backs up all world files every 30 minutes (can be pointed to disparate disks to ensure storage diversity).
• The Public web interface displays current MD5SUM of world client payload, created and last updated timestamps, active memory that the world is consuming, "PhValheim Client Download Link", and an instant "Launch!" link.
• The Admin web interface provides access to all manager features, which are completely isolated from the public interface.

How does it work?

Server

As mentioned above, PhValheim Server runs in a docker container. Out-of-the-box the container runs a few services:

• PhValheim Engine
  • The engine is responsible for all communication and execution between the supporting services mentioned below and the game's engine.
    • Listens for engine commands (create, start, stop, update, delete)
    • Builds client payloads after world creation and world updates.
• CRON (scheduler)
  • tsStoreStync
    • Syncs Thunderstore's entire Valheim Mod database every 12hrs (just the metadata)
  • worldBackup
    • Backs up all worlds every 30 minutes (default is 10 backups to keep, configurable)
  • utilizationMonitor
    • Brings real-time utilization of each world and process. Currently only provides real-time memory utilization for each world which is displayed on the public interface.
• Supervisor
  • The process watcher and executor. Supervisor manages all PhValheim processes, including every world deployed.
• NGINX
  • All Public and Admin interfaces are published via NGINX.
• MariaDB
  • All stateful (minus the Valheim and Steam binaries) are stored in MariaDB.

PhValheim Client

All of this is great but useless without a way to ensure the client behaves as expected. This is where PhValheim Client comes in. PhValheim Client is a mandatory companion application that runs on all Windows clients. It's a small C# application that registers a new "phvalheim://" URL to your Windows Registry. This allows your computer to recgonize and understand PhValheim Server payload URLs. When a PhValheim URL is clicked, the PhValheim Client pulls the URL into memory and decodes the information, instructing your PC what to do.

Here's the workflow (after the client has been installed)

1. Click a "phvalheim://" URL
2. Windows will send the URL to PhValheim Client's binary.
3. PhValheim Client will decode the URL, extracting the necessary information to:
   • Compare the remote world's MD5SUM (from PHValehim Server's database) with the local copy. If the local copy matches, proceed. Otherwise, download the new payload.
     • This payload includes all necessary mods, configs and depedencies to match the remote world and your fellow player's world.
   • Instruct PhValheim Client which PhValheim Server to connect to and which world endpoint to connect to.

     Note: PhValheim Client installs all related files to %appdata%/PhValheim, in addition to modifying your local install of Valheim's Steam directory to include the necessary bootstrap libraries for BepInEx to properly run (all mod managers do this already).

Architecture

Highlevel

Authentication and Authorization

Access to each world is controlled by the PhValheim database. We associate the SteamID of each player to every world we want to grant access to. The PhValheim Server will store SteamIDs to grant access to both the public web UI (library of worlds) and the allowList.txt file associated with each world. This ensures only allowed "citizens" can see the world in the UI and make a logical connection to the world itself (UDP).

Here is a swimlane depiction of the authentication and authorization workflow:

Screenshots

Public Login Page

Public Home

http://[dockerhost]:8080

Admin Home

http://[dockerhost]:8081

New World Creation

World Editor

Mods Viewer

Citizens Editor

Engine Logs

World Log

File Manager

Deployment

Unraid (search for PhValheim in the community app store)

Docker Command Line

docker create \
       --name='myPhValheim-server1' \
               -p '8080:8080/tcp' \
               -p '8081:8081/tcp' \
               -p '25000-26000:25000-26000/udp' \
               -e 'basePort'='25000' \
               -e 'defaultSeed'='szN8qp2lBn' \
               -e 'backupsToKeep'='10' \
               -e 'phvalheimHost'='phvalheim-dev.phospher.com' \
               -e 'gameDNS'='37648-dev1.phospher.com' \
               -e 'steamAPIKey'='0123456789' \
               -e 'phvalheimClientURL'='https://github.com/brianmiller/phvalheim-client/raw/master/published_build/phvalheim-client-installer.exe' \
               -v '/mnt/docker_persistent/phvalheim':'/opt/stateful':Z \
               -v '/mnt/phvalheim_backups/':'/opt/stateful/backups':Z \
               theoriginalbrian/phvalheim-server:latest``

docker start myPhValheim-server1

Container Variables

all variables are mandatory

Container Volumes and Persistent Storage

all paths are mandatory

Container Ports

all ports are mandatory

Reverse Proxy Config Example

Optional: Here's the config I use for my reverse proxy. It's a standard proxy pass config that helps with TLS termination.

server {
        listen 80;
        server_name phvalheim.phospher.com;
        rewrite ^ https://$http_host$request_uri? permanent;
        server_tokens off;
}

server {
        listen 443 ssl;
        server_name phvalheim.phospher.com phvalheim;

        ssl_certificate /mnt/certs/live/phospher.com/fullchain.pem;
        ssl_certificate_key /mnt/certs/live/phospher.com/privkey.pem;
        ssl_session_cache shared:SSL:10m;

        ssl_stapling on;
        ssl_stapling_verify on;
        #ssl_verify_client off;

        real_ip_header     X-Forwarded-For;
        real_ip_recursive  on;

        location / {
                proxy_pass http://37648-dev1.phospher.com:8080;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Host $server_name;
                proxy_set_header X-Forwarded-Proto https;
                proxy_request_buffering off;
                access_log /config/nginx/logs/phvalheim.access.log;
                error_log /config/nginx/logs/phvalheim.error.log;
                proxy_read_timeout 1200s;
                client_max_body_size 0;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
        }
}

Custom Config Folders

Optional: "custom_configs" folder - configs can be put into custom_config in order for them to get pushed/synced to clients when you perform updates / change mods on a server

Optional: "custom_configs_secure" folder - configs can be put into custom_config_secure in order for them to not be sent or synced to clients, but persist between updates/mod changes

Reference Material

Generate your Steam API Key

• Navigate to the Register Steam Web API Key portal to generate your key. Enter your PhValheim's external DNS hostname and copy your key. This is the key you must pass to PhValheim's "SteamAPIKey" variable on start.

  Do not share your key. The one below has been revoked ;)