steffen/cryodev
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions

translate all docs to English

Browse source 
Translate 8 documentation files from German to English:
- docs/index.md (complete)
- docs/getting-started/first-install.md (complete)
- docs/getting-started/new-client.md (complete)
- docs/getting-started/reinstall.md (complete)
- docs/getting-started/sd-image.md (complete)
- docs/deployment/dns.md (PTR, Hetzner, checklist sections)
- docs/services/tailscale.md (code comments)
- docs/services/forgejo.md (placeholder names)
This commit is contained in:
steffen 2026-03-14 15:31:50 +01:00
parent c81b43530a
commit a0da5be8fc
8 changed files with 386 additions and 386 deletions
Download patch file Download diff file Expand all files Collapse all files

244
docs/getting-started/first-install.md
View file

@ -1,44 +1,44 @@
# Erstinstallation (x86_64 Server)
# Initial Installation (x86_64 Server)
Diese Anleitung beschreibt die **Erstinstallation** eines neuen x86_64 Servers (z.B. cryodev-main).
This guide describes the **initial installation** of a new x86_64 server (e.g. cryodev-main).
> **Fuer Raspberry Pi:** Siehe [SD-Image erstellen](sd-image.md).
> **For Raspberry Pi:** See [Creating an SD Image](sd-image.md).
## Uebersicht
## Overview
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**
During initial installation there is a chicken-and-egg problem:
- SOPS secrets are encrypted with the SSH host key
- The SSH host key is only generated during installation
- Therefore: **Install without secrets first, then configure secrets**
### Ablauf
### Process
```
1. Services deaktivieren (die Secrets brauchen)
2. NixOS installieren
3. SSH-Host-Key extrahieren, SOPS konfigurieren, sofort erstellbare Secrets anlegen
4. Stufe-1-Services aktivieren und deployen (Headscale, Forgejo, Mail, Nginx)
5. Restliche Secrets generieren (Tailscale, Headplane, Forgejo-Runner)
6. Stufe-2-Services aktivieren und final deployen
1. Disable services (that require secrets)
2. Install NixOS
3. Extract SSH host key, configure SOPS, create immediately available secrets
4. Enable stage-1 services and deploy (Headscale, Forgejo, Mail, Nginx)
5. Generate remaining secrets (Tailscale, Headplane, Forgejo Runner)
6. Enable stage-2 services and perform final deployment
```
## Schritt 1: Host-Konfiguration vorbereiten
## Step 1: Prepare Host Configuration
> Falls der Host bereits in `hosts/` und `flake.nix` existiert, ueberspringe 1.1-1.2.
> If the host already exists in `hosts/` and `flake.nix`, skip 1.1-1.2.
### 1.1 Host aus Template erstellen
### 1.1 Create Host from Template
```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
The script:
- Copies the template to `hosts/<hostname>/`
- Sets the hostname in `networking.nix`
- Creates an empty `secrets.yaml`
- Adds the files to Git
### 1.2 In flake.nix registrieren
### 1.2 Register in flake.nix
```nix
nixosConfigurations = {
@ -46,24 +46,24 @@ nixosConfigurations = {
};
```
Ausserdem `hardware.nix` und `disks.sh` fuer die Zielhardware anpassen.
Also adjust `hardware.nix` and `disks.sh` for the target hardware.
### 1.4 Services temporaer deaktivieren
### 1.4 Temporarily Disable Services
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.
All services that reference SOPS secrets must be disabled for the initial installation. Otherwise the installation will fail because the secrets cannot yet be decrypted.
In `hosts/<hostname>/services/default.nix` die entsprechenden Imports auskommentieren:
In `hosts/<hostname>/services/default.nix`, comment out the corresponding imports:
```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
# Disabled until SOPS secrets are configured:
# ./forgejo.nix # requires: forgejo-runner/token, forgejo/mail-pw
# ./headplane.nix # requires: headplane/cookie_secret, headplane/agent_pre_authkey
# ./mailserver.nix # requires: mailserver/accounts/*
# ./tailscale.nix # requires: tailscale/auth-key
# Diese Services brauchen keine Secrets:
# These services do not require secrets:
./headscale.nix
./netdata.nix
./nginx.nix
@ -73,7 +73,7 @@ In `hosts/<hostname>/services/default.nix` die entsprechenden Imports auskomment
}
```
Zusaetzlich in `hosts/<hostname>/services/sops.nix` die Secrets-Definitionen auskommentieren:
Additionally, in `hosts/<hostname>/services/sops.nix`, comment out the secret definitions:
```nix
sops = {
@ -85,32 +85,32 @@ sops = {
};
```
### 1.5 Konfiguration testen
### 1.5 Test the Configuration
```bash
nix eval .#nixosConfigurations.<hostname>.config.system.build.toplevel.name
```
## Schritt 2: Installation durchfuehren
## Step 2: Perform Installation
### 2.1 NixOS ISO booten
### 2.1 Boot NixOS ISO
Vom [NixOS Minimal ISO](https://nixos.org/download/#nixos-iso) booten (USB/CD).
Boot from the [NixOS Minimal ISO](https://nixos.org/download/#nixos-iso) (USB/CD).
### 2.2 Netzwerk und SSH einrichten
### 2.2 Set Up Network and SSH
```bash
passwd # Root-Passwort setzen fuer SSH-Zugang
ip a # IP-Adresse ermitteln
passwd # Set root password for SSH access
ip a # Determine IP address
```
Optional per SSH verbinden (bequemer):
Optionally connect via SSH (more convenient):
```bash
ssh -o StrictHostKeyChecking=no root@<IP>
```
### 2.3 Installieren
### 2.3 Install
```bash
nix --experimental-features "nix-command flakes" run \
@ -119,20 +119,20 @@ nix --experimental-features "nix-command flakes" run \
-r <REPO_URL>
```
Alternativ, falls das Repository bereits unter `/tmp/nixos` geklont wurde:
Alternatively, if the repository has already been cloned to `/tmp/nixos`:
```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/`.
> **Note:** The disk ID in `hosts/<hostname>/disks.sh` must match the hardware.
> Verify with `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
The script:
1. Clones the repository (when using `-r`)
2. Partitions the disk (via `disks.nix` or `disks.sh`)
3. Generates `hardware.nix` (if not present)
4. Installs NixOS
### 2.4 Reboot
@ -140,34 +140,34 @@ Das Script:
reboot
```
## Schritt 3: SOPS-Secrets konfigurieren
## Step 3: Configure SOPS Secrets
Nach dem ersten Boot einloggen (Passwort: `changeme`, sofort aendern mit `passwd`).
After the first boot, log in (password: `changeme`, change immediately with `passwd`).
### 3.1 SSH-Host-Key zu Age-Key konvertieren
### 3.1 Convert SSH Host Key to Age Key
Auf dem **neuen Server**:
On the **new 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...`).
Note the output (e.g. `age1abc123...`).
Alternativ remote:
Alternatively, remotely:
```bash
nix-shell -p ssh-to-age --run 'ssh-keyscan -p 2299 -t ed25519 <IP> | ssh-to-age'
```
### 3.2 .sops.yaml aktualisieren
### 3.2 Update .sops.yaml
Auf dem **Entwicklungsrechner** den neuen Host-Key in `.sops.yaml` eintragen:
On the **development machine**, add the new host key to `.sops.yaml`:
```yaml
keys:
- &steffen_key age1e8p... # steffen (lokal)
- &hostname_key age1abc... # Key von Schritt 3.1
- &steffen_key age1e8p... # steffen (local)
- &hostname_key age1abc... # Key from step 3.1
creation_rules:
- path_regex: hosts/<hostname>/secrets.yaml$
@ -177,38 +177,38 @@ creation_rules:
- *hostname_key
```
### 3.3 Secrets erstellen
### 3.3 Create Secrets
Secrets-Datei oeffnen:
Open the secrets file:
```bash
sops hosts/<hostname>/secrets.yaml
```
Die folgende Tabelle zeigt alle Secrets fuer **cryodev-main** und wie sie generiert werden:
The following table shows all secrets for **cryodev-main** and how they are generated:
#### Sofort erstellbare Secrets
#### Immediately Available Secrets
Diese Secrets haben keine Abhaengigkeiten und koennen direkt generiert werden:
These secrets have no dependencies and can be generated directly:
| Secret | Befehl |
|--------|--------|
| Secret | Command |
|--------|---------|
| `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 |
| `mailserver/accounts/admin` | `mkpasswd -sm bcrypt` (remember the password!) |
| `mailserver/accounts/forgejo` | `mkpasswd -sm bcrypt` (remember the password!) |
| `forgejo/mail-pw` | Plaintext password matching the bcrypt hash of `mailserver/accounts/forgejo` |
#### Secrets die laufende Services brauchen
#### Secrets That Require Running Services
Diese Secrets koennen erst nach Schritt 4 erstellt werden. **Jetzt noch nicht eintragen** -- sie werden spaeter ergaenzt.
These secrets can only be created after step 4. **Do not add them yet** -- they will be added later.
| Secret | Befehl | Voraussetzung |
|--------|--------|---------------|
| `tailscale/auth-key` | Siehe Schritt 4.1-4.2 | Headscale laeuft |
| `headplane/agent_pre_authkey` | Siehe Schritt 4.1-4.2 | Headscale laeuft |
| `forgejo-runner/token` | Forgejo Admin Panel > Actions > Runners > Create Runner | Forgejo laeuft |
| Secret | Command | Prerequisite |
|--------|---------|--------------|
| `tailscale/auth-key` | See steps 4.1-4.2 | Headscale is running |
| `headplane/agent_pre_authkey` | See steps 4.1-4.2 | Headscale is running |
| `forgejo-runner/token` | Forgejo Admin Panel > Actions > Runners > Create Runner | Forgejo is running |
#### Beispiel secrets.yaml (Klartext vor Verschluesselung)
#### Example secrets.yaml (Plaintext Before Encryption)
```yaml
headplane:
@ -218,22 +218,22 @@ mailserver:
admin: "$2b$05$..."
forgejo: "$2b$05$..."
forgejo:
mail-pw: "das-klartext-passwort"
mail-pw: "the-plaintext-password"
```
### 3.4 Services stufenweise reaktivieren -- Stufe 1
### 3.4 Gradually Re-enable Services -- Stage 1
> **Wichtig:** Services die Headscale- oder Forgejo-Secrets brauchen (Tailscale,
> Headplane, Forgejo-Runner) duerfen noch **nicht** aktiviert werden, da diese
> Secrets erst generiert werden koennen, wenn die Services laufen.
> **Important:** Services that require Headscale or Forgejo secrets (Tailscale,
> Headplane, Forgejo Runner) must **not** be enabled yet, as these
> secrets can only be generated once those services are running.
Auf dem **Entwicklungsrechner** in `hosts/<hostname>/services/default.nix` die
Services **ohne externe Abhaengigkeiten** aktivieren:
On the **development machine**, in `hosts/<hostname>/services/default.nix`, enable
the services **without external dependencies**:
```nix
{
imports = [
# Stufe 1: Services ohne externe Abhaengigkeiten
# Stage 1: Services without external dependencies
./forgejo.nix
./headscale.nix
./mailserver.nix
@ -242,88 +242,88 @@ Services **ohne externe Abhaengigkeiten** aktivieren:
./openssh.nix
./sops.nix
# Stufe 2: Erst nach Schritt 4 aktivieren
# ./forgejo-runner.nix # braucht: forgejo-runner/token (Forgejo)
# ./headplane.nix # braucht: headplane/agent_pre_authkey (Headscale)
# ./tailscale.nix # braucht: tailscale/auth-key (Headscale)
# Stage 2: Enable only after step 4
# ./forgejo-runner.nix # requires: forgejo-runner/token (Forgejo)
# ./headplane.nix # requires: headplane/agent_pre_authkey (Headscale)
# ./tailscale.nix # requires: tailscale/auth-key (Headscale)
];
}
```
### 3.5 Deployen (Stufe 1)
### 3.5 Deploy (Stage 1)
```bash
nix run .#deploy -- -n <hostname>
```
Dies nutzt die Konfiguration aus `deploy.json`. Alternativ manuell:
This uses the configuration from `deploy.json`. Alternatively, deploy manually:
```bash
NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#<hostname> \
--target-host <user>@<IP> --sudo --ask-sudo-password
```
Nach diesem Deploy laufen Headscale, Forgejo, Mailserver und Nginx.
After this deployment, Headscale, Forgejo, Mailserver, and Nginx are running.
### 3.6 Forgejo Admin-Account erstellen
### 3.6 Create Forgejo Admin Account
Beim ersten Start hat Forgejo noch keine Benutzer. Admin-Account per CLI anlegen
(auf dem **Server**):
On first start, Forgejo has no users. Create an admin account via CLI
(on the **server**):
```bash
forgejo admin user create \
--username <benutzername> \
--username <username> \
--email <email>@<domain> \
--password <passwort> \
--password <password> \
--admin
```
> **Hinweis:** Das `forgejo` Shell-Alias wird vom Modul bereitgestellt und fuehrt
> automatisch den Befehl als `forgejo`-User mit der richtigen Config aus.
> Falls der Alias nicht verfuegbar ist, neue Shell starten (`bash` oder `zsh`).
> **Note:** The `forgejo` shell alias is provided by the module and automatically
> runs the command as the `forgejo` user with the correct config.
> If the alias is not available, start a new shell (`bash` or `zsh`).
>
> Da `DISABLE_REGISTRATION = true` gesetzt ist, koennen neue Accounts
> nur per CLI erstellt werden.
> Since `DISABLE_REGISTRATION = true` is set, new accounts
> can only be created via CLI.
## Schritt 4: Restliche Secrets generieren und alle Services aktivieren
## Step 4: Generate Remaining Secrets and Enable All Services
Nachdem der Server mit Headscale und Forgejo laeuft:
After the server is running with Headscale and Forgejo:
1. **Headscale-User anlegen** (auf dem Server):
1. **Create Headscale users** (on the server):
```bash
sudo headscale users create default
sudo headscale users create headplane-agent
```
2. **User-IDs ermitteln** (wird fuer die Preauth-Keys benoetigt):
2. **Determine user IDs** (needed for the preauth keys):
```bash
sudo headscale users list
```
Die Ausgabe zeigt die numerischen IDs (z.B. `1` fuer default, `2` fuer headplane-agent).
The output shows the numeric IDs (e.g. `1` for default, `2` for headplane-agent).
3. **Preauth-Keys generieren** (mit den IDs aus Schritt 2):
3. **Generate preauth keys** (using the IDs from step 2):
```bash
# Fuer Tailscale (User-ID von "default" einsetzen)
# For Tailscale (use the user ID of "default")
sudo headscale preauthkeys create --expiration 99y --reusable --user <ID>
# Fuer Headplane Agent (User-ID von "headplane-agent" einsetzen)
# For Headplane Agent (use the user ID of "headplane-agent")
sudo headscale preauthkeys create --expiration 99y --user <ID>
```
4. **Forgejo-Runner-Token** ueber das Forgejo Admin Panel erstellen:
4. **Create the Forgejo Runner token** via the Forgejo Admin Panel:
Administration > Actions > Runners > Create new Runner
5. **Secrets ergaenzen**:
5. **Add the remaining secrets**:
```bash
sops hosts/<hostname>/secrets.yaml
```
Die fehlenden Secrets eintragen:
Add the missing secrets:
```yaml
tailscale:
@ -334,7 +334,7 @@ Nachdem der Server mit Headscale und Forgejo laeuft:
agent_pre_authkey: "..."
```
6. **Stufe-2-Services aktivieren** in `hosts/<hostname>/services/default.nix`:
6. **Enable stage-2 services** in `hosts/<hostname>/services/default.nix`:
```nix
{
@ -353,14 +353,14 @@ Nachdem der Server mit Headscale und Forgejo laeuft:
}
```
6. **Erneut deployen**:
6. **Deploy again**:
```bash
nix run .#deploy -- -n <hostname>
```
## Naechste Schritte
## Next Steps
- [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
- [SOPS Reference](../services/sops.md) -- Detailed documentation on secret management
- [Creating an SD Image](sd-image.md) -- Install Raspberry Pi
- [Set Up CD](../deployment/cd.md) -- Automatic deployment