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
2026-09-10 11:52:51 -04:00
parent ab4f13a385
commit 16c8331379
1 changed files with 28 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
docs/00 INBOX/ai/steamcmd servers.md
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.
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.
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:
@@ -76,39 +44,16 @@ The host owns deployment-specific values:
- secret choice
- network placement
A host can run the game module directly during validation:
```nix
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.
A host can run the game module directly during validation.
For Valheim, the host passed only deployment values to `modules.services.games.valheim`.
The game module translated those values into `modules.services.steamcmd` options.
## Stage 3: Add UDP ingress
Many game servers use UDP.
HTTP virtual hosts do not route raw UDP traffic.
Extend `registry.route` with UDP ports:
```nix
registry.route.pikachu.valheim = {
domain = "valheim.alexion.dev";
udp.ports = [
2456
2457
];
};
```
Extend `registry.route` with the UDP ports for the public route.
Keep `domain` mandatory.
Nix does not own public DNS today.
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`.
It renders nginx `stream` entries for UDP routes.
```nginx
server {
listen 2456 udp;
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
```
Configure public DNS outside Nix to point the route domain at the public IP.
Configure LAN DNS outside Nix to point the same route domain at the reverse-proxy guest IP.
Configure router forwarding outside Nix to forward the documented UDP ports to the reverse-proxy guest.
Use the game documentation to choose the port list.
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:
```nix
guests.valheim = {
enable = true;
vlan = 20;
address = "10.23.20.197";
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)
];
};
};
};
```
- VLAN
- guest address
- host paths for SteamCMD files, server files, and server state
- server name
- reverse-proxy route
The generic guest machinery publishes registry entries.
```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;
```
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.
## Secrets
Use SOPS for game server passwords.
Use one shared secret when servers can share a password:
```yaml
services:
game-servers:
password: <password>
```
The Valheim guest defaults to:
```nix
passwordSecret = "services/game-servers/password";
```
Use one shared secret when servers can share a password.
The current shared key is `services/game-servers/password`.
The host decrypts the secret.
The guest module bind-mounts the decrypted file into the guest.
@@ -227,16 +108,16 @@ sops-host secrets/shared.yaml
## Validation
Evaluate the host:
Evaluate the host before deployment:
```sh
nix eval .#nixosConfigurations.pikachu.config.system.build.toplevel.drvPath --raw
nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
```
Deploy the host:
```sh
deploy-to pikachu
deploy-to <host>
```
Check the host secret:
@@ -248,20 +129,20 @@ sudo test -s /run/secrets/services/game-servers/password && echo secret-ok
Check the guest:
```sh
sudo systemctl status container@valheim.service --no-pager
sudo systemctl status container@<guest>.service --no-pager
```
Check the guest secret:
```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:
```sh
sudo nixos-container run valheim -- systemctl status valheim.service --no-pager
sudo nixos-container run valheim -- journalctl -u valheim.service -n 200 --no-pager
sudo nixos-container run <guest> -- systemctl status <game>.service --no-pager
sudo nixos-container run <guest> -- journalctl -u <game>.service -n 200 --no-pager
```
Wait for the game-specific ready log.
@@ -275,26 +156,17 @@ Opened Steam server
Check game UDP listeners:
```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:
```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:
```text
valheim.alexion.dev:2456
```
Test direct guest connectivity when ingress fails:
```text
10.23.20.197:2456
```
Test the client through LAN DNS or public DNS.
Test direct guest connectivity when ingress fails.
## Operational notes