Files
rust-discovery/docs/development.md
T

79 lines
12 KiB
Markdown

# Bauen und Bereitstellen in der Entwicklungsumgebung
Der [Lieferplan](mvp-completion-plan.md) nennt den nächsten Schritt. Für eine Entwicklungskorrektur reicht der direkte Weg zum betroffenen Dienst. Der Agent-Updater ist selbst ein Produktfeature und wird über den Releasekanal geprüft, wenn genau diese Funktion zur Abnahme steht.
## Buildziel wählen
Die Befehle werden im Repository ausgeführt. Der [Buildrunner](../tools/build.py) verwendet den gewählten Git-Commit, die gepinnte Rust-Toolchain und die vorhandenen Docker-Builder. `--plan` zeigt Revision, Zielbinaries und Kommando an. `--ref` akzeptiert einen Commit oder Branch und verwendet standardmäßig `HEAD`. Bei absichtlich geänderten Quellen einen eigenen abgegrenzten Git-Stand wählen, damit fremder WIP im Arbeitsbaum bleiben kann. Der Cargo-Cache wird je Ziel wiederverwendet.
| Ziel | Befehl | Ergebnis |
| --- | --- | --- |
| Linux-Client x86-64 | `python3 tools/build.py linux-x64` | Agent, privilegierter Helper und stabiler Updater |
| Windows-Client x86-64, Entwicklung | `python3 tools/build.py windows-gnu-x64` | Windows-GNU-Agent, SYSTEM-Helper und stabiler Windows-Updater. |
| Server ARM64 vom Notebook | `python3 tools/build.py server-arm64 --ssh` | Überträgt den Runner und ausgewählte Quellen des Git-Commits per geprüftem SSH. Baut Server und Zeitbroker im separaten Bereich `~/rmm-dev-build/server-arm64/` auf dem nativen ARM64-Host. Ausgabe enthält Remote-Pfad und Hashes. |
| Server ARM64 direkt auf einem passenden Linux-Buildhost | `python3 tools/build.py server-arm64` | Serverbinary für API/Gateway und Zeitbroker. Der lokale Modus erwartet Git-Checkout, gepinnten ARM64-Builder, Docker, Python 3, git, tar und rsync. |
| WebUI | `npm --prefix web run build` | TypeScript-Prüfung und Vite-Bundle in `web/dist/`. Im frischen Checkout zuerst `npm --prefix web ci` ausführen. |
| Windows-Binaries nativ mit MSVC | Vorhandenen [MSVC-Runner und Voraussetzungen](../deploy/windows/msvc/README.md) verwenden. | Geplant, nicht ausgeführt. Eigener Preflight und Build auf passendem Windows-Builder. Der GNU-Weg ist für schnelle Iteration auf dem Gast vorgesehen. |
Der lokale Runner gibt den **konkreten Artefaktordner** aus. Unter `devstate/build/<Ziel>/artifacts/<Commit>/<Manifesthash>/` liegen die Binaries und `manifest.json` mit Quellrevision, Zielarchitektur, Builder und SHA-256. Ausgelieferte Binärdateien immer am Hash identifizieren: Zwei Builds aus demselben Commit können unterschiedliche Bytes haben. Ein Build erstellt noch keinen signierten Produktrelease.
## Server und WebUI aus einem geprüften Git-Stand aktivieren
`python3 tools/build.py server-arm64 --ssh --ref REVISION` erzeugt die Binärdatei auf dem Server. Anschließend baut `python3 tools/dev_deploy_server.py --ref REVISION` die passende WebUI, übernimmt die vorhandene Compose-Konfiguration und aktiviert API und Gateway. Der Runner vergleicht die tatsächlich angewendeten SQLx-Prüfsummen mit Git und liest die laufenden Binärhashes und die über TLS ausgelieferte Startseite zurück. Mit `--overlay server.releases.compose.yaml` überträgt und aktiviert der Runner die entsprechende Datei aus derselben Git-Revision. [Deploymentrunner](../tools/dev_deploy_server.py)
Bei einer reinen WebUI-Änderung genügt `python3 tools/dev_deploy_server.py --web-only --ref REVISION`. Für ein schon gebautes Bundle aus dem Arbeitsbaum genügt `python3 tools/dev_deploy_server.py --web-only --web-dist web/dist`. Beide Wege stellen zuerst die Assets und zuletzt die Startseite per SSH bereit. Der Runner vergleicht die per TLS ausgelieferte Startseite mit den übergebenen Bytes. Die Ausgabe enthält den SHA-256 der Startseite und die ID des laufenden API-Containers.
## Vorhandene Dateien direkt bereitstellen
[dev_stage.py](../tools/dev_stage.py) verwendet die vorhandenen gepinnten SSH-Zugänge für `server`, `linux` und `windows`. Der Befehl nimmt beliebig viele benannte Entwicklungsartefakte entgegen, darunter fertige Binaries oder bereits gebaute Webassets. Unter `rmm-dev-stage/<SHA-256>/<Dateiname>` im Profil des SSH-Benutzers verifiziert er die Datei und verwendet vorhandene identische Bytes wieder. Für das Prüfen der Zielpfade genügt `--plan`. [Zugangsprofile und Hostpins](operations-access.md)
Beispiel für ein bereits gebautes Linux-Paar, **geplant, nicht ausgeführt**. `ARTIFACT_DIR` auf den vom Build ausgegebenen Ordner setzen:
```sh
python3 tools/dev_stage.py --plan linux "$ARTIFACT_DIR/rmm-agent" "$ARTIFACT_DIR/rmm-privileged-helper"
python3 tools/dev_stage.py linux "$ARTIFACT_DIR/rmm-agent" "$ARTIFACT_DIR/rmm-privileged-helper"
```
## Aktivierung der bereitgestellten Entwicklungsversion
Nach dem Transfer die laufende Version und ihre Rückmeldung prüfen. Für den Server übernimmt das der Deploymentrunner. Die beiden Entwicklungsgeräte haben eigene Verfahren für den Wechsel einer laufenden Binärdatei.
- **Server.** Den oben angegebenen Deploymentrunner verwenden. Er übernimmt die aktive Compose-Dateikette aus den Containerlabels, bestehende Volumes und Policy-Mounts. [Deploymentaufbau](server-deployment.md)
- **Linux.** Beim Austausch der betroffenen Dienste ihre tatsächlich installierten Artefakte und Rechte feststellen, Ersatz vollständig bereitstellen und Konfiguration, Identität und Journal erhalten. Den Prozesshash, einen neuen Heartbeat und bei geänderter Jobruntime einen regulären Sync zurücklesen. Die früheren [Linux-Wechsel](../deploy/cloud_shared_core_upgrade_v2.py) enthalten wiederverwendbare Prüfungen und setzen konkrete Altfälle voraus.
- **Windows.** Agent und Helper bei einem Paarwechsel koordiniert stoppen, Binärdateien und die an sie gebundenen Metadaten aus derselben Version einsetzen, ACLs und Geräteidentität erhalten und geordnet starten. Prozesshashes und Gerätepräsenz getrennt abfragen. [Vorhandener Paarwechsel](../deploy/windows/Install-DevelopmentPairSuccessor.ps1) · [Zugang und lesende Diensteprüfung](operations-access.md)
Der alte `deploy/dev.py up` richtet eine lokale Compose-Umgebung ein. Der Produktserver liegt auf dem dedizierten Internetserver. Fallbezogene Builder wie `server_build_221.py` sind über ihre damaligen Belege auffindbar.
## Tatsächlich geprüft am 17. November 2026
- `linux-x64` und `windows-gnu-x64` auf dem Entwicklungs-PC aus `a576c10` gebaut, fünf Binaries und beide Manifeste per SHA-256 geprüft. Wiederholte Cargo-Builds aus dem Cache lagen jeweils unter einer Sekunde. Auf dem Windows-Gast liefen bei der Inventur die Hashes seines früheren Installationsbuilds aus demselben Commit.
- `python3 tools/build.py server-arm64 --ssh` auf dem konfigurierten ARM64-Server tatsächlich ausgeführt. Server und Zeitbroker als ELF64/AArch64 nachgelesen, Manifest und Hashes bestätigt. Cargo benötigte beim ersten Lauf 7 min 6 s, beim zweiten 0,52 s. Beide Läufe lieferten identische Bytes. API, Gateway und Datenbank liefen währenddessen weiter.
- WebUI mit den lokal vorhandenen Abhängigkeiten typgeprüft und in ein isoliertes Ausgabeverzeichnis gebaut. Ergebnis: `index.html`, CSS- und JavaScript-Bundle.
- Auf Server, Cloud-Linux und Windows jeweils `python3 tools/dev_stage.py ZIEL rust-toolchain.toml` zweimal ausgeführt. Der erste Aufruf übertrug die Datei und prüfte den Zielhash, der zweite bestätigte die vorhandenen Bytes. Der Test veränderte nur den Stagingbereich. Es wurde kein Dienst aktiviert, Gerät neu aufgenommen oder Produktrelease veröffentlicht. [Build- und Betriebsbelege](evidence/product-audit-20261117.json)
Die früheren Entwicklungsprotokolle einschließlich der alten Notebook-/Reverse-Tunnel-Topologie sind im Git-Stand `a576c10:docs/development.md` erhalten.
## Signierte Agentversion im Entwicklungsmandanten veröffentlichen
Der Buildordner enthält das in der Buildquittung gebundene Agent-/Helperpaar und den stabilen Bootstrap-Updater. Ein Linux-Build benötigt `rmm-agent`, `rmm-privileged-helper` und `rmm-agent-updater`. Auf Windows heißen die Dateien `rmm-agent-windows.exe`, `rmm-helper-windows.exe` und `rmm-updater-windows.exe`. Beim GNU-Entwicklungsbuild den Updater mitbauen. Der Katalog führt Linux GNU, Windows MSVC und Windows GNU als getrennte Ziele. Windows GNU ist auf dem Entwicklungsserver freigeschaltet.
```bash
python3 tools/dev_agent_release.py \
--artifacts "$buildordner" --build-receipt "$buildordner/manifest.json" \
--sequence 1 --version 0.1.0-mvp.1
```
Der Befehl prüft die Buildquittung und überträgt die drei Binärdateien über den gepinnten SSH-Zugang. Auf dem Server signiert ein separater Ed25519-Schlüssel je Plattform das exakte Agent-/Helperpaar. Der Aufruf lädt die Dateien über die authentisierte Management-API und veröffentlicht zuletzt den Envelope. Ein erneuter Aufruf mit derselben Sequenz und denselben Bytes verwendet die gespeicherte Signatur. Für eine geänderte Version die Sequenz erhöhen. Native MSVC-Builds verwenden ihre `result.json` als `--build-receipt`.
Beim ersten Serveraufbau den Befehl zunächst mit `--prepare-only` ausführen. Damit entstehen die Schlüssel, die öffentliche Konfiguration und der Objektspeicher unter `/opt/rust-discovery/devstate/mvp-releases`. Das Compose-Overlay `deploy/server.releases.compose.yaml` bindet nur Konfiguration und Objekte an die Rollen. Der private Schlüssel bleibt auf dem Server. Anschließend API und Gateway mit diesem Overlay aktivieren und den Veröffentlichungsbefehl ohne `--prepare-only` erneut ausführen. Der bei der Einrichtung gespeicherte SHA-256 ist der Ausgangswert für die unten beschriebene kontrollierte Rotation.
## Neue Geräte und Selbstupdate
Im Releasekatalog der WebUI unter **Neues Gerät aufnehmen** einen Einmalcode erzeugen. Die WebUI zeigt die Installationsaufrufe für die veröffentlichten Plattformen. Den Code auf dem neuen Gerät im Prompt eingeben. Nach 15 Minuten oder beim erfolgreichen Enrollment verliert er seine Gültigkeit. Der öffentliche Bootstrap-Origin wird mit `RMM_BOOTSTRAP_ORIGIN` festgelegt. Die Geräteadresse stammt aus der geschützten plattformspezifischen Bootstrapkonfiguration.
Im aktuellen Windows-Entwicklungsmandanten den angebotenen Aufruf mit `-Platform x86_64-pc-windows-gnu` aus der WebUI übernehmen. Windows verwendet den LocalService-Agenten und den separaten Dienst `RmmDiscoveryReleasePull` für die periodische Prüfung.
Auf Linux startet `rmm-discovery-agent.service` als Systemkonto `rmm-discovery` mit eigenem Zustand in `/var/lib/rmm-discovery`. `rmm-discovery-update.timer` prüft nach dem Booten und anschließend alle fünf Minuten den Releasebestand. Die aktive Generation und ein bei fehlgeschlagener Aktivierung gespeicherter Fehler liegen unter `/opt/rust-discovery-client`. Der Lauf berücksichtigt belegte Jobs, verifiziert den signierten Inhalt, schaltet die Generation um und prüft die neue Geräteverbindung. Das Systemjournal von `rmm-discovery-update.service` enthält die Fehlermeldung. Der Linux-Produktinstaller startet den unprivilegierten Agenten. Die Freigabe und gerätespezifische Provisionierung des privilegierten Wartungshelpers bleibt eine eigene Verwaltungshandlung.
Ein geänderter stabiler Bootstrap-Updater wird ausdrücklich je Mandant rotiert. Dazu beim Veröffentlichen des geprüften neuen Builds `--rotate-bootstrap-from <bisheriger SHA-256>` ergänzen. Für den Windows-GNU-Worker mit Skript-/Updatesperre verlangt der signierte Release zusätzlich `--minimum-updater-version 2`. Der Befehl lädt den neuen Worker zunächst über die Katalog-API hoch, vergleicht das gespeicherte Objekt und den bisherigen Mandantenpin und schaltet anschließend auf den neuen Hash um. Bereits ausgestellte Installer können den vorher erhaltenen Hash noch 15 Minuten lang abrufen. Weitere Releases desselben Workerstands verwenden nur `--minimum-updater-version 2`. Bestehende Geräte mit älterer stabiler Prüferdatei verwerfen ein Release, dessen signierte Mindestversion ihre eigene Prüferfähigkeit übersteigt.