steffen 5ba78886d2 Add SD image pipeline, documentation overhaul, and fix module issues

- Add automatic SD image builds for Raspberry Pi via Forgejo Actions
- Enable binfmt emulation on cryodev-main for aarch64 cross-builds
- Add sd-image.nix module to cryodev-pi configuration
- Create comprehensive docs/ structure with installation guides
- Split installation docs into: first-install (server), reinstall, new-client (Pi)
- Add lib/utils.nix and apps/rebuild from synix
- Fix headplane module for new upstream API (tale/headplane)
- Fix various module issues (mailserver stateVersion, option conflicts)
- Add placeholder secrets.yaml files for both hosts
- Remove old INSTRUCTIONS.md (content moved to docs/)

2026-03-11 08:41:58 +01:00

3.7 KiB

Raw Blame History

Erstinstallation (x86_64 Server)

Diese Anleitung beschreibt die manuelle Installation eines neuen x86_64 Servers (z.B. cryodev-main).

Für Raspberry Pi: Siehe Neuen Raspberry Pi hinzufügen - dort wird ein SD-Image automatisch gebaut.

Übersicht

Bei der Erstinstallation gibt es ein Henne-Ei-Problem:

SOPS-Secrets werden mit dem SSH-Host-Key verschlüsselt
Der SSH-Host-Key wird erst bei der Installation generiert
Daher: Erst installieren, dann Secrets konfigurieren

Voraussetzungen

Bootbares NixOS ISO (Minimal ISO)
Netzwerkverbindung
Host-Konfiguration in hosts/<hostname>/ (ohne secrets.yaml)

Schritt 1: Host-Konfiguration vorbereiten

1.1 Template kopieren

cp -r templates/generic-server hosts/neuer-server

1.2 Hostname setzen

hosts/neuer-server/networking.nix:

{
  networking.hostName = "neuer-server";
}

1.3 In flake.nix registrieren

nixosConfigurations = {
  neuer-server = mkNixosConfiguration "x86_64-linux" [ ./hosts/neuer-server ];
};

1.4 Placeholder secrets.yaml erstellen

touch hosts/neuer-server/secrets.yaml

1.5 SOPS-Secrets temporär deaktivieren

In hosts/neuer-server/default.nix alle sops.secrets.* Referenzen auskommentieren oder mit lib.mkIf false umgeben, bis die echten Secrets existieren.

Schritt 2: Zielmaschine vorbereiten

2.1 NixOS ISO booten

Von USB/CD booten.

2.2 Root-Passwort setzen (für SSH)

passwd

2.3 IP-Adresse ermitteln

ip a

2.4 Per SSH verbinden (optional)

ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no nixos@<IP>
sudo -i

Schritt 3: Installation durchführen

3.1 Repository klonen

nix-shell -p git
git clone <GIT_REPO_URL> /tmp/nixos
cd /tmp/nixos

3.2 Disk-Konfiguration anpassen

Wichtig: Die Disk-ID muss zur Hardware passen!

# Verfügbare Disks anzeigen
lsblk -o NAME,SIZE,MODEL,SERIAL
ls -la /dev/disk/by-id/

In hosts/neuer-server/disks.sh oder disks.nix die richtige Disk-ID eintragen.

3.3 Install-Script ausführen

bash scripts/install.sh -n neuer-server

Das Script:

Partitioniert die Disk (via disko oder disks.sh)
Generiert hardware.nix (falls nicht vorhanden)
Installiert NixOS

3.4 Reboot

umount -Rl /mnt
reboot

Schritt 4: Nach dem ersten Boot

4.1 Einloggen

Standard-Passwort: changeme

passwd  # Sofort ändern!

4.2 SSH-Host-Key zu Age-Key konvertieren

nix-shell -p ssh-to-age --run 'cat /etc/ssh/ssh_host_ed25519_key.pub | ssh-to-age'

Ausgabe notieren! (z.B. age1abc123...)

4.3 Auf Entwicklungsrechner: SOPS konfigurieren

.sops.yaml bearbeiten:

keys:
  - &admin_key age1e8p35795htf7twrejyugpzw0qja2v33awcw76y4gp6acnxnkzq0s935t4t
  - &neuer_server_key age1abc123...  # Key von oben

creation_rules:
  - path_regex: hosts/neuer-server/secrets.yaml$
    key_groups:
      - age:
        - *admin_key
        - *neuer_server_key

4.4 Secrets erstellen

sops hosts/neuer-server/secrets.yaml

Mindestens den Tailscale Auth-Key eintragen (siehe nächster Schritt).

4.5 SOPS-Referenzen wieder aktivieren

Die in Schritt 1.5 auskommentierten sops.secrets.* Referenzen wieder aktivieren.

4.6 Konfiguration deployen

# Lokal bauen und per SSH deployen
nixos-rebuild switch --flake .#neuer-server --target-host root@<IP>

Nächste Schritte

Tailscale einrichten - VPN-Verbindung
Netdata konfigurieren - Monitoring
CD einrichten - Automatisches Deployment

3.7 KiB Raw Blame History