Files
nix-config/hosts/README.md
T

179 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Hosts
This directory contains all host-specific configurations for my NixOS and macOS systems.
## Current Host Inventory
### Physical Machines
#### `idols` - Main Workstations
Named after characters from "Oshi no Ko":
| Host | Platform | Hardware | Purpose | Status |
| ------------ | --------------- | --------------------- | --------------------- | ----------- |
| `ai` | NixOS | i5-13600KF + RTX 4090 | Gaming & Daily Use | ✅ Active |
| `aquamarine` | NixOS (libvirt) | Virtual | Monitoring & Services | ⚪ Not Used |
| `kana` | NixOS (libvirt) | Virtual | Run AI Agents | ✅ Active |
| `ruby` | NixOS (libvirt) | Virtual | Run AI Agents | ✅ Active |
| `akane` | NixOS (aarch64) | Virtual (UTM) | aarch64 test VM | ✅ Active |
`aquamarine` is retired; its services now run directly on `youko`
(`hosts/12kingdoms-youko/homelab-services/`).
#### `darwin` - macOS Systems
Named after characters from "Frieren: Beyond Journey's End":
| Host | Platform | Hardware | Purpose | Status |
| --------- | -------- | -------------------------- | ------------ | --------- |
| `fern` | macOS | MacBook Pro M2 13" 16GB | Personal Use | ✅ Active |
| `frieren` | macOS | MacBook Pro M4Pro 14" 48GB | Work Use | ✅ Active |
#### `12kingdoms` - Homelab Servers & Apple Silicon Linux
Named after "Twelve Kingdoms":
| Host | Platform | Hardware | Purpose | Status |
| --------- | -------- | ------------------------------------ | ---------------------- | --------- |
| `shoukei` | NixOS | MacBook Pro M2 | NixOS on Apple Silicon | ✅ Active |
| `shoryu` | NixOS | MoreFine S500+ (AMD Ryzen 7 5825U) | VM Host | ✅ Active |
| `shushou` | NixOS | MinisForum UM560 (AMD Ryzen 5 5625U) | VM Host | ✅ Active |
| `youko` | NixOS | Beelink GTR5 (AMD Ryzen 9 5900HX) | Homelab Core | ✅ Active |
On 2026-09-29 the NVMe SSDs of `youko` and `shushou` were physically swapped, and the 2×4TB USB HDDs
moved with the `youko` role to the other chassis. The reason was Jellyfin: HDR transcoding on the
5625U's Barceló iGPU could not keep up (~0.4–0.8×), while the 5900HX's Cezanne iGPU can (~1.68× for
1080p HDR). So the homelab-core role (all services + one k3s VM + the HDDs + the UPS) now runs on
the Beelink GTR5 and the k3s VM-host role on the UM560; the other services moving along is a side
effect of swapping the role's disk, not a separate migration. Hostnames, IPs, and state followed the
disks.
### Virtual Machines & Clusters
#### `k8s` - Kubernetes Infrastructure
- **VM Cluster**: 3 physical mini PCs (shoryu, shushou, youko) running all VMs
- **K3s Testing**: `k3s-test-1-master-{1,2,3}` (control plane; one per host) +
`k3s-test-1-worker-{1,2,3}` (workloads; `worker-1` on `shoryu`, `worker-2` on `youko`, `worker-3`
on `shushou`), running as microVMs
### External Systems
- **SBCs**: aarch64/riscv64 single-board computers managed in
[ryan4yin/nixos-config-sbc](https://github.com/ryan4yin/nixos-config-sbc)
All my riscv64 hosts:
![](/_img/nixos-riscv-cluster.webp)
## Naming Conventions
- **idols**: Characters from "Oshi no Ko" anime/manga
- **12kingdoms**: Characters from "Twelve Kingdoms" anime/novel series
- **darwin**: Characters from "Frieren: Beyond Journey's End" anime/manga
- **k8s**: Kubernetes-related systems follow standard naming patterns
## How to Add a New Host
The easiest way to add a new host is to copy and adapt an existing similar configuration. All host
configurations follow similar patterns but are customized for specific hardware and use cases.
### General Process
1. **Identify a similar existing host** from the directory structure above
2. **Copy the entire directory** and rename it for your new host
3. **Adapt the configuration files** for your specific hardware and requirements
4. **Update references** in the flake outputs and networking configuration
### Essential Steps
1. Under `hosts/`
1. Create a new folder under `hosts/` with the name of the new host.
2. Create & add the new host's `hardware-configuration.nix` to the new folder, and add the new
host's `configuration.nix` to `hosts/<name>/default.nix`.
3. If the new host need to use home-manager, add its custom config into
`home/hosts/linux/<name>.nix` or `home/hosts/darwin/<name>.nix`.
1. Under `outputs/`
1. Add a new nix file named `outputs/<system-architecture>/src/<name>.nix`.
2. Copy the content from one of the existing similar host, and modify it to fit the new host.
1. Usually, you only need to modify the `name` and `tags` fields.
3. [Optional] Add a new unit test file under `outputs/<system-architecture>/tests/<name>.nix` to
test the new host's nix file.
4. [Optional] Add a new integration test file under
`outputs/<system-architecture>/integration-tests/<name>.nix` to test whether the new host's
nix config can be built and deployed correctly.
1. Under `vars/networking.nix`
1. Add the new host's static IP address.
1. Skip this step if the new host is not in the local network or is a mobile device.
### File Templates
Use existing hosts as templates. The key files typically include:
- `default.nix` - Main host configuration
- `hardware-configuration.nix` - Auto-generated hardware settings
- Platform-specific files (e.g., `nvidia.nix`, `apple-silicon.nix`, etc.)
### Examples to Reference
- **Desktop systems**: See `idols-ai/` for gaming/workstation setup
- **Server systems**: See `12kingdoms-shoryu/` for VM hosts
- **macOS systems**: See `darwin-fern/` for macOS configurations
- **Apple Silicon**: See `12kingdoms-shoukei/` for ARM Linux setup
## Deploying VM Hosts
The three VM hosts (`shoryu`, `shushou`, `youko`) attach their VMs (microVM taps and libvirt
domains) to the Linux bridge `br0`, with the physical NIC as a bridge port. The `k3s-test-1` cluster
runs as microVMs on top, using Cilium as its pod network (flannel disabled).
- `switch` is fine for changes that don't touch the network stack (e.g. journald or other service
settings). Deploy serially (`-p 1`) and re-check VM reachability afterwards.
- Use `boot` + a serial reboot for anything that can drop the network mid-flight — `systemd.network`
/ `br0` changes, nixpkgs updates, or any broad rebuild.
- If a host loses VM networking, check `br0` and the VM taps, or reboot the host.
## Common Build Commands
Use the Just recipes for host configuration checks and builds:
```sh
just eval-host <host>
just build-host <host>
```
`eval-host` only evaluates the configuration. `build-host` builds the system closure without
activating it. Host activation remains an explicit Colmena operation such as `just shoryu`,
`just shushou`, or `just youko`.
## Distributed Building
I usually run the build command on `Ai` and nix will distribute the build to other NixOS machines,
which is convenient and fast.
When building some packages for riscv64 or aarch64, I often have no cache available because of
various changes under the hood, so I need to build much more packages than usual, which is one of
the reasons why the cluster was originally built, and another reason is distributed building is
cool!
![](/_img/nix-distributed-building.webp)
![](/_img/nix-distributed-building-log.webp)
## References
[Oshi no Ko 【推しの子】 - Wikipedia](https://en.wikipedia.org/wiki/Oshi_no_Ko):
![](/_img/idols-famaily.webp) ![](/_img/idols-ai.webp)
[The Rolling Girls【ローリング☆ガールズ】 - Wikipedia](https://en.wikipedia.org/wiki/The_Rolling_Girls):
![](/_img/rolling_girls.webp)
[List of Twelve Kingdoms characters](https://en.wikipedia.org/wiki/List_of_Twelve_Kingdoms_characters)
![](/_img/12kingdoms-1.webp) ![](/_img/12kingdoms-Youko-Rakushun.webp)
[List of Frieren characters](https://en.wikipedia.org/wiki/List_of_Frieren_characters)