nixos-vorlagen/docs/SETUP_FUER_FREUNDE.md

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

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:

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:

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...

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

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

1.2 Nach Installation: Reboot & Login

sudo reboot
# Login mit den Credentials vom Installer

Phase 2: Repository Setup

2.1 Repo klonen

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

2.2 Hardware-Config hinzufügen

Die aktuelle Hardware-Config vom System kopieren:

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

2.3 Configuration anpassen

nano ~/nixos-config/configuration.nix

Ändere diese 3 Werte:

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

2.4 Desktop & GPU wählen

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

3.2 Flake Inputs aktualisieren (optional)

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

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)

sudo reboot

Nach dem Reboot:

• Neuer Desktop startet
• Gaming-Stack ist installiert
• Alles ready!

---

Nach dem Setup: Erste Schritte

1. System überprüfen

# 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

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

3. Erstes Spiel testen

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

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

# Stelle sicher, du bist im Repo-Verzeichnis
cd ~/nixos-config
nix flake update

Problem: Kein Internet beim Build

Lösung:

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

nix flake update

Problem: "Chaotic-Nyx Cache nicht erreichbar"

Das ist normal! Fallback auf lokales Bauen:

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?

# 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

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

# 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! 🚀