Need help?
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.
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.
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.
- 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.
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.
- The engine is responsible for all communication and execution between the supporting services mentioned below and the game's engine.
- 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.
- tsStoreStync
- 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.
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.
- Click a "phvalheim://" URL
- Windows will send the URL to PhValheim Client's binary.
- 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.
- 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.
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).
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).
http://[dockerhost]:8080
http://[dockerhost]:8081
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
| Variable | Description |
|---|---|
| basePort | The port your first world will use. This must be the beginning of the port range passed to the container on start. |
| defaultSeed | The seed used when a seed isn't provided during world creation. |
| backupsToKeep | How many backups to keep on disk before deleting the oldest. |
| phvalheimHost | The FQDN of your PhValheim server your users will connect to. |
| gameDNS | The FQDN your users will connected their Valheim client to. This can be the same as phvalheimHost, if needed. |
| steamAPIKey | Your SteamAPI key used for player identification and authorization. See Generate Steam API Key for help. |
| phvalheimClientURL | The hosted URL for PhValheim Client downloads. You can change this if you prefer to host your own client files. |
| Container Path | Description |
|---|---|
| /opt/stateful | This volume stores all persistent data for your worlds, mods, PhValheim database, and configuration files. |
| /opt/stateful/backups | This volume is the destination of world backups. It's a good idea to set this to a different disk for disaster recovery. |
| Container Port | Description |
|---|---|
| 8080/tcp | This is the port the internal web service listens on and is the interface you want exposed to the public. Without this, nothing works. |
| 8081/tcp | This is the port the admin interface listens on. This should not be accessible from the public internet. Do not forward this port in your firewall/router unless you know what you're doing. |
| 25000-26000/udp | This is the port range used by PhValheim worlds. |
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;
}
}
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
- 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.
