Konventions-Geruest anlegen (CLAUDE.md, docs, Obsidian-Vault)
Projekt-CLAUDE.md mit Status, Entscheidungslog E-001..E-006, Architektur mit Mermaid-Diagrammen, COCKPIT/CHANGELOG als Vault-Start. Alt-Doku (CLAUDE_KONTEXT.md, ZUSAMMENFASSUNG_TODO.md) darin aufgegangen. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
78
docs/architektur.md
Normal file
78
docs/architektur.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# Architektur
|
||||
|
||||
Stand: 2026-07-13
|
||||
|
||||
## Ueberblick
|
||||
|
||||
Zwei getrennte Wege: **laufende Updates** (haeufig, automatisch, uebers Netz) und
|
||||
**Komplett-Reimage** (~1×/Jahr, von der externen Platte, ohne Netz).
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Herb["Herb (laptop03 = Master)"]
|
||||
REPO["~/projekte/schul-laptops<br/>(git)"]
|
||||
end
|
||||
|
||||
subgraph Hetzner["Hetzner 46.225.114.15 (nur Git!)"]
|
||||
GITEA["Gitea<br/>admin/schul-laptops (public)"]
|
||||
NGINX["Nginx<br/>git.lehrstun.de:443"]
|
||||
NGINX --> GITEA
|
||||
end
|
||||
|
||||
subgraph Laptop["Schul-Laptop (laptop01–16)"]
|
||||
TIMER["systemd-Timer<br/>Boot + alle 30 min"]
|
||||
PULL["schul-pull.sh →<br/>ansible-pull local.yml"]
|
||||
TIMER --> PULL
|
||||
CHECK["reimage-check.service<br/>(frueh im Boot)"]
|
||||
GRUB["GRUB-Eintrag<br/>Schul-Neuinstallation<br/>(Clonezilla toram)"]
|
||||
CHECK -- "Platte + neueres Image" --> GRUB
|
||||
end
|
||||
|
||||
REPO -- "git push (SSH :2222)" --> GITEA
|
||||
PULL -- "HTTPS 443 (Standard)" --> NGINX
|
||||
PULL -. "Fallback: SSH :2222<br/>Deploy-Key (read-only)" .-> GITEA
|
||||
|
||||
subgraph Platte["Externe Platte DEZNTRSICHERUNG"]
|
||||
IMG["schule-laptop-JJJJ-MM-TT/<br/>(mehrere, neuestes gewinnt)"]
|
||||
end
|
||||
|
||||
GRUB -- "Mini-Menue: AUFSPIELEN (auto) /<br/>IMAGE ERSTELLEN / Abbrechen" --> IMG
|
||||
```
|
||||
|
||||
## Ablauf Reimage (ohne Stick)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant P as Platte (DEZNTRSICHERUNG)
|
||||
participant L as Laptop (altes System)
|
||||
participant C as Clonezilla (toram, aus /boot/clonezilla)
|
||||
|
||||
Note over L: Platte anstecken, einschalten
|
||||
L->>P: reimage-check: neuestes Image > /etc/schul-image-version?
|
||||
L->>L: grub-reboot "Schul-Neuinstallation" + Reboot
|
||||
C->>L: Hostname aus altem /etc/hostname lesen
|
||||
Note over C: Mini-Menue, "AUFSPIELEN" startet nach ~20 s
|
||||
C->>L: ocs-sr restoredisk (Batch, ohne Nachpruefung)
|
||||
C->>L: Hostname, SSH-Host-Keys, Machine-ID,<br/>Versionsdatei schreiben; Admin-Key loeschen (ausser laptop03)
|
||||
Note over L: Poweroff → naechster Boot: fertig, Pull laeuft weiter
|
||||
```
|
||||
|
||||
## Komponenten im Repo
|
||||
|
||||
| Pfad | Zweck |
|
||||
|---|---|
|
||||
| `local.yml` | ansible-pull-Playbook (Updates, Pakete, Selbstverwaltung der Mechanik) |
|
||||
| `group_vars/all.yml` | Paketliste u.a. Variablen |
|
||||
| `files/schul-pull.sh` | Pull-Wrapper: HTTPS zuerst, SSH-Fallback, Journal-Log |
|
||||
| `files/ansible-pull.service/.timer` | systemd-Units (Boot + 30 min, RandomizedDelay) |
|
||||
| `files/first-boot-setup.sh` | Einmalig nach Erstinstallation: Hostname etc. |
|
||||
| `files/reimage-check.*` | Boot-Check: Platte erkannt → Reboot in Clonezilla |
|
||||
| `files/clonezilla/` | Mini-Menue + ocs-sr-Batch-Skripte (Restore/Save) |
|
||||
| `playbooks/`, `inventory.yml`, `update-ips.sh` | Legacy-Push (nur Heimnetz) |
|
||||
|
||||
## Sicherheit
|
||||
|
||||
- Repo public (nur Lesen), enthaelt keine Secrets.
|
||||
- Privater Gitea-Admin-Key existiert nur auf laptop03 (E-005).
|
||||
- Deploy-Key (Fallback) ist read-only und liegt unter `/root/.ssh/` (600).
|
||||
- laptop03: `reimage-check` deaktiviert — der Master ueberschreibt sich nie selbst.
|
||||
62
docs/decisions.md
Normal file
62
docs/decisions.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Entscheidungslog
|
||||
|
||||
Format: E-NNN · Datum · Entscheidung · Begruendung
|
||||
|
||||
## E-001 · 2026-07-13 · Pull statt Push
|
||||
|
||||
**Entscheidung:** Verwaltung der Laptops per `ansible-pull` (Laptops holen sich das
|
||||
Repo selbst), nicht mehr per Ansible-Push vom Controller.
|
||||
|
||||
**Begruendung:** Das Schul-WLAN (Client-Isolation) blockiert mDNS und SSH zwischen
|
||||
den Geraeten — Push und `update-ips.sh` funktionieren dort prinzipbedingt nicht.
|
||||
Pull braucht nur ausgehendes HTTPS. Das Push-Setup bleibt als Legacy fuers Heimnetz.
|
||||
|
||||
## E-002 · 2026-07-13 · Kein Image und kein Paket-Mirror auf dem Hetzner
|
||||
|
||||
**Entscheidung:** Der Hetzner-Server haelt nur das Git-Repo (Gitea) und den
|
||||
HTTPS-Zugang (`git.lehrstun.de` via Nginx). Clonezilla-Images bleiben komplett auf
|
||||
der externen Platte `DEZNTRSICHERUNG`; kein eigener APT-Mirror, keine eigene Distro.
|
||||
|
||||
**Begruendung:** 75-GB-Server zu klein fuer Images/Mirror; Restore uebers Schul-WLAN
|
||||
waere um ein Vielfaches langsamer als von der USB3-Platte (~5–10 min). Reimage ist
|
||||
nur ~1×/Jahr noetig. Sicherheitsupdates kommen direkt von den offiziellen
|
||||
Mint/Ubuntu-Servern.
|
||||
|
||||
## E-003 · 2026-07-13 · Repo-Zugriff: HTTPS als Standard, SSH-Deploy-Key als Fallback
|
||||
|
||||
**Entscheidung:** Laptops pullen per HTTPS von `git.lehrstun.de` (Port 443, Repo
|
||||
oeffentlich lesbar); Fallback SSH Port 2222 mit dediziertem Read-only-Deploy-Key.
|
||||
|
||||
**Begruendung:** Schulnetze blockieren oft alles ausser 80/443. Das Repo enthaelt
|
||||
keine Secrets (geprueft). Kein Token in URLs (globale Regel).
|
||||
|
||||
## E-004 · 2026-07-13 · Jahres-Reimage ohne Stick, Clonezilla im Batch-Modus
|
||||
|
||||
**Entscheidung:** Master-Image enthaelt Clonezilla-Live unter `/boot/clonezilla/`
|
||||
(GRUB-Eintrag, `toram`). Ein Boot-Check-Dienst erkennt die angesteckte Platte mit
|
||||
neuerem Image und startet den Reimage-Vorgang. Eigenes Mini-Menue
|
||||
(„AUFSPIELEN“ vorausgewaehlt mit ~20 s Countdown / „IMAGE ERSTELLEN“ / Abbrechen)
|
||||
statt Clonezilla-TUI; `ocs-sr` direkt im Batch-Modus, alle Sicherheitsschranken und
|
||||
die sektorweise Nachpruefung abgeschaltet.
|
||||
|
||||
**Begruendung:** 12× identische Hardware — Pruefungen bringen wenig, kosten Zeit;
|
||||
Fehlerfaelle behandelt Herb von Hand. Der Hostname bleibt erhalten, indem das
|
||||
Restore-Skript ihn vor dem Ueberschreiben aus dem alten System liest.
|
||||
Versionsvergleich (`/etc/schul-image-version` vs. Datumsname des Images)
|
||||
verhindert Reimage-Schleifen. laptop03 (Master) bespielt sich nie selbst.
|
||||
|
||||
## E-005 · 2026-07-13 · Privater Admin-Key nur auf laptop03
|
||||
|
||||
**Entscheidung:** `first-boot-setup.sh` und das Restore-Skript loeschen den privaten
|
||||
SSH-Key von `puettmann` auf allen Laptops ausser laptop03. Fuer den Pull-Fallback
|
||||
gibt es einen separaten Read-only-Deploy-Key unter `/root/.ssh/`.
|
||||
|
||||
**Begruendung:** Der Key auf laptop03 ist der Gitea-Admin-Key („herb-local“) — er
|
||||
wuerde sonst mit dem Image auf alle Schueler-Laptops geklont.
|
||||
|
||||
## E-006 · 2026-07-13 · Projekt nach Konventionen unter ~/projekte/schul-laptops
|
||||
|
||||
**Entscheidung:** Alter git-loser Ordner `~/ansible-schule` ist vollstaendig in
|
||||
`~/projekte/schul-laptops` aufgegangen (verschoben); git + Gitea-Remote (SSH),
|
||||
Projektordner ist zugleich Obsidian-Vault (COCKPIT.md, CHANGELOG.md,
|
||||
`.obsidian/` gitignored).
|
||||
Reference in New Issue
Block a user