infra-nix/.github/copilot-instructions.md

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:

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

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