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/)
This commit is contained in:
steffen
parent
a5261d8ff0
commit
5ba78886d2
44 changed files with 3570 additions and 609 deletions
282
docs/getting-started/new-client.md
Normal file
282
docs/getting-started/new-client.md
Normal file
|
|
@ -0,0 +1,282 @@
|
|||
# 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
|
||||
nixos-rebuild switch --flake .#neuer-pi --target-host root@<IP>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue