# 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