#96 - FEAT: Auto-update agent — mode natif Linux/Windows (installateur + vérification de version) - nonobis/Heimdall

nonobis commented

2026-08-12 10:33:05 +02:00

Owner

Contexte

Les agents Heimdall n'ont aucun mécanisme de mise à jour automatique. Décision du chef de projet (12/08/2026) : s'aligner sur le modèle Pangolin — le central vérifie la version (endpoint serveur avec cache, façon getNewtVersion.ts), l'agent télécharge et s'auto-update avec contrôle par site.

Modèle Pangolin retenu (fosrl/pangolin, étudié le 12/08/2026)

Le serveur central interroge l'API des releases (server/routers/newt/getNewtVersion.ts) : fetch repos/fosrl/newt/releases, cache 1 h + stale-while-revalidate, renvoie { version, assets: { plateforme: { url, sha256 } } } (digests = champ digest de l'API).
L'agent ne tape pas l'API releases directement : il récupère la version dispo auprès du central.
Auto-update contrôlable : sites.autoUpdateEnabled + override global par org (settingsEnableGlobalNewtAutoUpdate) — l'org peut forcer, le site peut surcharger (updateSite.ts).
UI : ProductUpdates.tsx compare env.app.version à la dernière dispo (semver gt), cloche/badge de notification.

État actuel Heimdall

Aucun installateur natif, aucune publication de binaires (voir #95).
L'agent se connecte déjà au central (register + heartbeat + SignalR) → le canal existe.
Version agent codée en dur 1.0.0 (voir #95) ; AgentDetail.razor affiche déjà _agent.Version.

À faire

Côté central — endpoint de version (façon getNewtVersion.ts) :
- GET /api/updates/latest (policy agent ou admin) qui fetch l'API Forgejo repos/nonobis/Heimdall/releases/latest (token de lecture ou public), cache 1 h + stale-while-revalidate, renvoie { version, assets: { linux-x64: { url, sha256 }, linux-arm64: {...}, win-x64: {...} } } ;
- en cas d'échec réseau : renvoie la dernière valeur en cache (jamais d'erreur bloquante).
Côté agent — AgentUpdateService :
- au démarrage puis toutes les 12 h : GET /api/updates/latest (via le canal d'auth agent existant, X-API-Key) ;
- compare semver (version runtime via InformationalVersion, voir #95) → si nouvelle version : télécharge le binaire de sa plateforme, vérifie sha256, remplacement atomique (binaire neuf + rename), redémarrage du service (systemd Restart=on-failure / service Windows) ;
- rollback si échec de démarrage après update ; journalisation complète (logs agent existants) ;
- pas d'update en pleine capture : drain propre.
Contrôle d'auto-update par site (façon Pangolin) :
- champ AutoUpdateEnabled sur l'entité Site (+ réglage global dans Settings) ; le central inclut la décision dans la config pushée à l'agent (GET /api/settings/agent/{id}, comme les autres settings) ;
- si activé → l'agent s'update automatiquement ; sinon → l'UI propose le bouton « Mettre à jour » (déclenchement manuel).
UI :
- AgentDetail.razor : version courante + version dispo + badge « mise à jour disponible » (comparaison semver, façon ProductUpdates) + bouton « Mettre à jour » ;
- paramètre « auto-update » dans le formulaire Site (et/ou settings globaux).
Installateur natif :
- install/install-agent.sh (Linux : détection OS/arch, téléchargement, systemd unit) + install/install-agent.ps1 (Windows : service) ;
- le script d'install sert aussi d'auto-update (pattern get-installer.sh de Pangolin : télécharge la dernière version et réinstalle par-dessus).
Sécurité : sha256 obligatoire, TLS, jamais d'update en cours de capture.

Critères d'acceptation

Un agent Linux systemd se met à jour automatiquement (si auto-update activé sur son site) ou manuellement depuis l'UI, avec vérification sha256.
Un agent Windows se met à jour (service redémarré).
Échec de téléchargement/checksum → l'agent reste sur sa version et journalise l'erreur (logs agents visibles au central).
L'UI montre version courante + version dispo + état de l'auto-update.

Fichiers concernés

src/Heimdall.Web/Controllers/UpdatesController.cs (nouveau, endpoint /api/updates/latest)
src/Heimdall.Agent/Services/AgentUpdateService.cs (nouveau)
src/Heimdall.Agent/AgentOptions.cs (UpdateCheckIntervalHours)
src/Heimdall.Domain/Entities/Site.cs (AutoUpdateEnabled + migration)
src/Heimdall.Web/Components/Pages/AgentDetail.razor (section version/update)
install/install-agent.sh + install/install-agent.ps1 (nouveaux)

Maquette

Lien Penpot : nonobis-design-system › page agents

Détails / composants MudBlazor (README)
Statut : maquette appliquée dans Penpot ✓

Description

Onglet « Mise à jour » de la fiche agent (mode natif) : version installée vs disponible, bouton « Mettre à jour vers vX.Y.Z », statut (À jour / Mise à jour disponible / Redémarr

Maquette

Lien Penpot : nonobis-design-system › page agents

Détails / composants MudBlazor (README)
Statut : maquette appliquée dans Penpot ✓

## Contexte Les agents Heimdall n'ont aucun mécanisme de mise à jour automatique. **Décision du chef de projet (12/08/2026) : s'aligner sur le modèle Pangolin** — le central vérifie la version (endpoint serveur avec cache, façon `getNewtVersion.ts`), l'agent télécharge et s'auto-update avec contrôle par site. ## Modèle Pangolin retenu (fosrl/pangolin, étudié le 12/08/2026) - **Le serveur central interroge l'API des releases** (`server/routers/newt/getNewtVersion.ts`) : fetch `repos/fosrl/newt/releases`, cache 1 h + stale-while-revalidate, renvoie `{ version, assets: { plateforme: { url, sha256 } } }` (digests = champ `digest` de l'API). - **L'agent ne tape pas l'API releases directement** : il récupère la version dispo auprès du central. - **Auto-update contrôlable** : `sites.autoUpdateEnabled` + override global par org (`settingsEnableGlobalNewtAutoUpdate`) — l'org peut forcer, le site peut surcharger (`updateSite.ts`). - **UI** : `ProductUpdates.tsx` compare `env.app.version` à la dernière dispo (semver `gt`), cloche/badge de notification. ## État actuel Heimdall - Aucun installateur natif, aucune publication de binaires (voir #95). - L'agent se connecte déjà au central (register + heartbeat + SignalR) → le canal existe. - Version agent codée en dur `1.0.0` (voir #95) ; `AgentDetail.razor` affiche déjà `_agent.Version`. ## À faire 1. **Côté central — endpoint de version (façon `getNewtVersion.ts`)** : - `GET /api/updates/latest` (policy agent ou admin) qui fetch l'API Forgejo `repos/nonobis/Heimdall/releases/latest` (token de lecture ou public), **cache 1 h + stale-while-revalidate**, renvoie `{ version, assets: { linux-x64: { url, sha256 }, linux-arm64: {...}, win-x64: {...} } }` ; - en cas d'échec réseau : renvoie la dernière valeur en cache (jamais d'erreur bloquante). 2. **Côté agent — `AgentUpdateService`** : - au démarrage puis toutes les 12 h : `GET /api/updates/latest` (via le canal d'auth agent existant, X-API-Key) ; - compare semver (version runtime via `InformationalVersion`, voir #95) → si nouvelle version : télécharge le binaire de sa plateforme, **vérifie sha256**, remplacement atomique (binaire neuf + `rename`), redémarrage du service (systemd `Restart=on-failure` / service Windows) ; - rollback si échec de démarrage après update ; journalisation complète (logs agent existants) ; - pas d'update en pleine capture : drain propre. 3. **Contrôle d'auto-update par site (façon Pangolin)** : - champ `AutoUpdateEnabled` sur l'entité Site (+ réglage global dans Settings) ; le central inclut la décision dans la config pushée à l'agent (`GET /api/settings/agent/{id}`, comme les autres settings) ; - si activé → l'agent s'update automatiquement ; sinon → l'UI propose le bouton « Mettre à jour » (déclenchement manuel). 4. **UI** : - `AgentDetail.razor` : version courante + version dispo + badge « mise à jour disponible » (comparaison semver, façon ProductUpdates) + bouton « Mettre à jour » ; - paramètre « auto-update » dans le formulaire Site (et/ou settings globaux). 5. **Installateur natif** : - `install/install-agent.sh` (Linux : détection OS/arch, téléchargement, systemd unit) + `install/install-agent.ps1` (Windows : service) ; - le script d'install sert aussi d'auto-update (pattern `get-installer.sh` de Pangolin : télécharge la dernière version et réinstalle par-dessus). 6. **Sécurité** : sha256 obligatoire, TLS, jamais d'update en cours de capture. ## Critères d'acceptation - Un agent Linux systemd se met à jour automatiquement (si auto-update activé sur son site) ou manuellement depuis l'UI, avec vérification sha256. - Un agent Windows se met à jour (service redémarré). - Échec de téléchargement/checksum → l'agent reste sur sa version et journalise l'erreur (logs agents visibles au central). - L'UI montre version courante + version dispo + état de l'auto-update. ## Fichiers concernés - `src/Heimdall.Web/Controllers/UpdatesController.cs` (nouveau, endpoint /api/updates/latest) - `src/Heimdall.Agent/Services/AgentUpdateService.cs` (nouveau) - `src/Heimdall.Agent/AgentOptions.cs` (`UpdateCheckIntervalHours`) - `src/Heimdall.Domain/Entities/Site.cs` (`AutoUpdateEnabled` + migration) - `src/Heimdall.Web/Components/Pages/AgentDetail.razor` (section version/update) - `install/install-agent.sh` + `install/install-agent.ps1` (nouveaux) --- --- ## Maquette - **Lien Penpot** : [nonobis-design-system › page agents](https://penpot.tordais.cc/?page=127dfd1c-12b5-80f7-8008-79c6fdaf09f4) ![Maquette](https://forgejo.tordais.cc/attachments/b3041825-8a38-40cd-a480-50350d0670d3) - [Détails / composants MudBlazor (README)](https://forgejo.tordais.cc/attachments/c79d4512-8a64-4eba-b471-227e0f6ae6bd) - Statut : maquette appliquée dans Penpot ✓ ## Description Onglet « Mise à jour » de la fiche agent (mode natif) : version installée vs disponible, bouton « Mettre à jour vers vX.Y.Z », statut (À jour / Mise à jour disponible / Redémarr --- ## Maquette - **Lien Penpot** : [nonobis-design-system › page agents](https://penpot.tordais.cc/?page=127dfd1c-12b5-80f7-8008-79c6fdaf09f4) ![Maquette](https://forgejo.tordais.cc/attachments/b3041825-8a38-40cd-a480-50350d0670d3) - [Détails / composants MudBlazor (README)](https://forgejo.tordais.cc/attachments/c79d4512-8a64-4eba-b471-227e0f6ae6bd) - Statut : maquette appliquée dans Penpot ✓

README.md

1.6 KiB

maquette.png

133 KiB

nonobis added the

feature

priority-high

labels

2026-08-12 10:33:05 +02:00

nonobis commented

2026-08-12 10:37:47 +02:00

Author

Owner

Décision chef de projet (12/08/2026) : aligné sur le modèle Pangolin — le central expose la version (cache 1h + stale-while-revalidate), l'agent télécharge/vérifie sha256, contrôle d'auto-update par site.

nonobis referenced this issue

2026-08-12 10:37:47 +02:00

FEAT: Auto-update agent — mode Docker (images taguées + mise à jour propre) #97

nonobis referenced this issue

2026-08-12 11:15:35 +02:00

FEAT: Release automatique Heimdall — GitVersion double central/agent #98

nonobis referenced this issue

2026-08-12 11:15:36 +02:00

FEAT: Publication de l'image agent + binaires natifs en release #100

nonobis referenced this issue from a commit

2026-08-12 11:39:22 +02:00

feat(release): GitVersion double central/agent + release notes auto + sécurité CI (Fixes #98 #99 #102, Refs #95 #96 #97 #103)

nonobis referenced this issue from a commit

2026-08-12 19:17:20 +02:00

feat(release): GitVersion double central/agent + release notes auto + sécurité CI (Fixes #98 #99 #102, Refs #95 #96 #97 #103)

nonobis commented

2026-08-14 10:53:44 +02:00

Author

Owner

Maquette the-designer intégrée (14/08/2026) :

Aperçu (PNG) : https://forgejo.tordais.cc/attachments/b3041825-8a38-40cd-a480-50350d0670d3
Détails / composants MudBlazor (README) : https://forgejo.tordais.cc/attachments/c79d4512-8a64-4eba-b471-227e0f6ae6bd
Statut : application Penpot différée (plugin MCP non connecté) — maquette locale consultable

Maquette the-designer intégrée (14/08/2026) : - Aperçu (PNG) : https://forgejo.tordais.cc/attachments/b3041825-8a38-40cd-a480-50350d0670d3 - Détails / composants MudBlazor (README) : https://forgejo.tordais.cc/attachments/c79d4512-8a64-4eba-b471-227e0f6ae6bd - Statut : application Penpot différée (plugin MCP non connecté) — maquette locale consultable

nonobis added the

design

label

2026-08-14 10:59:40 +02:00

nonobis referenced this issue from a commit

2026-08-27 09:16:36 +02:00

feat(agent): expose assembly version via GET /api/version

nonobis referenced this issue

2026-08-27 09:16:52 +02:00

feat(agent): expose assembly version via GET /api/version #171

nonobis referenced this issue from a commit

2026-08-27 16:37:00 +02:00