linking
This commit is contained in:
1 parent
33539144d8
commit
fa84c7cdab
3 files changed
+2
-596
No files matched your search
@@ -1,579 +0,0 @@
|
||||
# Agent Context: nixos-setup
|
||||
|
||||
A complete reference for an AI agent to understand, navigate, and modify this
|
||||
NixOS homelab configuration repository.
|
||||
|
||||
> **⚠️ MANDATORY:** Before doing anything in this repository, read
|
||||
> [`GUIDELINES.md`](../GUIDELINES.md) in full and follow it. It contains
|
||||
> non-negotiable hard rules (never run builds, never edit `flake.lock`, etc.)
|
||||
> and requires you to **present a plan and get user approval before making any
|
||||
> changes**.
|
||||
|
||||
---
|
||||
|
||||
## Repository Purpose
|
||||
|
||||
A **NixOS flake** managing multiple machines (laptops, desktops, servers) and one OpenWrt
|
||||
router for a personal homelab. Everything is declarative Nix. No imperative scripts except
|
||||
the `skyg` CLI wrapper and the OpenWrt deploy script.
|
||||
|
||||
The configured user, default system architecture, and NixOS state version are all defined
|
||||
in `flake.nix` (the `lib =` binding at the top of `outputs`). Check that file for
|
||||
source-of-truth values rather than relying on any hardcoded constants here.
|
||||
|
||||
---
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```
|
||||
nixos-setup/
|
||||
├── flake.nix # All outputs: nixosConfigurations, homeConfigurations, packages, devShells
|
||||
├── flake.lock # Locked input revisions — do not edit by hand
|
||||
├── secrets.nix # agenix: maps .age files → authorized SSH public keys
|
||||
├── bin/
|
||||
│ ├── skyg # Bash shim: exec nu --commands "use lib/cmds.nu *; skyg $*"
|
||||
│ └── lib/
|
||||
│ ├── cmds.nu # All skyg subcommands (NuShell — source of truth)
|
||||
│ ├── profile.nu # Profile helpers and tab-completion data
|
||||
│ └── types.nu # Type definitions
|
||||
├── hosts/
|
||||
│ ├── <hostname>.nix # One file per managed machine
|
||||
│ ├── <hostname>.hardware-configuration.nix
|
||||
│ ├── iso.nix # Bootable install image
|
||||
│ └── scripts/ # Host-specific helper scripts
|
||||
├── modules/
|
||||
│ ├── lib.nix # makeNixOs / makeIso / makeHomeManagerUsers / makeDarwinModule / eachSystem
|
||||
│ ├── main.nix # Base module every host gets: core/ + nixos/ + network-drives.nix
|
||||
│ ├── skyg-utils.nix # makeHyperlinkScriptToConfigs (symlinks configs/ → ~/.config/)
|
||||
│ ├── macos.nix # macOS/nix-darwin module
|
||||
│ ├── network-drives.nix # skyg.networkDrives — NFS auto-mounts
|
||||
│ ├── core/
|
||||
│ │ ├── default.nix # Imports: user.nix, macos.nix, nix-substituters.nix
|
||||
│ │ ├── user.nix # skyg.user.* and skyg.home-manager.* options; wires HM
|
||||
│ │ ├── nix-substituters.nix # Binary caches + remote builder config
|
||||
│ │ └── macos.nix # Pipx workaround overlay; distributed build config
|
||||
│ ├── home/
|
||||
│ │ ├── default.nix # makeCommonUser / makeRootUser factories
|
||||
│ │ ├── programs.nix # bat, neovim, direnv, eza, starship, nushell, carapace, zsh, zellij, tmux
|
||||
│ │ ├── services.nix # gpg-agent with SSH support
|
||||
│ │ ├── fonts.nix # Font packages
|
||||
│ │ └── git.nix # makeCommonGitConfigs
|
||||
│ ├── nixos/
|
||||
│ │ ├── default.nix # Imports: common/ + server/ + desktop/
|
||||
│ │ ├── common/
|
||||
│ │ │ ├── core.nix # nix-ld, nh, appimage-run, GC cron, timezone, locale
|
||||
│ │ │ ├── networking.nix # skyg.core.hostName; NetworkManager; disables nm-wait-online
|
||||
│ │ │ ├── user.nix # System user creation; zsh as default shell
|
||||
│ │ │ ├── ssh-server.nix # skyg.nixos.common.ssh-server.enable; key-only SSH
|
||||
│ │ │ ├── qemu.nix # skyg.core.qemu.enable; QEMU + SPICE stack
|
||||
│ │ │ ├── fonts.nix
|
||||
│ │ │ ├── hardware/ # amdgpu, nvidia, coral-tpu-udev, fan2go, fancontrol, laptop-power, pipewire, sound
|
||||
│ │ │ ├── containers/ # Docker/Podman options; local registry config; metrics port
|
||||
│ │ │ └── pritunl/ # Pritunl VPN client
|
||||
│ │ ├── server/
|
||||
│ │ │ ├── admin.nix # skyg.server.admin.enable → www-data group
|
||||
│ │ │ ├── exporters.nix # skyg.server.exporters.enable → Prometheus node exporter
|
||||
│ │ │ ├── timers.nix # skyg.server.timers attrset → systemd timer+service pairs
|
||||
│ │ │ ├── k3s/ # skyg.nixos.server.k3s.{enable,role,envPath}
|
||||
│ │ │ ├── k8s/ # Raw Kubernetes: master.nix + node.nix
|
||||
│ │ │ ├── dns/ # certbot/, routing/ (dnsmasq), local-ca/
|
||||
│ │ │ ├── arrs/ # Prowlarr + DB for *arr stack
|
||||
│ │ │ └── services/ # ai-services, audiobookshelf, comfyui, dockge, jellyfin, scrypted
|
||||
│ │ └── desktop/
|
||||
│ │ ├── default.nix # skyg.nixos.desktop.enable; PipeWire, dbus, portals, avahi
|
||||
│ │ ├── wayland.nix # NIXOS_OZONE_WL=1, xwayland
|
||||
│ │ ├── tiler/ # DankMaterialShell + niri + hyprland + swww
|
||||
│ │ ├── stylix/ # skyg.nixos.desktop.stylix.enable
|
||||
│ │ ├── gnome.nix / kde.nix / cosmic.nix
|
||||
│ │ ├── crypto.nix # skyg.nixos.desktop.crypto.enable
|
||||
│ │ ├── packages.nix
|
||||
│ │ └── printers.nix
|
||||
│ └── openwrt/
|
||||
│ ├── default.nix # Builds openwrt-gen Rust binary; exports deployScript
|
||||
│ └── generator/ # Rust: stdin JSON → dnsmasq.conf or ethers
|
||||
├── openwrt-routers/
|
||||
│ └── <router>.nix # Per-router config (IP, SSH user, configSecret path)
|
||||
├── secrets/
|
||||
│ └── *.age # Encrypted secrets (see secrets.nix for authorization map)
|
||||
├── configs/
|
||||
│ ├── niri/ # niri compositor config (symlinked to ~/.config/niri)
|
||||
│ ├── hypr/ # Hyprland config
|
||||
│ ├── hyprpanel/ # HyprPanel config
|
||||
│ └── extra.nu # Extra NuShell config
|
||||
└── docs/ # Documentation (hosts, modules, secrets, DNS, OpenWrt)
|
||||
```
|
||||
|
||||
**For the full host list and per-machine details**, see `docs/hosts/README.md`.
|
||||
|
||||
---
|
||||
|
||||
## skyg CLI Reference
|
||||
|
||||
`skyg` is implemented in `bin/lib/cmds.nu`. All commands `cd` to `$REPO_ROOT` first.
|
||||
The `bin/skyg` file is a thin bash shim — the NuShell file is the source of truth.
|
||||
|
||||
### System Deployment
|
||||
|
||||
```bash
|
||||
# Local system (whichever host the repo is checked out on)
|
||||
skyg os switch
|
||||
skyg os test
|
||||
skyg os switch --build-host <builder> # offload compilation to a remote builder
|
||||
|
||||
# Remote system
|
||||
skyg remote switch <hostname> # deploys to root@<hostname>.<domain>
|
||||
skyg remote test <hostname> # test without activating
|
||||
skyg remote switch <hostname> --build-host <builder>
|
||||
|
||||
# Rollback
|
||||
skyg rollback # sudo nixos-rebuild switch --rollback
|
||||
|
||||
# Validate flake without building
|
||||
skyg check # nix flake check --no-build
|
||||
```
|
||||
|
||||
`skyg remote` maps `<hostname>` → NixOS profile `hl-<hostname>` → SSH target
|
||||
`root@<hostname>.<domain>`. See `bin/lib/profile.nu` for the full list of valid targets.
|
||||
|
||||
### Home Manager
|
||||
|
||||
```bash
|
||||
skyg hm switch # apply for the default profile
|
||||
skyg hm build # build only
|
||||
skyg hm switch <profile> # explicit profile name
|
||||
```
|
||||
|
||||
### Flake Updates
|
||||
|
||||
```bash
|
||||
skyg update # nix flake update (all inputs) + shows flake.lock diff
|
||||
skyg update <input> # update a single input, e.g. skyg update nixpkgs
|
||||
```
|
||||
|
||||
### OpenWrt
|
||||
|
||||
```bash
|
||||
skyg openwrt # decrypt router secret, pipe to deploy script
|
||||
skyg openwrt <router> # explicit router name (matches openwrt-routers/<router>.nix)
|
||||
```
|
||||
|
||||
Deploy flow: age-decrypts the router's JSON secret → generates `dnsmasq.conf` + `ethers`
|
||||
via the Rust binary → shows colored diffs → prompts for confirmation × 2 → SSHes to the
|
||||
router → validates with `dnsmasq --test` → restarts dnsmasq (auto-reverts on failure).
|
||||
|
||||
### ISO
|
||||
|
||||
```bash
|
||||
skyg build-iso # nix build .#nixosConfigurations.iso.config.system.build.isoImage
|
||||
```
|
||||
|
||||
### Secrets
|
||||
|
||||
```bash
|
||||
skyg secrets # list known secret names
|
||||
skyg decrypt <name> # decrypt → .tmp/unencrypted-<name>
|
||||
skyg encrypt <name> [source] # re-encrypt ← .tmp/unencrypted-<name>
|
||||
skyg compare-secret <name> # diff .tmp/unencrypted-<name> vs the .age file
|
||||
```
|
||||
|
||||
### Profiles
|
||||
|
||||
```bash
|
||||
skyg profiles # list all configured profiles
|
||||
skyg profiles true # list remote-only profiles (hl-* prefixed)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Flake Outputs
|
||||
|
||||
```nix
|
||||
nixosConfigurations = {
|
||||
# One entry per host — names match hosts/<name>.nix
|
||||
# See flake.nix for the full list and hardware modules used
|
||||
<hostname> = lib.makeNixOs { ... };
|
||||
iso = lib.makeIso { ... };
|
||||
}
|
||||
|
||||
homeConfigurations = {
|
||||
# Standalone home-manager (non-NixOS use)
|
||||
# Profile name defined in flake.nix
|
||||
<profile> = lib.makeHomeManagerUsers { ... };
|
||||
}
|
||||
|
||||
packages.<system> = {
|
||||
# One deploy script per router, named openwrt-<router>
|
||||
openwrt-<router> = (openwrt (import ./openwrt-routers/<router>.nix)).deployScript;
|
||||
}
|
||||
|
||||
devShells.<system>.default # nix develop shell
|
||||
formatter.<system> # nixpkgs-fmt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `lib.nix` API
|
||||
|
||||
```nix
|
||||
lib.makeNixOs {
|
||||
hostName; # required — sets networking.hostName
|
||||
system ? "x86_64-linux";
|
||||
systemStateVersion ? "26.05";
|
||||
configuration ? []; # extra modules/files appended after main.nix
|
||||
}
|
||||
# Automatically includes: determinate, stylix, home-manager, nix-flatpak,
|
||||
# agenix, dms (DankMaterialShell), nix-index-database, hermes-agent NixOS modules.
|
||||
|
||||
lib.makeIso { hostName; ... } # same as makeNixOs + installation-cd-minimal.nix
|
||||
|
||||
lib.makeHomeManagerUsers {
|
||||
modules ? [];
|
||||
userConfig ? user; # defaults to the user attrset defined in flake.nix
|
||||
system ? "x86_64-linux";
|
||||
}
|
||||
|
||||
lib.makeDarwinModule {
|
||||
hostName; user;
|
||||
system ? "x86_64-darwin";
|
||||
configuration ? [];
|
||||
}
|
||||
|
||||
lib.eachSystem (system: ...) # genAttrs over all systems from nix-systems/default
|
||||
```
|
||||
|
||||
`specialArgs` injected into every host module: `unstablePkgs`, `skygUtils`, `user`,
|
||||
`system`, `hyprlauncher`, `dms`, `noctalia`, `nix-index-database`, `hermes-agent`.
|
||||
|
||||
---
|
||||
|
||||
## `skyg.*` Option Namespace
|
||||
|
||||
All custom NixOS options. Set these in host files (`hosts/<name>.nix`).
|
||||
|
||||
```
|
||||
skyg.user
|
||||
.name string username
|
||||
.fullName string
|
||||
.email string
|
||||
.enable bool enable home-manager config for this user
|
||||
.createSystemUser bool create the Linux user account (default: true)
|
||||
.extraGitConfigs list [{path = "..."}] extra git config includes
|
||||
|
||||
skyg.home-manager
|
||||
.version string HM stateVersion (default: "26.05")
|
||||
.extraImports list extra HM modules to import
|
||||
|
||||
skyg.core
|
||||
.hostName string REQUIRED — sets networking.hostName
|
||||
.qemu.enable bool QEMU + quickemu + SPICE stack
|
||||
.substituters.urls list extra Nix binary cache URLs
|
||||
.substituters.keys list extra Nix binary cache trusted public keys
|
||||
|
||||
skyg.nixos.desktop
|
||||
.enable bool PipeWire, dbus, libinput, avahi, XDG portals, user groups
|
||||
.tiler.enable bool DankMaterialShell, gnome-keyring, polkit, wayland tools
|
||||
.tiler.niri.enable bool niri compositor; symlinks configs/niri → ~/.config/niri
|
||||
.tiler.hyprland.enable bool Hyprland compositor
|
||||
.stylix.enable bool Stylix theming
|
||||
.crypto.enable bool crypto/wallet tools
|
||||
|
||||
skyg.nixos.common
|
||||
.ssh-server.enable bool OpenSSH, key-only auth, a master pubkey pre-authorized
|
||||
.hardware
|
||||
.sound.enable bool
|
||||
.pipewire.enable bool
|
||||
.amdgpu.enable bool
|
||||
.nvidia.enable bool
|
||||
.laptop-power-mgr.* attrset TLP/power management; lid switch config
|
||||
.udevrules.coraltpu.enable bool
|
||||
.containers
|
||||
.runtime string "docker" (default) | "podman"
|
||||
.openMetricsPort bool opens the container metrics port
|
||||
|
||||
skyg.nixos.server
|
||||
.k3s
|
||||
.enable bool
|
||||
.role string "server" (default) | "agent"
|
||||
.envPath string path to env file with K3s tokens/config
|
||||
.services
|
||||
.ai.enable bool Ollama+openwakeword containers + Wyoming whisper/piper
|
||||
.audiobookshelf.* attrset {enable, host, port, openFirewall, configDir, metadataDir}
|
||||
.comfyui.* attrset {enable, mode ("rocm"|"cuda"), port, rocm.dataDir}
|
||||
.dockge.* attrset {enable, openFirewall, port, volumes.stacks/data.{nfsServer,share}}
|
||||
.jellyfin.enable bool NFS-backed storage
|
||||
.scrypted.enable bool
|
||||
|
||||
skyg.server
|
||||
.admin.enable bool creates www-data group (gid=33) with user as member
|
||||
.exporters.enable bool Prometheus node exporter
|
||||
.timers attrset {<name> = {script, OnCalendar, wantedBy}} → systemd timer+service
|
||||
.dns
|
||||
.routing.enable bool
|
||||
.routing.openFirewall bool
|
||||
.routing.addressesSecretName string agenix secret name for dnsmasq address= lines
|
||||
.certbot.enable bool
|
||||
.certbot.email string
|
||||
.certbot.publicDomains list
|
||||
|
||||
skyg.networkDrives
|
||||
.enable bool
|
||||
.tnas1.{enable, host} NAS host (default defined in network-drives.nix)
|
||||
.terra1.{enable, host} storage server host
|
||||
.bigBox2.{enable, host} storage server host
|
||||
.options list NFS mount options (default: x-systemd.automount, auto, nofail, _netdev)
|
||||
```
|
||||
|
||||
The NFS mount points provided by `skyg.networkDrives` are defined in `modules/network-drives.nix`.
|
||||
|
||||
---
|
||||
|
||||
## Hosts
|
||||
|
||||
See `docs/hosts/README.md` for the full per-host reference (hardware, role, services, ports).
|
||||
|
||||
The `flake.nix` `nixosConfigurations` block is the canonical list of managed systems.
|
||||
Each host's source file is `hosts/<hostname>.nix` paired with
|
||||
`hosts/<hostname>.hardware-configuration.nix`.
|
||||
|
||||
---
|
||||
|
||||
## Secrets Management
|
||||
|
||||
Uses [agenix](https://github.com/ryantm/agenix). All `.age` files in `secrets/` are
|
||||
committed to the repo. `secrets.nix` maps each file to the SSH public keys authorized to
|
||||
decrypt it — check that file for the current authorization matrix and secret list.
|
||||
|
||||
### Using a secret in a module
|
||||
|
||||
```nix
|
||||
age.secrets.my-secret = {
|
||||
file = ../../secrets/my-secret.age;
|
||||
};
|
||||
|
||||
# Reference the runtime-decrypted path (e.g. /run/agenix/my-secret).
|
||||
# Never hardcode a path to the .age file itself in service config.
|
||||
someOption = config.age.secrets.my-secret.path;
|
||||
```
|
||||
|
||||
### Managing secrets
|
||||
|
||||
```bash
|
||||
# Create or edit
|
||||
agenix -e secrets/my-secret.age
|
||||
|
||||
# After adding a new host key to secrets.nix, re-encrypt everything:
|
||||
agenix -r -i ~/.ssh/id_ed25519
|
||||
|
||||
# skyg wrappers
|
||||
skyg secrets # list known secret names
|
||||
skyg decrypt <name> # → .tmp/unencrypted-<name>
|
||||
skyg encrypt <name> # ← .tmp/unencrypted-<name>
|
||||
skyg compare-secret <name> # diff plaintext vs encrypted
|
||||
```
|
||||
|
||||
`.tmp/` is gitignored. Never commit unencrypted secrets.
|
||||
|
||||
### Adding a secret for a new host
|
||||
|
||||
```bash
|
||||
ssh root@<host> "cat /etc/ssh/ssh_host_ed25519_key.pub"
|
||||
# Add the key to secrets.nix, then:
|
||||
agenix -r -i ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Binary Caches
|
||||
|
||||
Configured in `modules/core/nix-substituters.nix` and applied to all hosts. Includes a
|
||||
local nix-serve instance on the lab network for fast rebuilds, plus several public caches.
|
||||
See that file for the current URLs and trusted public keys.
|
||||
|
||||
---
|
||||
|
||||
## Dev Shell
|
||||
|
||||
```bash
|
||||
nix develop # or: direnv allow (if .envrc is present)
|
||||
```
|
||||
|
||||
Provides: `nixpkgs-fmt`, `nixd`, `nh`, `agenix`, `age`, `home-manager`, `rustc`, `cargo`,
|
||||
`rust-analyzer`, `nushell`
|
||||
|
||||
- Adds `bin/` to `PATH` → `skyg` is available immediately
|
||||
- Sets `SKYG_LIB` env var for NuShell
|
||||
- Enforces `nixpkgs-fmt` as a pre-commit hook on all `.nix` files
|
||||
- Auto-launches NuShell with `cmds.nu` imported when running interactively
|
||||
|
||||
---
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
- **Formatter**: `nixpkgs-fmt` — enforced by pre-commit. Run before committing.
|
||||
- **Options**: Use `lib.mkEnableOption` for booleans, `lib.mkOption` with `type` and
|
||||
`description` for everything else.
|
||||
- **Conditional config**: `config = lib.mkIf cfg.enable { ... }` pattern throughout.
|
||||
- **Defaults**: Use `lib.mkDefault` in `main.nix` so host configs can override cleanly.
|
||||
- **Unfree**: `nixpkgs.config.allowUnfree = true` is set globally — no need to repeat per-host.
|
||||
- **Secrets**: Never hardcode sensitive values. Use agenix. Reference
|
||||
`config.age.secrets.<name>.path` at runtime.
|
||||
- **`specialArgs`**: `unstablePkgs`, `skygUtils`, `user`, `system` are always available
|
||||
in every module — no need to pass them explicitly.
|
||||
- **Nix features**: `nix-command` and `flakes` experimental features are enabled everywhere.
|
||||
- **`nh`**: Preferred over raw `nixos-rebuild`. Used by both `skyg os` and `skyg remote`.
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Minimal server host
|
||||
|
||||
```nix
|
||||
# hosts/<name>.nix
|
||||
{ ... }: {
|
||||
skyg.user.enable = true;
|
||||
skyg.nixos.common.ssh-server.enable = true;
|
||||
skyg.server.exporters.enable = true;
|
||||
skyg.networkDrives.enable = true;
|
||||
|
||||
boot.loader.systemd-boot.enable = true;
|
||||
boot.loader.efi.canTouchEfiVariables = true;
|
||||
services.fwupd.enable = true;
|
||||
}
|
||||
```
|
||||
|
||||
### Declarative systemd timer
|
||||
|
||||
```nix
|
||||
skyg.server.timers.my-backup = {
|
||||
OnCalendar = "daily";
|
||||
wantedBy = [ "some-mount.mount" ];
|
||||
script = ''
|
||||
set -eu
|
||||
${pkgs.rsync}/bin/rsync -av /src /dest
|
||||
'';
|
||||
};
|
||||
```
|
||||
|
||||
### Enable K3s
|
||||
|
||||
```nix
|
||||
skyg.nixos.server.k3s = {
|
||||
enable = true;
|
||||
role = "agent";
|
||||
envPath = "/opt/k3s/k3s.env"; # file contains K3S_URL and K3S_TOKEN
|
||||
};
|
||||
```
|
||||
|
||||
### Use an agenix secret in a service
|
||||
|
||||
```nix
|
||||
age.secrets.my-api-key.file = ../../secrets/my-api-key.age;
|
||||
|
||||
services.myapp.apiKeyFile = config.age.secrets.my-api-key.path;
|
||||
```
|
||||
|
||||
### NFS-backed Dockge
|
||||
|
||||
```nix
|
||||
skyg.nixos.server.services.dockge = {
|
||||
enable = true;
|
||||
openFirewall = true;
|
||||
volumes.stacks = { nfsServer = "<nfs-host>"; share = "/path/to/stacks"; };
|
||||
volumes.data = { nfsServer = "<nfs-host>"; share = "/path/to/data"; };
|
||||
};
|
||||
```
|
||||
|
||||
### Desktop with tiling WM
|
||||
|
||||
```nix
|
||||
skyg.nixos.desktop = {
|
||||
enable = true;
|
||||
tiler.enable = true;
|
||||
tiler.niri.enable = true; # or hyprland.enable = true
|
||||
stylix.enable = true;
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Host — Checklist
|
||||
|
||||
1. **Create host files**:
|
||||
```
|
||||
hosts/<name>.nix
|
||||
hosts/<name>.hardware-configuration.nix # from nixos-generate-config
|
||||
```
|
||||
|
||||
2. **Register in `flake.nix`** under `nixosConfigurations`:
|
||||
```nix
|
||||
<name> = lib.makeNixOs {
|
||||
hostName = "<name>";
|
||||
configuration = [
|
||||
./hosts/<name>.nix
|
||||
./hosts/<name>.hardware-configuration.nix
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
3. **Add SSH host key to `secrets.nix`** if the host needs any secrets:
|
||||
```bash
|
||||
ssh root@<host> "cat /etc/ssh/ssh_host_ed25519_key.pub"
|
||||
# Add the key to secrets.nix, then re-encrypt:
|
||||
agenix -r -i ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
4. **Deploy**:
|
||||
```bash
|
||||
skyg remote switch <name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Service Module — Checklist
|
||||
|
||||
1. Create `modules/nixos/server/services/<name>.nix`:
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
let cfg = config.skyg.nixos.server.services.<name>; in
|
||||
{
|
||||
options.skyg.nixos.server.services.<name> = {
|
||||
enable = lib.mkEnableOption "Enable <Name>";
|
||||
# add typed options here
|
||||
};
|
||||
config = lib.mkIf cfg.enable {
|
||||
# NixOS configuration goes here
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
2. Import in `modules/nixos/server/services/default.nix`:
|
||||
```nix
|
||||
imports = [ ... ./<name>.nix ];
|
||||
```
|
||||
|
||||
3. Enable on relevant hosts:
|
||||
```nix
|
||||
skyg.nixos.server.services.<name>.enable = true;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key File Locations
|
||||
|
||||
| What | Path |
|
||||
|------|------|
|
||||
| Host registrations (canonical list) | `flake.nix` → `nixosConfigurations` |
|
||||
| Secret authorization map | `secrets.nix` |
|
||||
| User / global config (name, email, etc.) | `flake.nix` → `lib =` binding |
|
||||
| Base module every host receives | `modules/main.nix` |
|
||||
| Home Manager programs | `modules/home/programs.nix` |
|
||||
| Binary cache configuration | `modules/core/nix-substituters.nix` |
|
||||
| SSH master public key | `modules/nixos/common/ssh-server.nix` |
|
||||
| All `skyg` subcommand implementations | `bin/lib/cmds.nu` |
|
||||
| Valid remote deployment targets | `bin/lib/profile.nu` |
|
||||
| Router configs | `openwrt-routers/` |
|
||||
| Desktop compositor configs | `configs/` |
|
||||
| Full host documentation | `docs/hosts/README.md` |
|
||||
| Module architecture + option reference | `docs/modules/README.md` |
|
||||
| Secrets workflow | `docs/secrets/README.md` |
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
AGENTS.md
|
||||
@@ -1,17 +0,0 @@
|
||||
# Claude Instructions — nixos-setup
|
||||
|
||||
**MANDATORY FIRST ACTION:** Read [`GUIDELINES.md`](GUIDELINES.md) in full before
|
||||
doing anything in this repository. It is the single source of truth for agent
|
||||
behavior here.
|
||||
|
||||
Key non-negotiable rules from that file:
|
||||
|
||||
- **Always present a plan first** and wait for user approval before making any
|
||||
changes — no matter how small the task.
|
||||
- **Never run builds or system switches** (`nixos-rebuild`, `nh os`, `skyg os`,
|
||||
`nix build`, `nix flake check`, etc.) — zero exceptions, even if asked.
|
||||
- Never edit `flake.lock`, `*.hardware-configuration.nix`, or anything in
|
||||
`secrets/`.
|
||||
- Never add `imports = [...]` to host files.
|
||||
- Never commit or create branches unless explicitly asked.
|
||||
- Also read [`.agents/Agent.md`](.agents/Agent.md) for full repository context.
|
||||
Reference in new issue
Block a user