# Für Freunde: Komplette Anleitung zum Repo nutzen

Alles, was du und deine Freunde wissen müssen, um dieses Repo erfolgreich zu nutzen.

---

## Das Repo beim Klonen - Was passiert?

### Schritt 1: Repo klonen

```bash
git clone <REPO-URL> ~/nixos-config
cd ~/nixos-config
```

**Was wird geklont?**
- ✅ `flake.nix` – Die Eingangsdatei
- ✅ `flake.lock` – Gepinnte Versionen für reproduzierbare Builds
- ✅ Alle Module im `modules/`-Verzeichnis
- ✅ `configuration.nix` – Basis-Config
- ✅ `hardware-configuration.nix` – Host-spezifische Beispiel-/Ausgangsdatei
- ✅ Alle `.md`-Dateien (Anleitungen)
- ✅ Git-History

**Was musst du trotzdem prüfen?**
- `hardware-configuration.nix` muss zu deinem Rechner passen.
- Auf einem anderen PC solltest du sie durch die lokal generierte Datei aus `/etc/nixos/` ersetzen.

### Schritt 2: Inputs prüfen oder aktualisieren

Nach dem Klonen kannst du direkt mit den gepinnten Versionen bauen. Wenn du bewusst aktualisieren willst:

```bash
cd ~/nixos-config
nix flake update
```

**Was das macht:**
- Lädt alle Inputs herunter (nixpkgs, chaotic-nyx)
- Aktualisiert `flake.lock`
- Speichert exakte Versionen aller Abhängigkeiten

**Wichtig:** `flake.lock` ist nicht hardware-spezifisch. Sie pinnt nur die Versionen der Flake-Inputs. Hardware-spezifisch ist vor allem `hardware-configuration.nix`.

---

## Warum `flake.lock` im Repo ist

**Gut - das ist absichtlich!**

### Ohne `flake.lock`

```
Problem: Jeder Build kann andere Versionen von nixpkgs und Chaotic-Nyx ziehen.
- Alice baut heute
- Bob baut in zwei Wochen
- Charlie baut nach einem größeren nixpkgs-Update
→ schwerer vergleichbare Fehler und weniger reproduzierbare Builds
```

### Mit `flake.lock`

```
Alle starten mit denselben Input-Versionen.
- weniger Überraschungen beim ersten Build
- Updates passieren bewusst mit `nix flake update`
- Änderungen an nixpkgs/chaotic lassen sich als Git-Diff sehen
```

---

## Stable vs Unstable - Was sollte im Repo sein?

### Aktuelle Wahl: `nixos-unstable` ✅ (Richtig!)

**flake.nix sagt:**
```nix
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
```

**Warum unstable für dieses Repo?**

| Kriterium | Stable | Unstable |
|-----------|--------|----------|
| **Stabilität** | Hoch | Mittel (aber gut getestet) |
| **Aktuelle Treiber** | ⚠️ Verzögert | ✅ Täglich neu |
| **Gaming** | Funktioniert | **Optimal** |
| **Mesa-Git** | ❌ Nicht möglich | ✅ Ja |
| **Chaotic-Nyx** | ❌ Nicht kompatibel | ✅ Ja |
| **Steam/Proton** | Funktioniert | **Neuste Fixes** |

**Conclusion:** `nixos-unstable` ist die richtige Wahl für Gaming + Chaotic-Nyx.

### Stable braucht man NUR wenn...

```nix
# Nur in speziellen Fällen:
# - Production/Server (nicht Gaming!)
# - Maximale Stabilität wichtiger als aktuelle Treiber
# - Ältere Hardware (bekommt keine neuen Features)

# NICHT empfohlen für dieses Gaming-Template!
```

---

## Kompletter Setup-Prozess für Freunde

### Phase 1: Vorbereitung (vor Clone)

**1.1 Frische NixOS-Installation**

Du/deine Freunde brauchen eine funktionierende NixOS-Installation:

```bash
# Auf der Installations-CD
# Normaler NixOS-Installer durchlaufen
# Irgendeine Config aussuchen (wird überschrieben)
```

**1.2 Nach Installation: Reboot & Login**

```bash
sudo reboot
# Login mit den Credentials vom Installer
```

### Phase 2: Repository Setup

**2.1 Repo klonen**

```bash
git clone <DEIN-REPO> ~/nixos-config
cd ~/nixos-config
```

**2.2 Hardware-Config hinzufügen**

Die aktuelle Hardware-Config vom System kopieren:

```bash
sudo cp /etc/nixos/hardware-configuration.nix ~/nixos-config/
```

**2.3 Configuration anpassen**

```bash
nano ~/nixos-config/configuration.nix
```

Ändere diese 3 Werte:

```nix
hostName = "mein-gaming-pc";    # Computername
userName = "max";                # Benutzername
fullName = "Max Mustermann";     # Vollständiger Name
```

**2.4 Desktop & GPU wählen**

```nix
desktopConfig = ./modules/desktop/kde.nix;      # oder cosmic-max.nix, gnome.nix, etc.
graphicsConfig = ./modules/graphics/mesa-amd.nix; # oder nvidia.nix, etc.
```

### Phase 3: Flake vorbereiten

**3.1 Cachix überprüfen (Beschleunigung!)**

Dieses Repo nutzt bereits **Chaotic-Nyx Cachix** (vorkompilierte Pakete).

Das bedeutet:
- ✅ Builds sind 4-6x schneller
- ✅ Statt 90 Min → nur 15-30 Min
- ✅ Automatisch aktiviert, kein Setup nötig

**Mehr Infos:** Siehe [`CACHIX_ANLEITUNG.md`](CACHIX_ANLEITUNG.md)

**3.2 Flake Inputs aktualisieren (optional)**

```bash
cd ~/nixos-config
nix flake update
```

**Das macht:**
- Lädt alle Packages herunter
- Aktualisiert `flake.lock`
- Speichert exakte Versionen

**Dauer:** meist wenige Minuten, je nach Internetverbindung.

Für den ersten Build kannst du diesen Schritt überspringen und die Versionen aus dem Repo nutzen.

### Phase 4: System bauen & starten

**4.1 NixOS Rebuild**

```bash
sudo nixos-rebuild switch --flake .#template
```

**Das macht:**
- Baut NixOS mit deiner Config
- Installiert alle Packages
- Aktiviert sofort (kein Reboot nötig für erste Konfiguration)

**Dauer:** 10-60 Minuten (beim ersten Mal)

**Mögliche Fehler:**
- "Network is unreachable" → Netzwerk prüfen
- "Insufficient disk space" → Zu wenig Platz auf /nix
- Irgendwas mit nixpkgs → `nix flake update` und retry

**4.2 Reboot (optional aber empfohlen)**

```bash
sudo reboot
```

Nach dem Reboot:
- Neuer Desktop startet
- Gaming-Stack ist installiert
- Alles ready!

---

## Nach dem Setup: Erste Schritte

### 1. System überprüfen

```bash
# Desktop prüfen
echo $DESKTOP_SESSION

# GPU prüfen
glxinfo | grep "OpenGL"

# Mesa-Git aktiv?
glxinfo | grep "Mesa"

# Gaming-Tools
which steam
which gamescope
which mangohud
```

### 2. Steam einrichten

```bash
steam
# Größe/Auflösung anpassen
# Account einloggen
# Controller Settings prüfen
```

### 3. Erstes Spiel testen

```bash
# In Steam: Ein Spiel aus der Bibliothek starten
# (oder Proton-Spiel ausprobieren)
# Performance mit mangohud checken
```

---

## Mesa-Git für Freunde erklären

### Einfache Erklärung:

```
Mesa-Git = Täglich neue GPU-Treiber für AMD

Aktiviert in: modules/chaotic-nyx.nix
- enable = true  → aktiv (Standard)
- enable = false → deaktiviert

Wenn's crasht: Fallback bootet automatisch auf stabile Version
```

### Falls Freunde fragen: "Warum Mesa-Git?"

Antworte:
- **AMD-Nutzer:** "Neueste Treiber = bessere Gaming-Performance"
- **NVIDIA-Nutzer:** "Ignorieren, ihr nutzt proprietäre Treiber"
- **Intel:** "Funktioniert, aber nicht optimiert für Gaming"

### Falls Mesa-Git Probleme macht:

```bash
# In modules/chaotic-nyx.nix:
enable = false;  # Mesa-Git aus

sudo nixos-rebuild switch --flake .#template
# System bootet auf stabile Mesa
```

---

## Häufige Probleme & Lösungen

### Problem: `flake.lock` oder Flake-Inputs machen Probleme

**Symptom:**
```
nixpkgs/chaotic kann nicht geladen werden oder ein Input wirkt veraltet
```

**Lösung:**
```bash
# Stelle sicher, du bist im Repo-Verzeichnis
cd ~/nixos-config
nix flake update
```

### Problem: Kein Internet beim Build

**Lösung:**
```bash
# Netzwerk testen
ping github.com

# Falls offline: Später probieren
# Falls Online aber langsam: Geduld haben (kann 30+ min dauern)
```

### Problem: Eigene `flake.lock` von einem Fork?

Wenn du aus einem Fork kommst und bewusst neu pinnen willst:
```bash
nix flake update
```

### Problem: "Chaotic-Nyx Cache nicht erreichbar"

**Das ist normal!** Fallback auf lokales Bauen:
```bash
sudo nixos-rebuild switch --flake .#template --no-substitute
# Dauert länger, aber funktioniert
```

---

## Checkliste für Freunde

**Vor Setup:**
- [ ] Frische NixOS-Installation
- [ ] Internet funktioniert
- [ ] Genug Platz auf Festplatte (~50 GB frei)

**Beim Setup:**
- [ ] Repo geklont
- [ ] Hardware-Config kopiert
- [ ] configuration.nix angepasst
- [ ] Desktop & GPU gewählt
- [ ] `nix flake update` ausgeführt

**Nach Setup:**
- [ ] Desktop startet
- [ ] Gaming-Tools erkannt (`which steam`)
- [ ] GPU erkannt (`glxinfo`)
- [ ] Erstes Spiel testet

**Optional:**
- [ ] Steam Account einrichten
- [ ] Controller testen
- [ ] Performance benchmarken

---

## Version-Management für Freunde

### Warum `flake.lock` committen?

```bash
# Immer committen, wenn du die System-Basis bewusst aktualisierst:
flake.lock
```

**Grund:**
```
flake.lock = reproduzierbare Input-Versionen
- nixpkgs bleibt nachvollziehbar
- chaotic bleibt nachvollziehbar
- Updates lassen sich im Git-Diff reviewen

→ Wenn etwas kaputtgeht, weißt du genauer, seit welchem Update.
```

### Richtig versionieren

```bash
# ✅ Immer committen:
- flake.nix (Eingabe-Definition)
- flake.lock (Input-Versionen)
- configuration.nix (Config)
- modules/ (Die ganzen Module)
- *.md (Dokumentation)

# ⚠️ Nur committen, wenn das Repo wirklich genau diesen Host beschreibt:
- hardware-configuration.nix
```

---

## Forks & Customization für Freunde

### Falls Freunde das Repo forken wollen

```bash
# 1. Fork machen
github.com/dein-name/nixos → Fork auf github.com/dein-name/nixos

# 2. Clone forked version
git clone https://github.com/dein-name/nixos ~/nixos-config

# 3. Anpassen
cd ~/nixos-config
# Alle Anpassungen durchführen

# 4. Eigene changes committen
git add modules/packages.nix
git commit -m "Meine Pakete hinzugefügt"
git push

# Falls Updates vom Original gewünscht:
git remote add upstream https://github.com/dein-name/nixos.git
git pull upstream main
```

---

## Zusammenfassung für Freunde

| Frage | Antwort |
|-------|---------|
| **Brauche ich flake.lock?** | Ja, sie ist im Repo und pinnt die Input-Versionen |
| **Stable oder Unstable?** | `nixos-unstable` (für Gaming optimal) |
| **Mesa-Git automatisch?** | Ja, aktiviert in modules/chaotic-nyx.nix |
| **Kann ich den Desktop wechseln?** | Ja, einfach die Zeile in configuration.nix ändern |
| **Wie update ich später?** | `nix flake update && sudo nixos-rebuild switch --flake .#template` |
| **Kann ich meine Anpassungen speichern?** | Ja, in Unterordnern oder neuen Modulen |

---

**Alles klar? Jetzt können deine Freunde direkt loslegen!** 🚀