75 lines
4.1 KiB
Markdown
75 lines
4.1 KiB
Markdown
# AGENTS.md
|
|
|
|
## What this repo is
|
|
|
|
NixOS flake that defines kiosk systems running the RadiantWave app. Not application code — this is the OS image and deployment configuration. The actual app lives in the `radiantwave` flake input (from gitea.radiantwavetech.com).
|
|
|
|
Hosted on Gitea: `https://gitea.radiantwavetech.com/RadiantWaveTech/KioskConfig`
|
|
|
|
## Key commands
|
|
|
|
```bash
|
|
# Build a system closure (any config name from flake.nix)
|
|
nix build .#nixosConfigurations.<name>.config.system.build.toplevel
|
|
|
|
# Build a bootable ISO
|
|
nix build .#nixosConfigurations.<name>.config.system.build.isoImage
|
|
|
|
# Deploy to a remote kiosk over SSH
|
|
nixos-rebuild switch --flake .#<name> --target-host root@<host>
|
|
|
|
# Push build result to Attic cache
|
|
attic push kiosk ./result
|
|
|
|
# Evaluate available config names
|
|
nix eval .#nixosConfigurations --apply builtins.attrNames
|
|
```
|
|
|
|
## Config variants
|
|
|
|
| Name | Target hardware | Disk device | Notes |
|
|
|---|---|---|---|
|
|
| `radiantwavekiosk` | Intel NUC 14 (NVMe) | `/dev/nvme0n1` | Production, uses `radiantwave-legacy` |
|
|
| `radiantwavekiosk-dev` | Intel NUC 14 (NVMe) | `/dev/nvme0n1` | Dev, uses `radiantwave` `?ref=dev` |
|
|
| `radiantwavekiosk-commercial` | Commercial HW (SATA) | `/dev/sda` | Production, uses `radiantwave-legacy` |
|
|
| `radiantwavekiosk-commercial-dev` | Commercial HW (SATA) | `/dev/sda` | Dev, uses `radiantwave` `?ref=dev` |
|
|
| `radiantwavekiosk-android` | Intel NUC 14 | `/dev/nvme0n1` | + rotated display (portrait), uses `radiantwave-legacy` |
|
|
| `radiantwavekiosk-rpi` | Raspberry Pi 5 | — | Uses `nixos-raspberrypi`, uses `radiantwave-legacy` |
|
|
| `radiantwavekiosk-rpi-dev` | Raspberry Pi 5 | — | Dev, uses `radiantwave` `?ref=dev` |
|
|
|
|
ISOs: `usb-iso`, `commercial-usb-iso`, `android-iso`, `dev-iso` — each bakes in the corresponding system closure for zero-touch install.
|
|
|
|
## Branching model
|
|
|
|
Single branch (`main`). Production vs. dev split is at the **flake input** level (`radiantwave-legacy` vs `radiantwave` `?ref=dev`), not at the branch level.
|
|
|
|
## CI (Gitea)
|
|
|
|
`.gitea/workflows/build-dev.yml` — triggered by `workflow_dispatch`. Updates `radiantwave` input (dev branch), builds dev closure + ISO, commits updated `flake.lock`. Runs on `build-server`.
|
|
|
|
## Important gotchas
|
|
|
|
- **Disk device differs by variant**: `disk-config.nix` uses `/dev/nvme0n1`, `commercial-disk-config.nix` uses `/dev/sda`. Don't mix them up.
|
|
- **ISO configs reference specific system closures**: `iso-config.nix` hardcodes `radiantwavekiosk`, `dev-iso.nix` hardcodes `radiantwavekiosk-dev`, `commercial-iso-config.nix` hardcodes `radiantwavekiosk-commercial`, `android-iso.nix` hardcodes `radiantwavekiosk-android`. Changing a config name in `flake.nix` requires updating the corresponding ISO config.
|
|
- **Attic cache token**: ISO configs embed a JWT token for Attic in `/etc/nix/netrc`. If builds fail with auth errors, the token may have expired (expiry in the JWT payload).
|
|
- **`rotated_display.nix` uses `mkForce`** on `loginShellInit` — it replaces the entire kiosk startup script from `configuration.nix`, don't edit both.
|
|
- **SOPS**: `.sops.yaml` configures age-based encryption for `secrets.yaml`. You'll need the private key matching `age1t2wpzv...` to decrypt.
|
|
- **Flake inputs**: `radiantwave` tracks main, `radiantwave-dev` tracks `?ref=dev`. Updating them independently is intentional.
|
|
|
|
## File map
|
|
|
|
- `flake.nix` — all system definitions, entry point
|
|
- `configuration.nix` — shared NixOS config (packages, services, kiosk user, auto-upgrade, health check, VM variant)
|
|
- `disk-config.nix` — NVMe disk layout (NUC)
|
|
- `commercial-disk-config.nix` — SATA disk layout (commercial HW)
|
|
- `iso-config.nix` — production ISO + zero-touch installer
|
|
- `dev-iso.nix` — dev ISO + zero-touch installer
|
|
- `commercial-iso-config.nix` — commercial ISO + zero-touch installer
|
|
- `android-iso.nix` — android ISO + zero-touch installer
|
|
- `rotated_display.nix` — portrait display override for Android variant
|
|
- `facter.json` — hardware facter report (NUC 14)
|
|
- `14rvk.json`, `pn54.json` — additional hardware facter reports
|
|
- `assets/` — logo and splash image
|
|
- `plymouth-theme/` — boot splash theme
|
|
- `commands.md` — quick-reference for build/deploy commands
|