cryodev/docs/getting-started/first-install.md

Erstinstallation (x86_64 Server)

Diese Anleitung beschreibt die Erstinstallation eines neuen x86_64 Servers (z.B. cryodev-main).

Fuer Raspberry Pi: Siehe SD-Image erstellen.

Uebersicht

Bei der Erstinstallation gibt es ein Henne-Ei-Problem:

• SOPS-Secrets werden mit dem SSH-Host-Key verschluesselt
• Der SSH-Host-Key wird erst bei der Installation generiert
• Daher: Erst ohne Secrets installieren, dann Secrets konfigurieren

Ablauf

1. Services deaktivieren (die Secrets brauchen)
2. NixOS installieren
3. SSH-Host-Key extrahieren, SOPS konfigurieren, Secrets erstellen
4. Services reaktivieren und deployen

Schritt 1: Host-Konfiguration vorbereiten

Falls der Host bereits in hosts/ und flake.nix existiert, ueberspringe 1.1-1.3.

1.1 Template kopieren

cp -r templates/generic-server hosts/<hostname>

1.2 Hostname setzen

hosts/<hostname>/networking.nix:

{
  networking.hostName = "<hostname>";
  networking.domain = "cryodev.xyz";
}

1.3 In flake.nix registrieren

nixosConfigurations = {
  <hostname> = mkNixosConfiguration "x86_64-linux" [ ./hosts/<hostname> ];
};

1.4 Services temporaer deaktivieren

Alle Services, die SOPS-Secrets referenzieren, muessen fuer die Erstinstallation deaktiviert werden. Andernfalls schlaegt die Installation fehl, weil die Secrets noch nicht entschluesselt werden koennen.

In hosts/<hostname>/services/default.nix die entsprechenden Imports auskommentieren:

{
  imports = [
    # Deaktiviert bis SOPS-Secrets konfiguriert sind:
    # ./forgejo.nix     # braucht: forgejo-runner/token, forgejo/mail-pw
    # ./headplane.nix   # braucht: headplane/cookie_secret, headplane/agent_pre_authkey
    # ./mailserver.nix  # braucht: mailserver/accounts/*
    # ./tailscale.nix   # braucht: tailscale/auth-key

    # Diese Services brauchen keine Secrets:
    ./headscale.nix
    ./netdata.nix
    ./nginx.nix
    ./openssh.nix
    ./sops.nix
  ];
}

Zusaetzlich in hosts/<hostname>/services/sops.nix die Secrets-Definitionen auskommentieren:

sops = {
  defaultSopsFile = ../secrets.yaml;
  # secrets = {
  #   "forgejo-runner/token" = { };
  #   "tailscale/auth-key" = { };
  # };
};

1.5 Konfiguration testen

nix eval .#nixosConfigurations.<hostname>.config.system.build.toplevel.name

Schritt 2: Installation durchfuehren

2.1 NixOS ISO booten

Vom NixOS Minimal ISO booten (USB/CD).

2.2 Netzwerk und SSH einrichten

passwd                  # Root-Passwort setzen fuer SSH-Zugang
ip a                    # IP-Adresse ermitteln

Optional per SSH verbinden (bequemer):

ssh -o StrictHostKeyChecking=no root@<IP>

2.3 Installieren

nix --experimental-features "nix-command flakes" run \
  git+<REPO_URL>#apps.x86_64-linux.install -- \
  -n <hostname> \
  -r <REPO_URL>

Alternativ, falls das Repository bereits unter /tmp/nixos geklont wurde:

nix --experimental-features "nix-command flakes" run /tmp/nixos#install -- -n <hostname>

Hinweis: Die Disk-ID in hosts/<hostname>/disks.sh muss zur Hardware passen. Pruefen mit ls -la /dev/disk/by-id/.

Das Script:

1. Klont das Repository (bei -r)
2. Partitioniert die Disk (via disks.nix oder disks.sh)
3. Generiert hardware.nix (falls nicht vorhanden)
4. Installiert NixOS

2.4 Reboot

reboot

Schritt 3: SOPS-Secrets konfigurieren

Nach dem ersten Boot einloggen (Passwort: changeme, sofort aendern mit passwd).

3.1 SSH-Host-Key zu Age-Key konvertieren

Auf dem neuen Server:

nix-shell -p ssh-to-age --run 'cat /etc/ssh/ssh_host_ed25519_key.pub | ssh-to-age'

Ausgabe notieren (z.B. age1abc123...).

Alternativ remote:

nix-shell -p ssh-to-age --run 'ssh-keyscan -p 2299 -t ed25519 <IP> | ssh-to-age'

3.2 .sops.yaml aktualisieren

Auf dem Entwicklungsrechner den neuen Host-Key in .sops.yaml eintragen:

keys:
  - &admin_key age1e8p...     # Dein lokaler Admin-Key
  - &hostname_key age1abc...  # Key von Schritt 3.1

creation_rules:
  - path_regex: hosts/<hostname>/secrets.yaml$
    key_groups:
      - age:
          - *admin_key
          - *hostname_key

3.3 Secrets erstellen

Secrets-Datei oeffnen:

sops hosts/<hostname>/secrets.yaml

Die folgende Tabelle zeigt alle Secrets fuer cryodev-main und wie sie generiert werden:

Sofort erstellbare Secrets

Diese Secrets haben keine Abhaengigkeiten und koennen direkt generiert werden:

Secret	Befehl
headplane/cookie_secret	openssl rand -hex 16
mailserver/accounts/admin	mkpasswd -sm bcrypt (Passwort merken!)
mailserver/accounts/forgejo	mkpasswd -sm bcrypt (Passwort merken!)
forgejo/mail-pw	Klartext-Passwort das zum bcrypt-Hash von mailserver/accounts/forgejo passt

Secrets die laufende Services brauchen

Diese Secrets koennen erst erstellt werden, nachdem die entsprechenden Services laufen. Bis dahin Platzhalter eintragen (z.B. placeholder):

Secret	Befehl	Voraussetzung
tailscale/auth-key	sudo headscale preauthkeys create --expiration 99y --reusable --user default	Headscale laeuft
headplane/agent_pre_authkey	sudo headscale users create headplane-agent && sudo headscale preauthkeys create --expiration 99y --user headplane-agent	Headscale laeuft
forgejo-runner/token	Forgejo Admin Panel > Actions > Runners > Create Runner	Forgejo laeuft

Beispiel secrets.yaml (Klartext vor Verschluesselung)

tailscale:
    auth-key: "placeholder"
forgejo-runner:
    token: "placeholder"
headplane:
    cookie_secret: "a1b2c3d4e5f6..."
    agent_pre_authkey: "placeholder"
mailserver:
    accounts:
        admin: "$2b$05$..."
        forgejo: "$2b$05$..."
forgejo:
    mail-pw: "das-klartext-passwort"

3.4 Services reaktivieren

Auf dem Entwicklungsrechner die in Schritt 1.4 auskommentierten Imports in hosts/<hostname>/services/default.nix wieder aktivieren:

{
  imports = [
    ./forgejo.nix
    ./headplane.nix
    ./headscale.nix
    ./mailserver.nix
    ./netdata.nix
    ./nginx.nix
    ./openssh.nix
    ./sops.nix
    ./tailscale.nix
  ];
}

Ebenso in hosts/<hostname>/services/sops.nix die Secrets-Definitionen wieder einkommentieren.

3.5 Deployen

nixos-rebuild switch --flake .#<hostname> \
  --target-host <user>@<IP> --use-remote-sudo \
  --ssh-option="-p 2299"

Schritt 4: Platzhalter-Secrets ersetzen

Nachdem der Server mit Headscale und Forgejo laeuft, die Platzhalter durch echte Werte ersetzen:

1. Headscale-User anlegen (auf dem Server):

   sudo headscale users create default
   sudo headscale users create headplane-agent
   

2. Preauth-Keys generieren:

   # Fuer Tailscale
   sudo headscale preauthkeys create --expiration 99y --reusable --user default
   
   # Fuer Headplane Agent
   sudo headscale preauthkeys create --expiration 99y --user headplane-agent
   

3. Forgejo-Runner-Token ueber das Forgejo Admin Panel erstellen: Administration > Actions > Runners > Create new Runner

4. Secrets aktualisieren:

   sops hosts/<hostname>/secrets.yaml
   # Platzhalter durch echte Werte ersetzen
   

5. Erneut deployen:

   nixos-rebuild switch --flake .#<hostname> \
     --target-host <user>@<IP> --use-remote-sudo \
     --ssh-option="-p 2299"
   

Naechste Schritte

• SOPS-Referenz -- Detail-Dokumentation zur Secret-Verwaltung
• SD-Image erstellen -- Raspberry Pi installieren
• CD einrichten -- Automatisches Deployment