updatarr

Updatarr entdeckt Dependencies, bewertet Updates anhand der Repository-Policy und erstellt sichere Forgejo-Pull-Requests. Das Rust-Backend verwendet Axum, SeaORM/PostgreSQL sowie die veröffentlichten Common-/Dracula-Bausteine. Die bestätigte Werkzeug-Runtime enthält Wolfi-Pakete und bestehende offizielle Toolchains in einem finalen scratch-Image.

Zuständigkeit

wuast-crates ist das eigenständige Repository für wuast-common und wuast-ui. Wiederverwendbare Konfigurationsparser, Problem-Details-Antworten, Logging, Shutdown und UI-Komponenten werden dort entwickelt und veröffentlicht. Dieses Repository enthält die Service-Konfiguration, Domain-Fehler, Handler und Router-Zusammenstellung. Die verbindlichen Regeln stehen in AGENTS.md; CLAUDE.md verweist auf dieselbe Zuständigkeit.

rust-template ist die verbindliche Referenz für Grundaufbau, CI, Tooling, Justfile, Agenten-Regeln und Container/Lifecycle aller Apps. wuast-ui ist der gemeinsame UI-Baukasten: Apps wählen und arrangieren Elemente frei und verwenden dokumentierte Optionen für Schriftgröße, semantische Farben, Größen und Dichte. Der Grundstil und seine Defaults bleiben in der Library, damit zentrale Styling-Updates beim nächsten Dependency-Update übernommen werden. Fehlende Bausteine oder Optionen werden dort kompatibel ergänzt und vor der App-Integration veröffentlicht. Potenziell inkompatible Änderungen benötigen vorher die ausdrückliche Entscheidung des Users. CLAUDE.md und GEMINI.md enthalten über Symlinks denselben vollständigen Regelsatz wie AGENTS.md.

Entwicklung

Voraussetzungen: Rust über rustup (Toolchain aus rust-toolchain.toml), just, Git; Docker für die isolierten Datenbanktests und Container-Checks. CI stellt die Testdienste selbst bereit. Die echten Tooltests benötigen Git/SSH, Node/npm, Bun, Python/uv, Go, Rustup/Cargo, Elixir/Mix/Rebar und OpenTofu; bash scripts/install-app-tools.sh installiert die aus dem Dockerfile abgeleiteten Linux-Werkzeuge. Der vorhandene Playwright-Weg prüft UI und echte Backendaktionen.

just setup     # gepinnte cargo-deny/cargo-machete/git-cliff-Versionen und Hooks
just run
just gate      # Pflicht bei funktionalen Änderungen; derselbe Aufruf läuft in Forgejo
just push      # Git-Push; nach Erfolg repo-eigenes target/ vollständig aufräumen

just push origin main oder just push --set-upstream origin feature/mein-thema reichen Git-Argumente unverändert weiter. Nach einem erfolgreichen tatsächlichen Push entfernt cargo clean ausschließlich das lokale target/, einschließlich Coverage-/Browser-Ausgaben. Fehler und Dry-Runs erhalten den Ordner. just clean räumt separat auf; globale Cargo-/Rustup-/Docker-Caches und Anwendungsdaten bleiben erhalten. Der nächste lokale Build kompiliert erneut. Notwendige kompakte Nachweise vorher dokumentieren; direkter git push oder ein IDE-Push lösen die Bereinigung nicht aus. Git bietet keinen lokalen Post-Push-Hook.

just gate prüft Formatierung, Clippy ohne Warnungen, alle Tests, RustSec-Advisories/Dependency-Bans und ungenutzte Dependencies. Cargo-Builds und Tests verwenden --locked. Duplicate-Versionen werden entsprechend deny.toml als Warnungen gemeldet; Lizenzprüfungen sind nicht Teil dieses Gates. Reine Dokumentation, beschreibende Metadaten und nachweislich ungenutzte Migrationsreste benötigen nach Prüfung des Diffs keinen lokalen Gate; die genaue Abgrenzung steht in AGENTS.md.

Tests prüfen eigene Verarbeitung anhand definierter Inputs und unabhängig erwarteter Ergebnisse. Keine Quelltext-, Versionspin-, UI-Titel- oder CSS-Klassen-Prüfungen. Der verbindliche Standard und die Testebenen sind in docs/testing.md dokumentiert und gelten für alle abgeleiteten Apps.

Rust-Umbau und Betrieb

Der technische Umbau ist vollständig nativ verifiziert und als v0.12.4 veröffentlicht. Migrationsnachweis und Datenübernahme/Betrieb dokumentieren Funktionsabnahme, Import, Restore und Rückweg. old/ und working/ wurden nach erfolgreicher Abnahme entfernt; die archivierte Go-Revision bleibt in Git. Produktionsumschaltung separat über GitOps.

Kanonischer Ablauf für weitere Migrationen

Zuerst old/, working/ und den vollständigen Template-Grundaufbau herstellen; die vorher belegte Git-/Image-Identität erhalten. Danach vor der fachlichen Rust-Implementierung ein vollständiges, quell- und laufzeitgestütztes App-/Dependency-Inventar erstellen. Jede Funktion muss vollständig ersetzt und durch tatsächlich ausgeführte Szenarien einschließlich Daten und Nebenwirkungen nachgewiesen werden. Altcode erst nach geprüftem Ersatz entfernen; keine Platzhalter oder Teilstände als fertige Migration. Die echten Rust-Tests laufen über just gate in CI; just parity ist optional, kein dauerhafter Go-Doppelrunner erforderlich. Verbindlicher Startauftrag, Inventarvorlage, Abschlussnachweis.

Konfiguration

Variable	Default	Verhalten
HOST	0.0.0.0	IPv4-/IPv6-Adresse, z. B. 127.0.0.1 oder ::1; keine DNS-Namen
PORT	8080	u16; 0 lässt das Betriebssystem einen freien Port wählen
SHUTDOWN_TIMEOUT_SECS	10	Positive Zahl; gemeinsames begrenztes HTTP-/Worker-Draining nach SIGTERM/SIGINT; anschließend separat begrenztes Schließen der Verbindungen
LOG_LEVEL	info	error, warn, info, debug, trace; abgeschlossene HTTP-Antworten mit Status, Dauer und Request-ID ab info
LOG_FORMAT	automatisch	Pretty bei TTY, JSON bei Pipe/Container; json/pretty überschreiben die Auswahl
RUST_LOG	—	Individueller Tracing-Filter, überschreibt LOG_LEVEL

Fehlende Konfigurationswerte verwenden Defaults. Ungültige oder nicht als Unicode lesbare Werte für Host, Port und Shutdown-Timeout verhindern den Start. Der Log nennt die tatsächlich gebundene Adresse, auch bei PORT=0.

HTTP-Vertrag

Pfad	Antwort
GET /healthz	200, {"status":"ok"}
GET /ready	200 mit ready oder 503 mit not_ready
GET /api/v1/status	JSON mit name, version, status, uptime_secs
GET /	Dracula-Dashboard
GET /_assets/*	Eingebettete Assets aus wuast-ui

Domain-Fehler sowie unbekannte API-Routen und nicht unterstützte API-Methoden liefern RFC-9457-Problem-Details mit application/problem+json. Interne Fehlerdetails werden ausschließlich serverseitig geloggt. Neue Handler müssen ihre Domain- und Extractor-Fehler in AppError überführen, damit dieser Vertrag erhalten bleibt.

Updatarr betreiben

DATABASE_URL ist erforderlich. PostgreSQL ist das Cargo-Default; im Betrieb wird kein Redis benötigt. Native Migrationen laufen vor Listener und Workern. Repository-Konfigurationen verwenden .updatarr.yaml, ersatzweise .updatarr.yml; die YAML-Datei hat Vorrang. Persistierte nichtleere Forgejo-/GitHub-Settings überschreiben Envwerte. Scans und automatische PR-Erstellung sind zunächst deaktiviert und werden über Settings gesteuert.

Die Repo-Ansicht zeigt während eines Scans aktuelle Phasen, Datei-/Dependency-Zähler und parallel aktive Lookups. Verarbeitung, Regex-Optimierung und Nachweise.

Wolfi-Pakete werden standardmäßig pro Repository gemeinsam aktualisiert. In Settings kann ein crates.io-Sparse-Proxy für öffentliche Crate-Lookups aktiviert werden; initial aus und ohne URL, bei Ausfall ohne direkten Fallback. Verhalten und Nachweis.

Feld	Default / Zweck
BASE_URL	http://localhost:<PORT>
UPDATARR_REPOSITORY_ROOT	lokal /workspace/.updatarr/repos, im Image /var/lib/updatarr/repos
UPDATARR_LOOKUP_CONCURRENCY	16, positive Anzahl gleichzeitiger Lookupoperationen je Scan
UPDATARR_SCAN_CONCURRENCY	2, positive Anzahl paralleler Repository-Scans; dasselbe Repo bleibt exklusiv
FORGEJO_BASE_URL, FORGEJO_TOKEN, GITHUB_TOKEN	optional; Token benötigt eine Forgejo-BaseURL
CORS_ALLOWED_ORIGINS	optional, kommaseparierte HTTP(S)-Origins
UPDATARR_DATASOURCE_FIXTURE_FILE	optionaler absoluter Pfad zu einem kontrollierten Providerfixture

Das Image läuft als 65532:65532 mit schreibgeschütztem Root. Repository-Volume, Home und Cache-/Temp-Volumes müssen diesem Benutzer Schreibrechte geben. /tmp benötigt Ausführungsrechte: Go-/Cargo-Folgeoperationen und Tofu-Provider führen temporär erzeugte Binaries aus. Bei Docker-Tmpfs ausdrücklich rw,exec verwenden; das implizite noexec verhindert diese Funktionen. Rustup startet mit der gebündelten Toolchain und installiert projektbezogene Toolchains in den beschreibbaren Cache. /app und die gebündelten Werkzeuge bleiben read-only.

Die UI umfasst Repositories, Discovery/Import, Scan-/Dependency-Evidenz, Vorschläge und Settings. Die vorhandenen /api/...-Routen sowie /api/health und /api/ready bleiben erhalten; native /healthz, /ready und /metrics ergänzen den Betrieb. Zugriffsschutz erfolgt weiterhin über Envoy/Authelia.

Für die einmalige Datenübernahme und den Rückweg siehe Betriebsanleitung, für Funktions-IDs und Prüfstand Inventar und Abschlussnachweis.

Für Image-Releases erforderlich: HARBOR_USERNAME und HARBOR_PASSWORD. Die SPDX-SBOM wird ohne Signierung im eigenen Harbor mit dem Image-Digest verknüpft und zurückgeprüft; siehe SBOM-Vertrag. Der gemeinsame S3-Compiler-Cache benötigt lokal gültige Credentials und in CI AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY; Endpoint/Bucket haben gemeinsame Defaults. Einrichtung und Buildpfade. Der Release bricht bei fehlender erforderlicher Konfiguration vor dem Image-Push ab.

Releases und Container

PRs durchlaufen .forgejo/workflows/ci.yml; Pushes auf main und manuelle Releases .forgejo/workflows/release.yaml. Release-Läufe werden serialisiert und laufende Veröffentlichungen nicht abgebrochen. Fehler bei der Versionsberechnung führen zu einem fehlgeschlagenen Workflow. Wiederholungen verwenden die Notes des bereits getaggten Releases.

Ein erneuter Lauf desselben getaggten Commits darf dessen Release wiederholen. Spätere reine test:-/style:-Commits erzeugen keinen Release und überschreiben keine veröffentlichte Image-Version. Eine berechnete Version auf einer anderen Git-Historie stoppt die Veröffentlichung vor dem Build.

git-cliff bestimmt die Version aus Conventional Commits. Diese wird als APP_VERSION beim Build übergeben und erscheint identisch im Image-Tag, OCI-Label, Startup-Log, Status-Endpunkt und HTTP-User-Agent. Lokale Builds verwenden die Cargo-Paketversion. APP_VERSION akzeptiert stabile SemVer-Versionen ohne v-Präfix.

Das Image verwendet scratch, UID/GID 65532, CA-Roots, Europe/Berlin, /tmp und Cargo-Manifeste für SBOM-Scanner. Bei readOnlyRootFilesystem benötigen schreibende Anwendungen ein separates temporäres Volume. Health-Probes erfolgen per HTTP durch den Kubelet. Die unsignierte SPDX-SBOM wird am Image-Digest erstellt, im eigenen Harbor veröffentlicht und zurückgeprüft; scratch ersetzt keine Dependency-Advisory-Prüfung.

CI-Actions sind auf Commit-SHAs gepinnt. scripts/ci-tools.lock enthält Versionen, feste Download-URLs und SHA256-Hashes der Linux/amd64-Tools. Aktualisierungen müssen URL, Version und verifizierten Hash gemeinsam ändern; der Installer führt ungeprüfte Downloads nicht aus.

Weitere Befehle: just test, just clippy, just fmt, just outdated, just build, just version, just changelog, just verify-image [tag]. Details: Architektur.

PostgreSQL und Datenübernahme

Die zehn Updatarr-Domaintabellen und ihre Beziehungen werden durch explizite native SeaORM-Migrationen verwaltet. Historische Migrationen bleiben unverändert; unbekannte Versionen stoppen den Start. Die Legacy-Datenbank wird niemals automatisch migriert. Datenbank-Vertrag, generiertes Schema, offline Import.

PostgreSQL ist die einzige aktivierte Integration. Updatarr bietet keine Redis-/Dragonfly-Integration und keine zusätzlichen Produktionsvarianten an. just schema-diagram erzeugt das Diagramm aus einer isolierten migrierten Testdatenbank, just gate prüft seine Aktualität.

Coverage

just gate, just test und CI führen die vollständigen echten Tests ohne Coverage-Instrumentierung aus. just coverage misst separat während der Entwicklung und zeigt Zusammenfassung sowie fehlende Zeilen im Terminal; just coverage html erzeugt HTML nur auf ausdrücklichen Bedarf. Keine LCOV-/JSON-/Summary-Dateien, Forgejo-Reportartefakte oder Screenshots. Lokale Einrichtung über just setup; Messverfahren und Grenzen.

Hintergrundprozesse und Betriebsinformationen

src/workers.rs komponiert fachliche Jobs über den veröffentlichten Common-Supervisor. Die optionale Dependency-Probe zeigt den vollständigen Weg: begrenzte Verarbeitung, gemeinsame Job-ID, beobachtete Job-Fehler, Readiness und geordneter Shutdown. /metrics liefert HTTP-/Job-Messungen; Request-IDs erscheinen in Response und JSON-Logs. Vertrag und Erweiterungspunkte.