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

feat(nixos): add Palworld Tracion guest

Browse Source
This commit was merged in pull request #39.
This commit is contained in:
alexion
2026-09-10 14:37:50 -04:00
parent 8bd9ff166e
commit 9e7469796d
9 changed files with 525 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/.obsidian/workspace.json vendored
View File

@@ -22,6 +22,26 @@
}
}
]
},
{
"id": "72e6501450a46859",
"type": "tabs",
"children": [
{
"id": "06bc3d52246b600b",
"type": "leaf",
"state": {
"type": "markdown",
"state": {
"file": "00 INBOX/ai/steamcmd servers.md",
"mode": "source",
"source": true
},
"icon": "lucide-file",
"title": "steamcmd servers"
}
}
]
}
],
"direction": "vertical"
@@ -233,13 +253,16 @@
},
"active": "0c587e5452c16787",
"lastOpenFiles": [
"00 INBOX/how to setup a steamcmd server.md",
"00 INBOX/ai/steamcmd servers.md",
"03 wrk/ariadne.md",
"00 INBOX/ai/ariadne-cli-skeleton.md",
"00 INBOX/ai/ariadne-project-goals.md",
"TODO.md",
"00 INBOX/ai/dictionary-cli.md",
"00 INBOX/ai/dictionary-skill.md",
"03 wrk/falinks.md",
"03 wrk/ariadne.md",
"03 wrk/machoke.md",
"TODO.md",
"00 INBOX/home assistant agent integration.md",
"02 notes/falinks public surfaces.md",
"03 wrk/machoke.md~",
@@ -261,8 +284,6 @@
"00 INBOX/ai/hoopa design review findings.md",
"00 INBOX/ai/hoopa follow up decisions.md",
"01 sources/obsidian and ai were made for each other.md",
"99 meta/technical writing.md",
"99 meta/dictionary.md",
"99 meta/Untitled",
"03 wrk",
"02 notes",

125
docs/00 INBOX/how to setup a steamcmd server.md Normal file
View File

@@ -0,0 +1,125 @@
---
date-created: 2026-09-10 12:01
---
# How to set up a `steamcmd` server
This note explains how to add a SteamCMD-managed game server to the NixOS configuration.
Use these existing files as examples:
- `configs/nixos/modules/services/steamcmd.nix`
- `configs/nixos/modules/services/games/valheim.nix`
- `configs/nixos/guests/valheim.nix`
- `configs/nixos/hosts/pikachu/default.nix`
## Understand the layers
The shared `steamcmd` module installs and runs a dedicated server.
It owns the low-level systemd service, update service, user, directories, and firewall ports.
A game module maps game-specific options onto `modules.services.steamcmd`.
It hides Steam app IDs, executable names, launch arguments, and port calculations.
A guest module maps host-level storage, secrets, and resource limits onto the game module.
It keeps host paths outside the guest's interior configuration.
A host enables the guest and supplies network placement, storage paths, and routing.
## Create the game module
1. Create `configs/nixos/modules/services/games/<game>.nix`.
2. Add an option namespace at `modules.services.games.<game>`.
3. Add an `enable` option with `lib.mkEnableOption`.
4. Add options for game-specific settings.
5. Add options for `steamDir`, `installDir`, and `stateDir`.
6. Use `lib.mkIf config.modules.services.games.<game>.enable` for the module configuration.
7. Set `modules.services.steamcmd.enable = true`.
8. Pass `steamDir`, `installDir`, and `stateDir` to `modules.services.steamcmd`.
9. Set `serviceName` to the game service name.
10. Set `appId` to the Steam dedicated-server app ID.
11. Set `executable` to the server executable or a generated wrapper script.
12. Set `arguments` to the game launch arguments.
13. Set `udpPorts` to every UDP port the server needs.
14. Put secrets in runtime files instead of option values.
15. Read secret files from a wrapper script when the server needs secret values.
Use `configs/nixos/modules/services/games/valheim.nix` as the main pattern.
It wraps the executable because Valheim receives its password as a command-line argument.
## Create the guest module
1. Create `configs/nixos/guests/<game>.nix`.
2. Add an option namespace at `guests.<game>`.
3. Add host-path options for the SteamCMD metadata, install, and state directories.
4. Give host-path options a `null` default.
5. Add assertions that require each host path when the guest is enabled.
6. Define guest-internal paths in a `let` block.
7. Enable `guests.<game>.interior.modules.services.games.<game>`.
8. Pass the guest-internal paths to the game module.
9. Add mounts that bind host paths to the guest-internal paths.
10. Set directory mount `owner`, `group`, and `mode` together.
11. Mount secret files under `/run/secrets/...` when the game needs secrets.
12. Declare matching `sops.secrets` entries for those secret files.
13. Set conservative default resource limits under `guests.<game>.limits`.
Use `configs/nixos/guests/valheim.nix` as the main pattern.
It mounts the password secret into the guest and passes only the runtime path inward.
## Enable the guest on a host
1. Open the target host file under `configs/nixos/hosts/<host>/default.nix`.
2. Set `guests.<game>.enable = true`.
3. Set `vlan` and `address` for the guest.
4. Set host storage paths for SteamCMD metadata, server files, and state.
5. Set game options such as server name and port.
6. Enable reverse-proxy routing when the server needs external access.
7. Route every game UDP port exposed by the guest.
8. Add required secrets to the host's SOPS files.
Use the Valheim section in `configs/nixos/hosts/pikachu/default.nix` as the host-level pattern.
## Test the change
1. Stage new Nix files before evaluation.
Flake evaluation ignores untracked files.
```console
$ git add configs/nixos/modules/services/games/<game>.nix configs/nixos/guests/<game>.nix
```
2. Build the target host configuration.
```console
$ nixos-rebuild build --flake .#<host>
```
3. Deploy the host when the build succeeds.
```console
$ sudo nixos-rebuild switch --flake .#<host>
```
4. Enter the guest from the host.
```console
$ sudo machinectl shell <game>
```
5. Check the update service inside the guest.
```console
$ systemctl status steamcmd-<game>-update.service
```
6. Check the game service inside the guest.
```console
$ systemctl status <game>.service
```
7. Inspect the logs when either service fails.
```console
$ journalctl -u steamcmd-<game>-update.service -u <game>.service
```

55
docs/TODO.md
View File

@@ -45,7 +45,7 @@
- subagents
- test-driven-development
## pikachu proxmox -> nixos
## pikachu + pichu proxmox -> nixos
- lidarr (requires raichu)
- immich
@@ -57,16 +57,60 @@
- adguard
- homepage
## raichu proxmox -> nixos
- dwn torrent (vpn)
- dwn usenet (vpn)
- dwn-torrent-novpn
- prowlarr
- flaresolverr
- radarr
- sonarr
- radarr-anime
- sonarr-anime
- configarr
- lidarr
- audiobookshelf
- portainer
- seerr
- plex
- pterodactyl
- palworld old
- project zomboid
- minecraft
- cobblemon
# learning
- https://www.youtube.com/@EeroAlvar/videos
- YouTube
- EeroAlvar
- https://www.youtube.com/watch?v=DzhLFiblPUk
- https://www.youtube.com/watch?v=hQGAwD9vkLo
- https://www.youtube.com/watch?v=hhtExS5UQBI
- https://www.youtube.com/watch?v=Y1xO9OsCBC4
- https://www.youtube.com/watch?v=DWWrLlM3gwQ
- https://www.youtube.com/watch?v=yHL-gmkzC-4
- https://www.youtube.com/watch?v=KRVYUkM16hE
- https://www.youtube.com/watch?v=RxdvzenLcl4
- https://www.youtube.com/watch?v=mdbpIpPSPwQ
- https://www.youtube.com/watch?v=GHsq0klC_4g
- https://www.youtube.com/watch?v=ciC6ffUqI8k
- https://www.youtube.com/watch?v=gYxZt9Qe0fk
- https://www.youtube.com/watch?v=0tqty8ltKDA
- https://www.youtube.com/watch?v=kzcI5F4tGiU
- https://www.youtube.com/watch?v=iKwPaB5TUdI
- https://www.youtube.com/watch?v=A-CtdQFRX64
# tech debt
- better remote deployment
## nix refactor
```text
nixos
├── guests
│ ├── actualbudget.nix
│ ├── copyparty.nix
│ └── reverse-proxy.nix
│ ├── reverse-proxy.nix
│ └── valheim.nix
├── hosts
│ ├── neogaia
│ │ ├── default.nix
@@ -120,9 +164,12 @@
│ │ ├── vlans.nix
│ │ └── vpn-client.nix
│ ├── services
│ │ ├── games
│ │ │ └── valheim.nix
│ │ ├── actualbudget.nix
│ │ ├── copyparty.nix
│ │ └── reverse-proxy.nix
│ │ ├── reverse-proxy.nix
│ │ └── steamcmd.nix
│ ├── shell
│ │ ├── direnv
│ │ │ ├── default.nix