Variables d'environnement : répertoires de projet et de données

Les variables de Variables d'environnement sont des valeurs : un port, une URL, une chaîne de connexion. Les quatre traitées ici sont des chemins, et ce sont celles dont un processus superviseur a besoin : l'application de bureau Sovrium, une unité systemd, une étape de CI. Toutes sont optionnelles. Non définies, elles se résolvent sur le répertoire de travail, ce que veut quelqu'un qui tape sovrium start dans le dossier de son projet.

Exécution sous un superviseur

Un superviseur sait quel dossier contient l'application, mais ne choisit pas le répertoire de travail depuis lequel le binaire est lancé. Ces quatre variables lui permettent de le dire sans cd. Toutes relèvent de l'environnement, jamais du schéma : rien de la façon dont une application est supervisée n'entre dans AppSchema, si bien qu'une configuration rédigée sous un superviseur s'exécute telle quelle dans Docker, sur un serveur et en CI.

Le répertoire de projet

SOVRIUM_PROJECT_DIR=/srv/contact-book sovrium start

Sovrium résout par rapport à ce répertoire ; il ne s'y déplace jamais par chdir. Un process.chdir() serait une mutation globale au processus, qui relogerait d'un coup et en silence tous les autres chemins relatifs — un argument de configuration relatif, un SOVRIUM_PUBLIC_DIR relatif — et sa justesse dépendrait de l'ordre dans lequel ceux-ci se trouvent lus.

Trois conséquences en découlent, et chacune est le but recherché :

Un chemin que vous passez l'emporte toujours. SOVRIUM_PROJECT_DIR déplace l'endroit où start et build découvrent une configuration quand vous n'en nommez aucune. sovrium start ./other.yaml charge ./other.yaml relativement au répertoire de travail exactement comme avant, et il en va de même pour APP_SCHEMA_FILE et APP_SCHEMA.

SOVRIUM_CONFIG_FILE nomme un fichier dans la racine, pas un chemin qui en sort. Elle remplace le sondage des candidats par un fichier nommé, parce que nommer staging.yaml désigne ce fichier-là et qu'un repli sur app.yaml démarrerait quelque chose que vous n'avez pas demandé. Une valeur qui se résout hors du répertoire de projet est refusée avant la moindre lecture de fichier :

$ SOVRIUM_PROJECT_DIR=/srv/app SOVRIUM_CONFIG_FILE=../secrets.yaml sovrium start
Error: SOVRIUM_CONFIG_FILE resolves outside the project directory

  SOVRIUM_CONFIG_FILE: ../secrets.yaml
  Project directory:   /srv/app

It names a config file within the project directory, so it must stay inside it.
To run a config elsewhere, point SOVRIUM_PROJECT_DIR at its folder.

Tout le graphe de configuration est enfermé dans la racine — mais seulement si vous en définissez une. Un $ref qui en sort est refusé avant même l'ouverture du fichier référencé : une référence refusée ne révèle donc pas jusqu'à son existence.

$ SOVRIUM_PROJECT_DIR=/srv/app sovrium start
Using app.yaml (auto-discovered)
Error: Failed to parse YAML file: /srv/app/app.yaml

Details: $ref resolves outside the project directory: /srv/shared/tables.yaml
The project directory is /srv/app, and the whole config graph must stay inside it.

Cette prison n'existe que là où quelque chose l'a demandée. Non définie, la racine de projet retombe sur le répertoire de travail : c'est le bon défaut pour résoudre un chemin et le mauvais pour le confiner, car une configuration légitimement chargée d'ailleurs — sovrium start ../other/app.yaml — tire aussi des $ref d'ailleurs, et enfermer contre un défaut implicite les refuserait tous. Confier un dossier, c'est déclarer que ce dossier est tout ce que le moteur a le droit de lire.

Arrêt sur fin de fichier

Windows n'a pas de SIGTERM : un superviseur n'y dispose d'aucun moyen portable de demander à un enfant de s'arrêter. Fermer l'entrée standard de l'enfant en est l'équivalent portable, et SOVRIUM_SHUTDOWN_ON_STDIN_CLOSE=1 en fait une demande d'arrêt :

23:19:30 [server] stdin closed — stopping
23:19:30 [server] stopped

C'est l'arrêt gracieux qu'exécute un signal — le fichier de verrou est retiré, les requêtes en cours se vident, le processus sort en 0 — si bien qu'un arrêt sur fin de fichier est indiscernable d'un arrêt sur signal pour qui lit ensuite le code de sortie ou le fichier de verrou. Elle ajoute un déclencheur sans en remplacer aucun : SIGINT et SIGTERM continuent de fonctionner exactement comme aujourd'hui.

L'option se demande, et elle continue de se demander. Un serveur est couramment lancé avec l'entrée standard déjà fermée — nohup, une unité systemd, une étape de CI, sovrium start & — et un gestionnaire de fin de fichier inconditionnel tuerait chacun d'eux à l'instant de son démarrage. Ne la définissez que depuis un superviseur qui tient l'entrée standard ouverte aussi longtemps qu'il veut le serveur vivant.

Répertoire de données

Les artefacts d'exécution vivent sous un répertoire unique, pour qu'une racine de projet neuve reste propre.

.sovrium/
  database.db    # SQLite par défaut — DATABASE_URL remplace
  encryption-key # secret racine propre à l'installation — SOVRIUM_ENCRYPTION_KEY remplace
  lock           # PID du serveur + empreinte de config — SOVRIUM_LOCK_DIR remplace
  storage/       # fichiers téléversés en local — STORAGE_LOCAL_DIRECTORY remplace

SOVRIUM_DATA_DIR ne déplace que l'emplacement de repli. Chaque artefact garde sa propre variable de remplacement, et celle-ci l'emporte toujours. L'URL de la base de données est traitée sur Variables d'environnement, le répertoire de stockage sur Variables d'environnement : services.

Pages connexes

• Variables d'environnement — l'application, le serveur, la base de données et les deux secrets.
• Variables d'environnement : services — stockage, IA, e-mail, MCP, éco, observabilité.
• Fichiers de configuration — les formats et l'ordre dans lequel une commande cherche une configuration.
• Administration et maintenance — ce que SOVRIUM_INSTALL_METHOD=desktop change pour sovrium update.