Linux et systemd

L’installateur Linux, introduit dans ATLAS 0.1.298, utilise le même serveur combiné que Docker et l’application HA. Administration et Card Editor fonctionnent ensemble ; les plugins externes restent installables séparément. L’intégration ATLAS Runtime native facultative est également implémentée et vérifiée via un dépôt HACS personnalisé sur Pi 5 et Proxmox.

Prérequis

• Linux avec systemd actif, Node.js 22 ou ultérieur et accès root pour l’installation.
• Un package Linux correspondant à l’architecture CPU, à libc et à l’ABI Node de la cible.
• Trois ports libres : 4176 pour l’application, 4175 et 4174 pour les interfaces internes.
• Assez d’espace pour deux versions du Runtime au moins et les sauvegardes de données.

La construction prend en charge AMD64 et ARM64 et utilise Debian Bookworm/glibc. Un package Alpine/musl n’est pas interchangeable. La préparation native est également vérifiée sous Raspberry Pi OS / Debian 13.7 Trixie avec glibc sur un Raspberry Pi 4 (aarch64, 4 Go de RAM).

État des vérifications au 15.10.2026 : Debian 12 AMD64 en LXC et le Pi 4 natif avec Node.js 22.23.3 et ATLAS 0.1.303/0.1.304. Sur le Pi, les 17 tests de l’installateur, l’installation, la mise à jour, le retour à la version précédente, la sauvegarde, le redémarrage du service et la récupération automatique après une mise à jour défaillante réussissent. Les données synthétiques de plugin/projet et la configuration sont conservées. Les ports restaient locaux lors de cette première vérification. Les tests suivants valident accès LAN sur4176, véritable redémarrage du Pi 4, démarrage automatique et récupération persistante de la connexion HA depuis 0.1.305. Les autres distributions et matériels nécessitent une qualification séparée.

L’installateur utilise le compte système atlas. Il refuse un compte existant avec un autre répertoire personnel ou groupe principal et ne reprend pas silencieusement une autre installation ATLAS.

Préparer un package

Sur un hôte Linux avec les dépendances de construction habituelles :

corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm test:linux
pnpm linux:prepare

output/linux-runtime contient l’application compilée, les dépendances, le plugin de référence et atlas-linux-runtime.json. Un répertoire de sortie existant n’est pas écrasé.

Autre méthode, avec Docker hors du LXC cible :

docker build -f packaging/linux/Dockerfile --target export --output type=local,dest=output/linux-export .

L’export comprend une archive, un manifeste, des sommes de contrôle et le binaire Node avec sa licence provenant de l’image officielle Node. Vérifiez la provenance et les SHA-256 avant utilisation. Utilisez une installation Node compatible ; ne remplacez pas une version existante sans vérification. Conservez les liens symboliques relatifs de node_modules pendant le transfert.

Installation

Avec un package vérifié et extrait et une version Node compatible :

sudo node /chemin/linux-runtime/scripts/atlas-linux-installer.mjs install --source /chemin/linux-runtime
sudo systemctl status atlas
curl --fail http://127.0.0.1:4176/health

L’installateur valide le package, l’architecture et les modules natifs, crée une sauvegarde, installe une version séparée et démarre le service. La vérification exige les deux interfaces, la version attendue et la cible de distribution Linux. Aucun service tiers n’est arrêté pour libérer un port occupé.

Données persistantes

Chemin	Contenu
/opt/atlas/releases/	Versions du Runtime séparées.
/opt/atlas/current	Lien symbolique vers la version actuelle.
/opt/atlas/installation.json	État de l’installation et version précédente.
/var/lib/atlas/	Données, plugins, identité, historique de fichiers et corbeille.
/etc/atlas/atlas.env	Configuration protégée, conservée lors des mises à jour.
/etc/systemd/system/atlas.service	Service géré.
/etc/systemd/system/atlas.service.d/	Compléments systemd locaux.
/var/backups/atlas/	Sauvegardes horodatées.

Les projets de l’éditeur et une partie de l’Administration résident dans le navigateur. Exportez-les séparément depuis leurs interfaces : une sauvegarde serveur ne capture pas le stockage du navigateur. Conservez l’adresse du navigateur, le chemin des données et l’identité de l’installation lors des mises à jour pour préserver les identifiants chiffrés liés localement. Les données Docker/HA ne sont pas migrées silencieusement.

Mise à jour et retour à la version précédente

sudo node /chemin/nouveau-package/scripts/atlas-linux-installer.mjs update --source /chemin/nouveau-package
sudo node /opt/atlas/current/scripts/atlas-linux-installer.mjs rollback

ATLAS est arrêté et sauvegardé avant la mise à jour. Le fichier d’environnement, les plugins installés et les compléments systemd sont conservés. Le lien actuel change de Runtime. En cas d’échec, le Runtime précédent est rétabli. Une installation précédemment arrêtée reste arrêtée après vérification ; l’activation au démarrage est conservée.

Le retour change le programme, pas les données utilisateur. De futures migrations de données nécessitent une vérification de rétrocompatibilité distincte. Les anciennes versions et sauvegardes ne sont pas supprimées automatiquement. Utilisez systemctl edit atlas pour vos compléments au lieu de modifier directement le service géré.

Sauvegarde et restauration

sudo node /opt/atlas/current/scripts/atlas-linux-installer.mjs backup
sudo node /opt/atlas/current/scripts/atlas-linux-installer.mjs status

La sauvegarde à service arrêté comprend données, configuration, service, compléments et manifeste d’installation. Un service auparavant actif redémarre ensuite. Les sauvegardes sont réservées à root et peuvent contenir des identifiants. Sauvegardez séparément les chemins externes, clés SSH hors des données ATLAS et projets du navigateur.

Pour restaurer manuellement, arrêtez ATLAS, sauvegardez à nouveau l’état actuel et restaurez les données/configurations sélectionnées aux chemins d’origine avec les propriétaires appropriés. Conservez l’identité de l’installation, préparez le Runtime correspondant puis vérifiez /health. Copier la sauvegarde sur une autre installation ne déverrouille pas ses secrets locaux. Un snapshot VM/LXC avant installation permet aussi de restaurer l’hôte entier.

Réseau et plugins

Depuis ATLAS 0.1.305, l’enregistrement des paramètres de l’administration Linux conserve aussi la connexion HA mémorisée sur le serveur avec AES-GCM. La restauration après redémarrage du service ou de l’hôte fonctionne donc en HTTP sur le réseau local sans Web Crypto dans le navigateur. Après la mise à jour, saisissez une fois le jeton existant dans l’administration puis enregistrez ; les versions précédentes peuvent l’avoir conservé uniquement en mémoire.

Le fichier chiffré admin-connection.enc.json et la clé privée admin-connection.enc.json.key se trouvent à côté de admin-device.json dans le répertoire privé des données ATLAS. Les fichiers utilisent le mode Linux 0600 ; les données sont liées à l’identité de l’installation. Une sauvegarde complète doit conserver ces trois fichiers et rester confidentielle. Copier uniquement le répertoire du programme ou l’export du navigateur n’inclut pas cette clé. « Oublier le jeton » retire aussi le jeton HA mémorisé du serveur. Des données chiffrées illisibles ne sont pas remplacées automatiquement.

Toutes les interfaces utilisent loopback par défaut ; Terminal est désactivé. L’installateur n’ouvre aucun pare-feu. L’administrateur peut modifier délibérément ATLAS_APP_HOST pour le LAN et limiter cet accès ; les ports internes restent locaux. L’Administration ne doit pas être exposée sans protection sur Internet.

File Studio nécessite des permissions Linux correspondant aux chemins approuvés. Les fichiers HA situés sur un autre hôte ne sont pas montés automatiquement. SSH et Oh My Posh pour le Terminal externe sont des prérequis supplémentaires facultatifs, non inclus dans le package Linux.

Périmètre des tests

Les régressions utilisent des données temporaires pour vérifier conservation, sauvegarde, échec de mise à jour, retour de version, état du service, installation sans écrasement et validation des chemins/ABI. Un test conteneur avec service simulé ne remplace pas un test systemd natif. Les preuves natives et plateformes ouvertes figurent dans l’état du développement.