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):

```bash
sudo headscale preauthkeys create --expiration 99y --reusable --user default
```

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

---

## Schritt 2: Host-Konfiguration erstellen

### 2.1 Template kopieren

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

### 2.2 Hostname setzen

`hosts/neuer-pi/networking.nix`:

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

### 2.3 In flake.nix registrieren

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

### 2.4 In constants.nix eintragen

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

### 2.5 Placeholder secrets.yaml erstellen

```bash
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`:

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

---

## Schritt 4: Push und Image bauen lassen

```bash
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**:

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

### 5.2 Dekomprimieren

```bash
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!

```bash
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:

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

### 6.2 SSH verbinden

```bash
ssh steffen@<IP>  # oder der konfigurierte User
```

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

### 6.3 Age-Key ermitteln

Auf dem Pi:

```bash
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:

```yaml
keys:
  - &admin_key age1e8p35795htf7twrejyugpzw0qja2v33awcw76y4gp6acnxnkzq0s935t4t
  - &neuer_pi_key age1xyz...  # Der neue Key

creation_rules:
  # ... bestehende Regeln ...
  
  - path_regex: hosts/neuer-pi/secrets.yaml$
    key_groups:
      - age:
        - *admin_key
        - *neuer_pi_key
```

### 6.5 Secrets erstellen

```bash
sops hosts/neuer-pi/secrets.yaml
```

Inhalt:

```yaml
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

```bash
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:

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

---

## Schritt 8: Verifizieren

### Tailscale-Verbindung

```bash
# 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