174 lines
4.2 KiB
Markdown
174 lines
4.2 KiB
Markdown
# GitHub Copilot Instructions – infra-nix (NixOS Infrastructure)
|
||
|
||
Copilot soll in diesem Repo so unterstützen, dass die Struktur der NixOS-
|
||
Infrastruktur konsistent, deklarativ und sauber bleibt. Diese Anweisung
|
||
gilt für alle Dateien im Repository, insbesondere für Flakes, Modules,
|
||
Hosts, Deployment-Skripte und Shell-Files.
|
||
|
||
---
|
||
|
||
## 🧱 Projektstruktur
|
||
|
||
Das Repository enthält eine deklarative NixOS-Infrastruktur für zwei
|
||
Systeme:
|
||
|
||
- **fileserver**
|
||
→ SMB, FileBrowser (OCI Container), rclone-Backup, /data-Datendisk
|
||
|
||
- **gateway**
|
||
→ AdGuardHome (DNS), Caddy (Reverse Proxy), feste IPs
|
||
|
||
Globale Struktur:
|
||
|
||
```
|
||
infra-nix/
|
||
├─ flake.nix
|
||
├─ hosts/
|
||
│ ├─ fileserver/
|
||
│ │ ├─ configuration.nix
|
||
│ │ └─ hardware-configuration.nix
|
||
│ └─ gateway/
|
||
│ ├─ configuration.nix
|
||
│ └─ hardware-configuration.nix
|
||
└─ modules/
|
||
├─ common.nix
|
||
├─ fileserver.nix
|
||
└─ gateway.nix
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 Ziele für Copilot
|
||
|
||
Copilot soll:
|
||
|
||
1. **Nur deklarative Änderungen vorschlagen**, die mit NixOS-Flakes kompatibel sind.
|
||
2. Die bestehende Struktur respektieren:
|
||
- `hosts/*` → Host-spezifisch
|
||
- `modules/*` → Rollen / Services
|
||
- Keine Vermischung
|
||
3. Immer die Syntax und Konventionen von NixOS 25.05 einhalten.
|
||
4. Kein imperatives Bash/Script in Nix-Files vorschlagen.
|
||
5. Installationsscripte sollen *nur* im Ordner `install/` liegen.
|
||
6. Kein Secret in irgendwelche Dateien einfügen.
|
||
|
||
---
|
||
|
||
## 🚫 Copilot darf NICHT:
|
||
|
||
- rclone-Konfigs einfügen
|
||
- API-Keys, Tokens, SSH-Keys generieren
|
||
- Passwörter hartcodieren (außer Platzhalter im Installer)
|
||
- Konfigurationen mischen (z. B. Caddy-Konfig in fileserver host packen)
|
||
- SystemstateVersions verändern
|
||
- hardware-configuration.nix anfassen (außer Kommentar)
|
||
|
||
---
|
||
|
||
## 🟢 Copilot SOLL:
|
||
|
||
### **Flakes**
|
||
- NUR `flake.nix` updaten, wenn Struktur unverändert bleibt.
|
||
- `nixosConfigurations.<host>` sauber definieren.
|
||
- Keine Inputs manipulieren, außer wenn der Nutzer es verlangt.
|
||
|
||
### **Modules**
|
||
- Rein deklarative NixOS-Optionen vorschlagen.
|
||
- Firewall-Regeln nur innerhalb der Host- oder Rollenmodule definieren.
|
||
- systemd-Services korrekt bauen:
|
||
- `serviceConfig.Type = "oneshot";`
|
||
- `wantedBy = [ "multi-user.target" ];` oder Timer.
|
||
|
||
### **Hosts**
|
||
- Netzwerk-Konfiguration korrekt setzen:
|
||
- `networking.useDHCP = false;`
|
||
- `networking.interfaces.<iface>.ipv4.addresses = [...]`
|
||
- `networking.defaultGateway`
|
||
- `networking.nameservers`
|
||
|
||
### **Installer-Skripte**
|
||
- Bash-Skripte strikt POSIX-kompatibel generieren.
|
||
- Partitionierung per `parted` + `mkfs` sauber halten.
|
||
- Nie secret-basierte Dinge reinschreiben.
|
||
- Platzhalter-Passwörter erlauben (z. B. "changeme").
|
||
|
||
### **Deployment**
|
||
Copilot soll folgende Struktur unterstützen:
|
||
|
||
```
|
||
deploy.sh
|
||
install/install-fileserver.sh
|
||
install/install-gateway.sh
|
||
```
|
||
|
||
Deploy-Script-Regeln:
|
||
|
||
- remote `git pull`
|
||
- remote `nixos-rebuild switch --flake .#host`
|
||
- Fehlermeldungen klar halten
|
||
- SSH-Verbindungen per definierte Host-IPs nutzen
|
||
|
||
---
|
||
|
||
## 📄 Stil & Format-Vorgaben
|
||
|
||
- Nix-Files immer **2 spaces indent**, keine Tabs.
|
||
- Kommentare in Nix:
|
||
```nix
|
||
# Kommentar
|
||
```
|
||
- Bash-Skripte:
|
||
- `set -euo pipefail`
|
||
- Funktionen statt dupliziertem Code
|
||
- Keine trailing spaces
|
||
|
||
---
|
||
|
||
## 🛡 Security
|
||
|
||
Copilot darf:
|
||
- KEINE Secrets generieren
|
||
- KEINE echten Passwörter erstellen
|
||
- KEINE private Keys einfügen
|
||
- KEINE rclone.conf, sops/age Keys etc. erstellen
|
||
- KEINE Passwörter automatisch setzen außer Dummy im Installer
|
||
|
||
---
|
||
|
||
## 🧪 Testbarkeit / Rebuilds
|
||
|
||
Copilot soll bevorzugt:
|
||
|
||
```bash
|
||
sudo nixos-rebuild switch --flake .#fileserver
|
||
```
|
||
|
||
und NICHT den alten channel-basierten Modus vorschlagen.
|
||
|
||
---
|
||
|
||
## 🔧 Erweiterbare Bereiche
|
||
|
||
Copilot darf folgende Rollen ergänzen, wenn der Nutzer danach fragt:
|
||
- zusätzlicher Storage Host
|
||
- Monitoring-VM (Prometheus/Grafana)
|
||
- Backup-VM
|
||
- VPN (WireGuard)
|
||
- Logging-Server
|
||
|
||
Dabei:
|
||
- eigene module-Dateien erzeugen
|
||
- Hosts sauber anlegen
|
||
- Struktur konsistent halten
|
||
|
||
---
|
||
|
||
## 🧩 Zusammenfassung
|
||
|
||
Copilot soll helfen:
|
||
- Struktur beizubehalten
|
||
- deklarativ zu bleiben
|
||
- nichts zu vermischen
|
||
- saubere, sichere, reproducible NixOS-Konfigurationen zu erzeugen
|
||
- Install- und Deploy-Skripte korrekt, minimal und robust zu halten
|