alexion/dev
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: trim SteamCMD workflow examples

Browse Source
This commit is contained in:
alexion committed 2026-09-10 11:52:51 -04:00
1 parent ab4f13a385
commit 16c8331379
1 file changed
+28 -156
Download Patch File Download Diff File Expand all files Collapse all files
docs/00 INBOX/ai/steamcmd servers.md
+28 -156
View File
@@ -10,40 +10,8 @@ Move deployment behavior into a guest module after validation.
Prove the generic SteamCMD runner before adding game-specific modules. Prove the generic SteamCMD runner before adding game-specific modules.
Configure `modules.services.steamcmd` directly in the host file. Configure `modules.services.steamcmd` directly in the host file.
```nix
modules.services.steamcmd = {
enable = true;
steamDir = "/pikachu/data/steamcmd";
serviceName = "valheim";
appId = 896660;
installDir = "/pikachu/data/servers/valheim/main";
stateDir = "/pikachu/media/games/servers/valheim/main";
executable = "./valheim_server.x86_64";
arguments = [
"-nographics"
"-batchmode"
"-name"
"main"
"-port"
"2456"
"-world"
"main"
"-savedir"
config.modules.services.steamcmd.stateDir
"-password"
"foobarbaz"
"-public"
"0"
];
udpPorts = [
2456
2457
];
};
```
Use real values for the target game. Use real values for the target game.
The example shows Valheim because it was the first server added. For the first Valheim deployment, the direct configuration set the Steam app ID, install path, state path, executable, command-line arguments, and UDP ports directly on `modules.services.steamcmd`.
This layer owns shared SteamCMD behavior: This layer owns shared SteamCMD behavior:
@@ -76,39 +44,16 @@ The host owns deployment-specific values:
- secret choice - secret choice
- network placement - network placement
A host can run the game module directly during validation: A host can run the game module directly during validation.
For Valheim, the host passed only deployment values to `modules.services.games.valheim`.
```nix The game module translated those values into `modules.services.steamcmd` options.
modules.services.games.valheim = {
enable = true;
steamDir = "/pikachu/data/steamcmd";
installDir = "/pikachu/data/servers/valheim/main";
stateDir = "/pikachu/media/games/servers/valheim/main";
serverName = "main";
passwordFile = "/run/secrets/services/game-servers/password";
};
```
The game module translates its options into `modules.services.steamcmd`.
It passes the app ID, executable, arguments, and ports to the runner.
## Stage 3: Add UDP ingress ## Stage 3: Add UDP ingress
Many game servers use UDP. Many game servers use UDP.
HTTP virtual hosts do not route raw UDP traffic. HTTP virtual hosts do not route raw UDP traffic.
Extend `registry.route` with UDP ports: Extend `registry.route` with the UDP ports for the public route.
```nix
registry.route.pikachu.valheim = {
domain = "valheim.alexion.dev";
udp.ports = [
2456
2457
];
};
```
Keep `domain` mandatory. Keep `domain` mandatory.
Nix does not own public DNS today. Nix does not own public DNS today.
The route domain identifies the public route. The route domain identifies the public route.
@@ -117,31 +62,9 @@ A future LAN DNS module can also consume it.
The reverse-proxy module joins `registry.route` with `registry.address`. The reverse-proxy module joins `registry.route` with `registry.address`.
It renders nginx `stream` entries for UDP routes. It renders nginx `stream` entries for UDP routes.
```nginx Configure public DNS outside Nix to point the route domain at the public IP.
server { Configure LAN DNS outside Nix to point the same route domain at the reverse-proxy guest IP.
listen 2456 udp; Configure router forwarding outside Nix to forward the documented UDP ports to the reverse-proxy guest.
proxy_pass 10.23.20.197:2456;
}
```
Configure public DNS outside Nix:
```text
valheim.alexion.dev -> public IP
```
Configure LAN DNS outside Nix:
```text
valheim.alexion.dev -> reverse-proxy guest IP
```
Configure router forwarding outside Nix:
```text
2456/udp -> reverse-proxy guest:2456
2457/udp -> reverse-proxy guest:2457
```
Use the game documentation to choose the port list. Use the game documentation to choose the port list.
For Valheim, the official guide says it uses the configured port and port plus one. For Valheim, the official guide says it uses the configured port and port plus one.
@@ -157,62 +80,20 @@ It also connects guest address and route options to the registry.
The host config then owns deployment wiring: The host config then owns deployment wiring:
```nix - VLAN
guests.valheim = { - guest address
enable = true; - host paths for SteamCMD files, server files, and server state
vlan = 20; - server name
address = "10.23.20.197"; - reverse-proxy route
steamPath = "/pikachu/data/steamcmd";
installPath = "/pikachu/data/servers/valheim/main";
statePath = "/pikachu/media/games/servers/valheim/main";
serverName = "main";
reverseProxy = {
enable = true;
route = {
domain = "valheim.alexion.dev";
udp.ports = [
config.guests.valheim.port
(config.guests.valheim.port + 1)
];
};
};
};
```
The generic guest machinery publishes registry entries. The generic guest machinery publishes `guests.<name>.address` as `registry.address.<host>.<name>`.
It also publishes `guests.<name>.reverseProxy.route` as `registry.route.<host>.<name>` when reverse proxying is enabled.
```nix
guests.valheim.address = "10.23.20.197";
```
becomes:
```nix
registry.address.pikachu.valheim = "10.23.20.197";
```
The guest route becomes:
```nix
registry.route.pikachu.valheim = config.guests.valheim.reverseProxy.route;
```
## Secrets ## Secrets
Use SOPS for game server passwords. Use SOPS for game server passwords.
Use one shared secret when servers can share a password: Use one shared secret when servers can share a password.
The current shared key is `services/game-servers/password`.
```yaml
services:
game-servers:
password: <password>
```
The Valheim guest defaults to:
```nix
passwordSecret = "services/game-servers/password";
```
The host decrypts the secret. The host decrypts the secret.
The guest module bind-mounts the decrypted file into the guest. The guest module bind-mounts the decrypted file into the guest.
@@ -227,16 +108,16 @@ sops-host secrets/shared.yaml
## Validation ## Validation
Evaluate the host: Evaluate the host before deployment:
```sh ```sh
nix eval .#nixosConfigurations.pikachu.config.system.build.toplevel.drvPath --raw nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
``` ```
Deploy the host: Deploy the host:
```sh ```sh
deploy-to pikachu deploy-to <host>
``` ```
Check the host secret: Check the host secret:
@@ -248,20 +129,20 @@ sudo test -s /run/secrets/services/game-servers/password && echo secret-ok
Check the guest: Check the guest:
```sh ```sh
sudo systemctl status container@valheim.service --no-pager sudo systemctl status container@<guest>.service --no-pager
``` ```
Check the guest secret: Check the guest secret:
```sh ```sh
sudo nixos-container run valheim -- test -s /run/secrets/services/game-servers/password sudo nixos-container run <guest> -- test -s /run/secrets/services/game-servers/password
``` ```
Check the game service: Check the game service:
```sh ```sh
sudo nixos-container run valheim -- systemctl status valheim.service --no-pager sudo nixos-container run <guest> -- systemctl status <game>.service --no-pager
sudo nixos-container run valheim -- journalctl -u valheim.service -n 200 --no-pager sudo nixos-container run <guest> -- journalctl -u <game>.service -n 200 --no-pager
``` ```
Wait for the game-specific ready log. Wait for the game-specific ready log.
@@ -275,26 +156,17 @@ Opened Steam server
Check game UDP listeners: Check game UDP listeners:
```sh ```sh
sudo nixos-container run valheim -- ss -lunp | grep -E '2456|2457|valheim' sudo nixos-container run <guest> -- ss -lunp | grep -E '<ports>|<game>'
``` ```
Check reverse-proxy UDP listeners: Check reverse-proxy UDP listeners:
```sh ```sh
sudo nixos-container run reverse-proxy -- ss -lunp | grep -E '2456|2457|nginx' sudo nixos-container run reverse-proxy -- ss -lunp | grep -E '<ports>|nginx'
``` ```
Test the client through LAN DNS or public DNS: Test the client through LAN DNS or public DNS.
Test direct guest connectivity when ingress fails.
```text
valheim.alexion.dev:2456
```
Test direct guest connectivity when ingress fails:
```text
10.23.20.197:2456
```
## Operational notes ## Operational notes