Feat: Fügt AGENTS.md hinzu und aktualisiert Dokumentation
This commit is contained in:
@@ -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.
|
||||||
Reference in New Issue
Block a user