Skip to main content

Operations

Documentation Map​

Operations

Zweck​

Diese Datei beschreibt den aktuellen Betriebszustand und die Grenzen des Repositories.

Start​

Kein Dienststart vorhanden. Das Repository wird ueber Git und CI betrieben.

Run​

  • Dokumentation pflegen
  • issue-getriebte Aenderungen umsetzen
  • Linux-CI fuer Mindestvalidierung nutzen
  • abgeschlossene jhf-beam runs als cold data nach TrueNAS offloaden
  • getrennte Docker-Hygiene nur reporting-first und konservativ betreiben
  • repo-eigene Host-Artefakte ueber einen kanonischen Sync-Pfad planen, anwenden und verifizieren
  • standalone nach helpifyr-integrated nur ueber den dokumentierten Adopt-First-Pfad fuer denselben run path ueberfuehren

Verify​

  • Pflichtdateien vorhanden
  • Backlog und Issues konsistent
  • Manifest und README spiegeln denselben Scope
  • compatibility/latest.json zeigt den letzten bekannten single-path Status
  • runs/offloaded/<run-id>.json zeigt archivierte Cold-Data-Ziele fuer offloaded Runs
  • ops/host/evidence/<measurement-id>/measurement.json bildet den konservativen Vorher-/Nachher-Snapshot fuer repo-eigene Host-Rollouts
  • ~/.local/state/jhf-beam/host-artifact-sync-state.json beschreibt den zuletzt installierten repo-eigenen Host-Artefaktstand ueber eine artefaktbezogene artifact_revision
  • maintenance/*.json bilden Inventory, Promotion-Handoff, Live-Feedback und Governance-Baseline maschinenlesbar ab
  • ops/host/verify-ssh-batchmode-contract.sh validiert den env-owned non-interactive SSH-Contract (BatchMode=yes) fuer Linux-Shell-Checks
  • ops/host/verify-live-stack-attachment.sh belegt die Live-Anbindung dieses Repositories als host-bound Operator statt als Container-Runtime
  • scripts/testing/run_beam_stack_oss_inventory_wave.sh erzeugt den stack-weiten OSS-/Runtime-Bestand und den dazugehoerigen Upgrade-Wellenplan
  • ops/host/process-promotion-issue.sh ist der operative Bridge-Pfad fuer Stage 3 und erzeugt bzw. publiziert die strukturierte Rueckmeldung an das Promotion-Issue
  • ops/host/read-openclaw-runtime-readback.sh liefert die contract-relevante OpenClaw-Runtime-Evidence fuer Reload-Mode-, Sandbox- und Delegationssignale
  • der Publish-Schritt bleibt secret-neutral im Repo: GITEA_TOKEN kommt entweder explizit aus der Shell oder als runtime-fallback aus dem bereits laufenden openclaw-gateway, nie aus einer eingecheckten Datei
  • maintenance/check-published-live-feedback.py bildet den repo-seitigen Post-Publish-Verify dafuer, dass genau der erwartete Live-Feedback-Payload in Gitea angekommen ist
  • ~/.local/state/jhf-beam/live-promotions/metrics/stage3-summary.json bildet den aktuellen repo-lokalen Stage-3-Metrik-Snapshot fuer denselben Promotion-State
  • test-results/stack-oss-inventory.live.json und test-results/stack-upgrade-plan.live.json sind die repo-seitigen Artefakte fuer den letzten echten Stack-Vollscan

Stop​

Kein laufender Dienst vorhanden.

Recovery​

  • fehlerhafte Repo-Aenderungen per Git-Revert oder Folge-Commit korrigieren
  • Runner- oder Infra-Probleme dokumentieren, nicht im selben Lauf umbauen

Logs​

  • aktuell relevant sind Git-Historie und CI-Logs in Gitea
  • Host-Offload-Log: ~/.local/state/jhf-beam/offload.log
  • Host-Docker-Hygiene-Log: ~/.local/state/jhf-beam/docker-hygiene.log
  • Run-spezifische Logs: upgrade/openclaw/2026.3.13-to-2026.3.24/runs/<run-id>/logs/
  • integrierte evidence.json enthaelt auch plan_result und bei Plan-Fehlern eine kompakte plan_failure_summary

Monitoring​

  • aktuell nicht vorhanden
  • minimaler Ersatz: CI-Status des Repositories
  • stack-weite OSS-Upgrade-Drift wird repo-owned ueber Inventory + Wave-Plan sichtbar gemacht:
    • maintenance/pull_stack_oss_inventory.py
    • maintenance/generate_stack_upgrade_plan.py
    • maintenance/verify-stack-oss-inventory.py
    • Boundary fuer shared CI dispatch:
      • jhf-beam owned nur repo-lokale CI-Definition und Verify-Pfade in jhf-beam
    • jhf-beam owned nicht die globale Gitea-Runner-Dispatch-Policy, Runner-Registration oder Repo-Onboarding anderer Repositories
    • Blocker mit pending-Checks ohne materialisierten Actions-Task in fremden Repositories sind an den jeweiligen Repo-Owner plus env-/runner-owner zu routen (aktuell JaddaHelpifyr/jhf-loom und JaddaHelpifyr/jhf-openclaw-env)
  • Host-Runtime-Messung fuer Rollouts bleibt kurz und reporting-first:
    • CPU-Snapshot ueber top -b -n1
    • Docker-Ereignisrauschen ueber kurze exec_create-Stichprobe
    • user-level systemd Status fuer offload und docker hygiene
    • lokaler Evidence-Pfad ueber ops/host/measure-rollout-via-ssh.sh
  • letzter verifizierter Host-Rollout-Snapshot am 2026-04-02:
    • CPU idle vor dem Rollout: 0.9%
    • CPU idle nach dem Rollout: 31.8%
    • exec_create in 15s vor dem Rollout: 24
    • exec_create in 15s nach dem Rollout: 25
    • Einordnung: host-weite Signale bleiben verrauscht, weil fremde Container auf demselben Host laufen
  • Maintenance-Metriken werden vorerst als JSON-Baseline definiert:
  • Maintenance-Metriken werden jetzt fuer Stage 3 als JSON-Baseline unter ~/.local/state/jhf-beam/live-promotions/metrics/stage3-summary.json verdichtet:
    • success_rate
    • average_stage_duration
    • rollback_rate
    • drift_frequency
    • failed_promotions_per_week
    • manual_interventions_per_week
    • average_stage2_duration
    • average_stage3_duration

Healthchecks​

  • keine repo-eigenen Docker-Healthchecks vorhanden
  • aktuelle Runtime-Last entsteht nur ueber user-level systemd jobs fuer offload und docker hygiene
  • Standard fuer kuenftige repo-eigene Healthchecks bleibt:
    • kritische Kernservices: 20-30s
    • normale Services: 30s
    • unkritische Services: 60s
    • kein Intervall unter 20s
    • timeout 2-5s
    • retries 3-5
    • start_period 20-60s, nur wenn sinnvoll
  • Services ohne echten Liveness-Bedarf bekommen keinen Healthcheck

Readiness​

  • nicht vorhanden

Typische Fehlerbilder​

  • Pflichtdokumente fehlen oder sind inkonsistent
  • Issue-Status passt nicht zum Backlog
  • Scope wird in der Doku ueberdehnt
  • Offload-Target ist nicht schreibbar und ein Run bleibt als local-retained lokal
  • host-affecting Skripte verweigern unsichere Roots oder Schwellwerte
  • Host-Artefakt-Sync verweigert Ziele ausserhalb von ~/.local/bin und ~/.config/systemd/user
  • source-side capture kann nur den lokalen Terraform-Testzustand bewerten, wenn JHF_DEPLOYMENT_DIR lokal verfuegbar und per terraform output -json lesbar ist
  • host-lokale Ausfuehrung normalisiert <internal-runtime-redacted><internal-runtime-redacted> auf lokale Runtime-Inspektion statt SSH-zu-sich-selbst

Restart- und Recovery-Hinweise​

  • keine Laufzeitprozesse
  • fuer kuenftige Skripte muessen eigene Recovery-Hinweise pro Artefakt dokumentiert werden
  • user-level jhf-beam-offload.timer zieht nur abgeschlossene lokale Runs nach
  • user-level jhf-beam-docker-hygiene.timer ist getrennt und fasst standardmaessig keine Images oder Volumes aktiv an
  • repo-eigener Host-Artefakt-Sync legt Sicherungen unter ~/.local/state/jhf-beam/sync-backups/<timestamp>/ ab
  • beide Host-Jobs laufen mit reduzierter Prioritaet und sind fuer schwaechere Hosts auf geringe Dauerlast ausgelegt
  • Rollout-Messung bleibt read-only und darf keine Host-Konfiguration veraendern

Gate-, Timeout- und Locking-Basis​

Statusfluss:

  • draft
  • verified-stage1
  • verified-stage2
  • promoted
  • live-verified
  • closed

Blockierend:

  • blocked
  • drifted
  • missing-release-evidence

Timeouts:

  • Stage 1: 15 Minuten
  • Stage 2: 45 Minuten
  • Stage 3: 30 Minuten

Retry- und Cooldown-Basis:

  • nach Failure kein erneuter Apply desselben Artefakts auf dasselbe Ziel innerhalb von 30 Minuten ohne explizite Retry-Entscheidung
  • dieselbe Kombination aus artifact_digest + target_environment darf nur resume oder skip sein

Locking:

  • genau ein aktiver Promotion-Flow pro Repo
  • das aktive Promotion-Issue in jhf-deployment ist zugleich der operative Lock
  • stale Locks duerfen nur durch jhf-deployment Owner oder benannte Operatoren geloest werden

Laufzeitabhaengigkeiten​

  • Gitea
  • Linux-basierte Runner
  • /mnt/truenas-container/jhf-beam/runs fuer cold data offload
  • user-level Host-systemd fuer Fallback-Offload und Docker-Hygiene-Timer
  • SSH und SCP fuer den repo-eigenen Host-Artefakt-Sync
  • denselben OpenClaw run path fuer standalone und helpifyr-integrated, ohne Hidden Migration Layer

Betriebliche Grenzen​

  • kein Runtime-Service
  • keine Observability-Endpunkte
  • keine Rollout-Steuerung
  • aktive Runs bleiben lokal
  • Docker runtime bleibt lokal
  • Terraform working dirs bleiben lokal
  • automatische Docker-Loeschungen sind standardmaessig deaktiviert
  • nur die dokumentierte single-path Compatibility-Export-Surface ist stabil lesbar
  • keine repo-eigenen Container-Healthchecks, solange dieses Repository keine eigenen Compose-Stacks betreibt
  • Rollout-Messung ist host-weit nur indikativ; exec_create-Rauschen kann fremde Stacks enthalten
  • Host-Artefakt-Sync fasst nur den dokumentierten Satz aus ops/host/host-artifacts.manifest.tsv an
  • Adopt-First fuer diesen Pfad bedeutet Re-Execution gegen das integrierte Substrate, nicht Volume-, DB- oder Secret-Migration
  • jhf-beam bleibt Live-Host-Operator, aber nicht eigenstaendige Control Plane oder Promotion-Queue
  • Drift-Nachweis fuer OpenClaw-nahe Flows braucht expected vs actual plus gateway.reload.mode
  • das Fehlen eines jhf-beam Containers auf <internal-runtime-redacted> ist kein Incident; relevant sind Host-Checkout, Verify-Skripte und die repo-eigenen user-level Timer

Lizenz​

AGPLv3. Siehe ../LICENSE (LICENSE).

Mehr unter helpifyr.com.