Feat: Fügt AGENTS.md hinzu und aktualisiert Dokumentation

2026-08-23 00:39:20 +02:00
parent 3e2c7af0cb
commit a84e248e52
1 changed files with 104 additions and 0 deletions
@@ -0,0 +1,104 @@
+# AGENTS.md — Entwickler- und Agenten-Dokumentation für DockerUpdate
+
+Diese Datei dient als Leitfaden und Kontextdokumentation für autonome Agenten und Entwickler, die an der Codebasis von
+`docker-update` arbeiten.
+
+---
+
+## 1. Projektübersicht
+
+`docker-update` ist ein schlankes CLI-Werkzeug für **Linux-Server** (Rust 2024 Edition). Es durchsucht Verzeichnisse mit
+Docker-Compose-Dateien (standardmäßig `/var/apps`), prüft definierte Services mit `:latest`-Images auf neuere Versionen,
+lädt diese herunter, startet betroffene Services neu und bereinigt ungenutzte Zwischen-Images.
+
+### Wichtige Rahmenbedingungen & Prinzipien
+
+- **Reines Linux-Projekt**: Die Anwendung ist ausschließlich für Linux vorgesehen. Es dürfen keine Windows-spezifischen
+  Konstrukte oder bedingten Nicht-Linux-Kompilierungen (`#[cfg(target_os = ...)]`) hinzugefügt werden.
+- **Root-Rechte**: Die Anwendung erfordert Root-Rechte zur Verwaltung von Docker und Compose-Services. Fehlen diese,
+  eskaliert sie via `sudo`.
+- **Keine Unicode-Emojis im Logging**: Das Logging-Modul (`src/log.rs`) verwendet einheitliche ASCII-Präfixe (`[!]`
+  Error, `[?]` Warn, `[i]` Info, `[d]` Debug).
+- **Lizenz**: GNU General Public License v3.0 or later (`GPL-3.0-or-later`).
+
+---
+
+## 2. Modul- und Codestruktur
+
+```text
+DockerUpdate/
+├── Cargo.toml          # Rust-Manifest, Abhängigkeiten und Metadaten für cargo-deb / generate-rpm
+├── Cargo.lock
+├── LICENSE             # GPL-3.0 Lizenztext
+├── README.md           # Projektdokumentation für Endanwender und Administratoren
+├── AGENTS.md           # Richtlinien und Dokumentation für Agenten
+├── packaging/
+│   ├── arch/
+│   │   └── PKGBUILD    # Arch Linux PKGBUILD
+│   └── fedora/
+│       └── docker-update.spec # RPM-Spec für Fedora / RHEL / CentOS
+└── src/
+    ├── main.rs         # Einstiegspunkt, Root-Prüfung, Ausführung
+    ├── program.rs      # Hilfsfunktion zur Programmnamensermittlung
+    ├── sudo.rs         # Root-Prüfung (geteuid == 0) und Re-Exec via sudo
+    ├── config.rs       # Konfigurationsverwaltung (confy / TOML)
+    ├── log.rs          # Threadsicheres Logging (Terminal + Datei im Temp-Verzeichnis)
+    └── updater.rs      # Scan-, Pull-, Restart- und Bereinigungslogik für Compose-Apps
+```
+
+### Modulverantwortlichkeiten
+
+- **`src/main.rs`**:
+  Initialer Startpunkt. Prüft mit `sudo::is_run_as_root()`, ob Root-Rechte vorliegen. Wenn nicht, wird mit
+  `sudo::run_as_root()` neu gestartet. Ruft anschließend `updater::run_updates()` auf.
+- **`src/updater.rs`**:
+    - Sucht in Unterverzeichnissen von `apps_dir` nach Compose-Dateien (`docker-compose.yaml`, `docker-compose.yml`,
+      `compose.yaml`, `compose.yml`).
+    - Parst Services via `serde_yaml` und filtert mit `is_latest_image()` nach Services mit `:latest`-Images oder ohne
+      expliziten Tag.
+    - Führt `docker pull` für jedes gefundene Image aus und vergleicht Vorher/Nachher-Image-IDs via
+      `docker image inspect`.
+    - Startet bei Änderungen Services neu (`docker compose up -d` mit Fallback auf `docker-compose up -d`).
+    - Führt nach Updates `docker image prune -f` aus.
+- **`src/config.rs`**:
+    - Lädt und speichert die Konfiguration (`AppConfig`, `General` mit `apps_dir` und `log_level`).
+    - Standardpfade: `/etc/docker-update/config.toml` (Root) bzw. `~/.config/docker-update/config.toml` (Benutzer).
+- **`src/log.rs`**:
+    - Formatiert Logmeldungen nach Schema `[Präfix][Zeitstempel][LEVEL][Tag]: Nachricht`.
+    - Gibt auf Konsole aus und schreibt zusätzlich in tagesbasierte Logdateien im Temp-Verzeichnis
+      (`/tmp/docker-update-.../log-YYYY-MM-DD.log`).
+- **`src/sudo.rs`**:
+    - `is_run_as_root()`: Nutzt `libc::geteuid() == 0`.
+    - `run_as_root()`: Führt `sudo <args>` per `exec` aus.
+
+---
+
+## 3. Build-, Test- und Prüfbefehle
+
+Vor jedem Commit oder Abschluss einer Aufgabe müssen folgende Befehle erfolgreich durchlaufen:
+
+```bash
+# 1. Compiler- und Typ-Prüfung für alle Targets
+cargo check --all-targets
+
+# 2. Ausführen aller Unit-Tests
+cargo test
+
+# 3. Release-Build kompilieren
+cargo build --release
+```
+
+---
+
+## 4. Richtlinien für Änderungen
+
+1. **Abwärtskompatibilität & Pfade**:
+   Der Standard-Apps-Pfad `/var/apps` und die Konfigurationspfade dürfen nicht ohne triftigen Grund geändert werden.
+2. **Paketierungsdefinitionen synchron halten**:
+   Werden Abhängigkeiten oder Assets geändert, müssen `Cargo.toml` (`[package.metadata.deb]`,
+   `[package.metadata.generate-rpm]`), `packaging/arch/PKGBUILD` und `packaging/fedora/docker-update.spec` entsprechend
+   aktualisiert werden.
+3. **Automatisierung**:
+   Die empfohlene Automatisierungsmethode ist **Cron** (`/etc/cron.d/docker-update` oder `crontab -e`).
+4. **Keine Mocking-Bypässe**:
+   Tests dürfen nicht gelöscht, ignoriert oder durch leere Dummy-Assertions ersetzt werden.