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](sd-image.md).

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

### 1.1 Host aus Template erstellen

```bash
nix run .#create -- -t generic-server -n <hostname>
```

Das Script:
- Kopiert das Template nach `hosts/<hostname>/`
- Setzt den Hostname in `networking.nix`
- Erstellt eine leere `secrets.yaml`
- Fuegt die Dateien zu Git hinzu

### 1.2 In flake.nix registrieren

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

Ausserdem `hardware.nix` und `disks.sh` fuer die Zielhardware anpassen.

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

```nix
{
  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:

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

### 1.5 Konfiguration testen

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

## Schritt 2: Installation durchfuehren

### 2.1 NixOS ISO booten

Vom [NixOS Minimal ISO](https://nixos.org/download/#nixos-iso) booten (USB/CD).

### 2.2 Netzwerk und SSH einrichten

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

Optional per SSH verbinden (bequemer):

```bash
ssh -o StrictHostKeyChecking=no root@<IP>
```

### 2.3 Installieren

```bash
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:

```bash
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

```bash
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**:

```bash
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:

```bash
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:

```yaml
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:

```bash
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)

```yaml
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:

```nix
{
  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

```bash
nix run .#deploy -- -n <hostname>
```

Dies nutzt die Konfiguration aus `deploy.json`. Alternativ manuell:

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

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

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

2. **Preauth-Keys generieren**:

   ```bash
   # 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**:

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

5. **Erneut deployen**:

   ```bash
   nix run .#deploy -- -n <hostname>
   ```

## Naechste Schritte

- [SOPS-Referenz](../services/sops.md) -- Detail-Dokumentation zur Secret-Verwaltung
- [SD-Image erstellen](sd-image.md) -- Raspberry Pi installieren
- [CD einrichten](../deployment/cd.md) -- Automatisches Deployment