diff --git a/AGENTS.md b/AGENTS.md index 8defb09..0ba9650 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,7 @@ # AGENTS.md -This file teaches AI agents how to navigate and work with this NixOS configuration repository (`sid.ovh`). +This file teaches AI agents how to navigate and work with this NixOS +configuration repository (`sid.ovh`). --- @@ -8,13 +9,14 @@ This file teaches AI agents how to navigate and work with this NixOS configurati This is a NixOS flake managing three hosts: -| Host | IP (Tailscale) | Role | -|-------|----------------|------------------------------------------------------| -| `sid` | `100.64.0.6` | VPS - reverse proxy, mail, matrix, headscale | -| `rx4` | `100.64.0.10` | Home server - open-webui, forgejo, vaultwarden, etc. | -| `vde` | `100.64.0.1` | Desktop / workstation (not in use at the moment) | +| Host | IP (Tailscale) | Role | +|-------|----------------|---------------------------------------------------| +| `sid` | `100.64.0.6` | VPS — reverse proxy, mail, matrix, headscale | +| `rx4` | `100.64.0.10` | Home server — open-webui, forgejo, vaultwarden, … | +| `vde` | `100.64.0.1` | Desktop / workstation (not in use at the moment) | -Deployment is done via `deploy-rs` through a Forgejo CI pipeline (`.forgejo/workflows/deploy-configs.yml`). +Deployment is done via `deploy-rs` through a Forgejo CI pipeline +(`.forgejo/workflows/deploy-configs.yml`). --- @@ -22,20 +24,25 @@ Deployment is done via `deploy-rs` through a Forgejo CI pipeline (`.forgejo/work ### What it is -`synix` is a **NixOS library flake**, hosted at: +`synix` is the owner's **personal NixOS library flake**, hosted at: ``` https://git.sid.ovh/sid/synix.git ``` It provides: -- **NixOS modules** (`inputs.synix.nixosModules.*`): opinionated, reusable service configurations used heavily across all three hosts. -- **Home Manager modules** (`inputs.synix.homeModules.*`): desktop / user-space configurations (Hyprland, nixvim, waybar, etc.). -- **Packages** (`inputs.synix.packages..*`, also accessible via the `synix-packages` overlay as `pkgs.synix.*`): custom packages not in nixpkgs. -- **Overlays** (`inputs.synix.overlays.*`): nixpkgs modifications. -- **A utility library** (`inputs.synix.lib` / `lib.utils`): helper functions such as `mkVirtualHost` and `mkReverseProxyOption`. -- **Templates**: starter flake templates for servers, desktops, VMs, etc. -- **Apps**: convenience scripts (`deploy`, `rebuild`, `install`, etc.). +- **NixOS modules** (`inputs.synix.nixosModules.*`) — opinionated, + reusable service configurations used heavily across all three hosts. +- **Home Manager modules** (`inputs.synix.homeModules.*`) — desktop / + user-space configurations (Hyprland, nixvim, waybar, …). +- **Packages** (`inputs.synix.packages..*`, also accessible via + the `synix-packages` overlay as `pkgs.synix.*`) — custom packages not + in nixpkgs. +- **Overlays** (`inputs.synix.overlays.*`) — nixpkgs modifications. +- **A utility library** (`inputs.synix.lib` / `lib.utils`) — helper + functions such as `mkVirtualHost` and `mkReverseProxyOption`. +- **Templates** — starter flake templates for servers, desktops, VMs, etc. +- **Apps** — convenience scripts (`deploy`, `rebuild`, `install`, …). ### How it is consumed in `sid.ovh` @@ -52,13 +59,16 @@ inputs = { }; ``` -The active branch is **`release-25.11`**, aligned with `nixpkgs` at `nixos-25.11`. A `develop` branch exists for unstable work. A local checkout can be used for testing by switching to the `git+file://` URL. +The active branch is **`release-25.11`**, aligned with `nixpkgs` +`nixos-25.11`. A `develop` branch exists for unstable work. A local +checkout can be used for testing by switching to the `git+file://` URL. --- ## `synix` Module Reference -All NixOS modules are under `modules/nixos/` in the synix repo and exposed as `inputs.synix.nixosModules.`. +All NixOS modules are under `modules/nixos/` in the synix repo and +exposed as `inputs.synix.nixosModules.`. ### Infrastructure / base modules @@ -97,13 +107,18 @@ All NixOS modules are under `modules/nixos/` in the synix repo and exposed as `i ### Other available modules (not currently active in `sid.ovh`) -`audio`, `bluetooth`, `amd`, `nvidia`, `jellyfin`, `i2pd`, `ftp-webserver`, `webPage`, `windows-oci`, `librechat-oci`, `nostr-relay`, `ollama`, `cifsMount`, `hyprland` (NixOS-level), `normalUsers`. +`audio`, `bluetooth`, `amd`, `nvidia`, `jellyfin`, `i2pd`, +`ftp-webserver`, `webPage`, `windows-oci`, `librechat-oci`, +`nostr-relay`, `ollama`, `cifsMount`, `hyprland` (NixOS-level), +`normalUsers`. --- ## `synix` Packages (`pkgs.synix.*`) -Custom packages provided by synix and available via the `synix-packages` overlay (applied in `modules/nixos/common/overlays.nix`): +Custom packages provided by synix and available via the +`synix-packages` overlay (applied in +`modules/nixos/common/overlays.nix`): | Package name | What it is | |-------------------------------|------------| @@ -120,13 +135,15 @@ Custom packages provided by synix and available via the `synix-packages` overlay | `pkgs.synix.bulk-rename` | Batch file renaming script | | `pkgs.synix.pyman` | Python man-page helper | -The full list lives in `pkgs/default.nix` in the synix repo. All packages are also accessible as `inputs.synix.packages..`. +The full list lives in `pkgs/default.nix` in the synix repo. All +packages are also accessible as `inputs.synix.packages..`. --- ## `synix` Utility Library (`lib.utils`) -Exposed as `inputs.synix.lib` and merged into the flake's `lib` in `flake.nix`: +Exposed as `inputs.synix.lib` and merged into the flake's `lib` in +`flake.nix`: ```nix lib = nixpkgs.lib.extend (final: prev: inputs.synix.lib or { }); @@ -153,7 +170,8 @@ virtualHosts."${constants.services.forgejo.fqdn}" = mkVirtualHost { ## How `synix` Modules Are Imported -In each host's `default.nix`, synix modules are imported directly from the `inputs` special arg: +In each host's `default.nix`, synix modules are imported directly from +the `inputs` special arg: ```nix # hosts/rx4/default.nix @@ -161,7 +179,7 @@ imports = [ inputs.synix.nixosModules.common # base system config inputs.synix.nixosModules.device.server # server profile inputs.synix.nixosModules.openssh # hardened SSH - # service-specific modules in hosts/rx4/services/ + # …service-specific modules in hosts/rx4/services/ ]; ``` @@ -189,15 +207,18 @@ imports = [ | `old-stable-packages` | `nixpkgs-25.05` | `pkgs.old-stable.*` | | `unstable-packages` | `nixos-unstable` | `pkgs.unstable.*` | -`synix` also supplies its own `modifications` overlay (`inputs.synix.overlays.modifications`), merged into the local `modifications` overlay in `overlays/default.nix`. +`synix` also supplies its own `modifications` overlay +(`inputs.synix.overlays.modifications`), merged into the local +`modifications` overlay in `overlays/default.nix`. --- ## Centralized Logging Architecture -All hosts ship their systemd journal to a **central receiver running on `sid`** over HTTP using `systemd-journal-remote` / `systemd-journal-upload`. +All hosts ship their systemd journal to a **central receiver running on +`sid`** over HTTP using `systemd-journal-remote` / `systemd-journal-upload`. -### Receiver (local host `pc` which is not part of this flake) +### Receiver (`sid`) ```nix services.journald.remote = { @@ -227,15 +248,19 @@ services.journald.upload = { }; ``` -> **Note:** The upload URL uses `100.64.0.5` - the Tailscale transport IP for host `pc` (which is not part of this flake). Verify with `ip addr show tailscale0` and `hostname` if you are on host `pc` with IP `100.64.0.5`. +> **Note:** The upload URL uses `100.64.0.5` — the Tailscale transport +> IP for `sid` (distinct from the advertised IP `100.64.0.6` in +> `constants.nix`; verify with `ip addr show tailscale0` on `sid` if +> queries fail). -This module is applied to **every host** via `outputs.nixosModules.common` -> `modules/nixos/common/default.nix`. +This module is applied to **every host** via +`outputs.nixosModules.common` → `modules/nixos/common/default.nix`. --- ## Querying Remote Journals -All queries run **on `pc`**, reading from `/var/log/journal/remote/`. +All queries run **on `sid`**, reading from `/var/log/journal/remote/`. ### General pattern @@ -268,10 +293,13 @@ journalctl \ ``` This works because: -1. `rx4` uploads its journal to `pc:19532`. -2. The receiver stores it under `/var/log/journal/remote/` with `SplitMode=host`, preserving the `_HOSTNAME` field. +1. `rx4` uploads its journal to `sid:19532`. +2. The receiver stores it under `/var/log/journal/remote/` with + `SplitMode=host`, preserving the `_HOSTNAME` field. 3. `_HOSTNAME=rx4` narrows to that host's entries. -4. `SYSTEMD_UNIT=podman-open-webui.service` targets the OCI container unit for Open WebUI (defined in `hosts/rx4/services/open-webui-oci.nix`). +4. `SYSTEMD_UNIT=podman-open-webui.service` targets the OCI container + unit for Open WebUI (defined in + `hosts/rx4/services/open-webui-oci.nix`). ### Other useful queries @@ -280,24 +308,30 @@ This works because: journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 --no-pager -S "1 hour ago" # Forgejo on rx4 -journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=forgejo.service --no-pager -n 50 +journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \ + SYSTEMD_UNIT=forgejo.service --no-pager -n 50 # Vaultwarden on rx4 -journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=vaultwarden.service --no-pager -n 50 +journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \ + SYSTEMD_UNIT=vaultwarden.service --no-pager -n 50 # Nginx on rx4 -journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=nginx.service --no-pager -n 50 +journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \ + SYSTEMD_UNIT=nginx.service --no-pager -n 50 # Matrix-synapse on sid -journalctl -D /var/log/journal/remote/ _HOSTNAME=sid SYSTEMD_UNIT=matrix-synapse.service --no-pager -n 50 +journalctl -D /var/log/journal/remote/ _HOSTNAME=sid \ + SYSTEMD_UNIT=matrix-synapse.service --no-pager -n 50 # Follow logs live -journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 SYSTEMD_UNIT=podman-open-webui.service -f +journalctl -D /var/log/journal/remote/ _HOSTNAME=rx4 \ + SYSTEMD_UNIT=podman-open-webui.service -f ``` ### OCI container unit names -Containers managed by `virtualisation.oci-containers` get units named `podman-.service`: +Containers managed by `virtualisation.oci-containers` get units named +`podman-.service`: | Container attr | Unit name | Host | |------------------------|----------------------------------------|------| @@ -311,7 +345,8 @@ Containers managed by `virtualisation.oci-containers` get units named `podman-