cryodev/docs/getting-started/new-client.md

Neuen Raspberry Pi Client hinzufügen

Diese Anleitung beschreibt das Hinzufügen eines neuen Raspberry Pi Clients zur Infrastruktur.

Übersicht: Der Ablauf

1. Konfiguration erstellen     ──► Template kopieren, anpassen
         │
         ▼
2. Zur Image-Pipeline hinzufügen ──► Workflow-Matrix erweitern
         │
         ▼
3. Push auf main              ──► Forgejo baut automatisch SD-Image
         │
         ▼
4. Image flashen & booten     ──► SD-Karte beschreiben, Pi starten
         │
         ▼
5. SOPS konfigurieren         ──► Age-Key holen, Secrets erstellen
         │
         ▼
6. Finales Deployment         ──► Tailscale etc. aktivieren

Voraussetzungen

• SSH-Zugang zu cryodev-main (für Tailscale Auth-Key)
• Entwicklungsrechner mit Repository-Zugriff
• SD-Karte (mindestens 8 GB)

---

Schritt 1: Tailscale Auth-Key generieren

Auf cryodev-main (per SSH):

# User-ID ermitteln
sudo headscale users list
# Preauth-Key erstellen (User-ID von "default" einsetzen)
sudo headscale preauthkeys create --expiration 99y --reusable --user <ID>

Ausgabe notieren! (z.B. tskey-preauth-abc123...)

---

Schritt 2: Host-Konfiguration erstellen

2.1 Template kopieren

cp -r templates/raspberry-pi hosts/neuer-pi

2.2 Hostname setzen

hosts/neuer-pi/networking.nix:

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

2.3 In flake.nix registrieren

nixosConfigurations = {
  # ... bestehende Hosts ...
  
  neuer-pi = mkNixosConfiguration "aarch64-linux" [ ./hosts/neuer-pi ];
};

2.4 In constants.nix eintragen

{
  hosts = {
    # ... bestehende Hosts ...
    
    neuer-pi = {
      ip = "100.64.0.X";  # Wird von Headscale vergeben
    };
  };
}

2.5 Placeholder secrets.yaml erstellen

touch hosts/neuer-pi/secrets.yaml

2.6 SOPS temporär deaktivieren

In hosts/neuer-pi/default.nix die sops.secrets.* Referenzen auskommentieren, damit das Image ohne Secrets gebaut werden kann.

---

Schritt 3: Zur Image-Pipeline hinzufügen

Bearbeite .forgejo/workflows/build-pi-image.yml:

jobs:
  build-pi-images:
    strategy:
      matrix:
        # Neuen Host hier hinzufügen:
        host: [cryodev-pi, neuer-pi]

---

Schritt 4: Push und Image bauen lassen

git add .
git commit -m "Add neuer-pi host configuration"
git push

Der Forgejo Workflow baut jetzt automatisch ein SD-Image für neuer-pi.

Warten bis der Workflow fertig ist (30-60 Minuten). Status prüfen unter: https://git.cryodev.xyz/steffen/cryodev-server/actions

---

Schritt 5: Image flashen

5.1 Image herunterladen

Nach erfolgreichem Build unter Releases:

wget https://git.cryodev.xyz/steffen/cryodev-server/releases/latest/download/neuer-pi-sd-image.img.zst

5.2 Dekomprimieren

zstd -d neuer-pi-sd-image.img.zst -o neuer-pi.img

5.3 Auf SD-Karte schreiben

Achtung: /dev/sdX durch das richtige Gerät ersetzen!

lsblk  # Richtiges Gerät finden
sudo dd if=neuer-pi.img of=/dev/sdX bs=4M conv=fsync status=progress

5.4 Booten

1. SD-Karte in den Raspberry Pi einlegen
2. Ethernet anschließen
3. Strom anschließen
4. Warten bis gebootet (ca. 2 Minuten)

---

Schritt 6: SOPS konfigurieren

6.1 IP-Adresse finden

Der Pi sollte per DHCP eine IP bekommen. Prüfe deinen Router oder scanne das Netzwerk:

nmap -sn 192.168.1.0/24 | grep -B2 "Raspberry"

6.2 SSH verbinden

ssh steffen@<IP>  # oder der konfigurierte User

Standard-Passwort siehe hosts/neuer-pi/users.nix.

6.3 Age-Key ermitteln

Auf dem Pi:

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

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

6.4 .sops.yaml aktualisieren

Auf dem Entwicklungsrechner:

keys:
  - &steffen_key age1e8p35795htf7twrejyugpzw0qja2v33awcw76y4gp6acnxnkzq0s935t4t  # steffen (local)
  - &neuer_pi_key age1xyz...  # Der neue Key

creation_rules:
  # ... bestehende Regeln ...

  - path_regex: hosts/neuer-pi/secrets.yaml$
    key_groups:
      - age:
          - *steffen_key
          - *neuer_pi_key

6.5 Secrets erstellen

sops hosts/neuer-pi/secrets.yaml

Inhalt:

tailscale:
  auth-key: "tskey-preauth-abc123..."  # Key aus Schritt 1

netdata:
  stream:
    child-uuid: "..."  # uuidgen

6.6 SOPS-Referenzen aktivieren

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

---

Schritt 7: Finales Deployment

git add .
git commit -m "Configure SOPS secrets for neuer-pi"
git push

Da Comin auf dem Pi läuft, wird er die neue Konfiguration automatisch pullen.

Alternativ manuell:

NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#neuer-pi \
  --target-host <user>@<IP> --sudo --ask-sudo-password

---

Schritt 8: Verifizieren

Tailscale-Verbindung

# Auf dem Pi
tailscale status

# Auf cryodev-main
sudo headscale nodes list

Netdata-Streaming

Prüfe ob der neue Client im Netdata-Dashboard erscheint: https://netdata.cryodev.xyz

---

Checkliste

• Tailscale Auth-Key auf cryodev-main generiert
• Host-Konfiguration erstellt (Template, flake.nix, constants.nix)
• Host zur Workflow-Matrix hinzugefügt
• Gepusht und auf Image-Build gewartet
• SD-Karte geflasht und Pi gebootet
• Age-Key ermittelt und in .sops.yaml eingetragen
• secrets.yaml erstellt (Tailscale-Key, Netdata-UUID)
• SOPS-Referenzen aktiviert und deployed
• Tailscale-Verbindung funktioniert
• Netdata-Streaming funktioniert