Variables d'environnement

Comment poser une variable, où elle atterrit, à quel moment elle agit, et ce que la plateforme en rend. C'est le sujet qui coince le plus souvent, parce que deux moments très différents portent le même nom.

La distinction qui explique tout le reste

Une variable peut être nécessaire à deux moments, et ce ne sont pas les mêmes fichiers qui les servent.

Moment	Fichier écrit par Iridflow	Ce qui le lit	Prise d'effet
Au démarrage du conteneur	docker-compose.override.yml	votre application, une fois lancée	immédiate, le conteneur est relancé
Pendant la construction	.env	docker compose, puis `docker build`	au prochain `deploy_site`

Pourquoi deux fichiers ? Parce qu'un bloc environment: de compose n'agit qu'au démarrage du conteneur. Une application qui vérifie ses variables au chargement de ses modules, ce que font beaucoup de projets Next.js, échoue pendant la construction, c'est-à-dire bien avant qu'un conteneur ne démarre. Le seul chemin qui atteint la construction est un fichier .env que compose lit pour interpoler le compose, et dont les valeurs alimentent des arguments de construction.

Attention

Seules les clés préfixées IRIDFLOW_ sont écrites dans le .env, et c'est délibéré : un argument de construction reste lisible dans les couches de l'image, que docker history affiche à quiconque la récupère. Vos secrets applicatifs restent dans l'override, hors de portée de la construction.

« Je veux TOTO=TATA », concrètement

C'est la question la plus posée, et elle a trois réponses selon le moment où votre code a besoin de la variable. Dans aucune des trois vous n'écrivez un fichier.

Votre besoin	Ce que vous posez	Ensuite
L'application lit `TOTO` quand elle tourne. Le cas courant.	nom `TOTO`, valeur `TATA`	rien, le site est relancé
`TOTO` est exigée pendant la construction	nom `IRIDFLOW_BUILD_ENV`, valeur `TOTO=TATA`	`deploy_site`, obligatoire
Les deux	les deux lignes ci-dessus	`deploy_site`

Ce que vous obtenez, et ce que vous n'obtenez pas

Posez TOTO = TATA et vous obtenez ceci dans l'override, qui met la variable dans l'environnement du conteneur :

// docker-compose.override.yml
services:
  web:
    environment:
      TOTO: "TATA"

Vous n'obtenez pas un fichier .env contenant TOTO=TATA. Et si vous ajoutez IRIDFLOW_BUILD_ENV = TOTO=TATA, le .env généré contient la ligne enveloppante, pas votre variable :

// .env généré par Iridflow
# Genere par Iridflow (set_site_env). Lu par docker compose pour
# interpoler le compose. Ne pas editer a la main.
IRIDFLOW_BUILD_ENV="TOTO=TATA"

C'est compose qui déplie cette ligne et pose TOTO dans l'environnement de la construction. Vérifié : un test [ "$TOTO" = "TATA" ] placé en commande préalable passe quand la variable est là, et fait échouer la construction quand elle n'y est pas.

Note

Il n'y a aucun fichier .env dans votre conteneur. Celui qu'Iridflow génère vit à côté du compose, sur la machine, et le .dockerignore du site l'exclut explicitement de l'image. Vos variables arrivent par l'environnement du processus, pas par un fichier.

Si votre code utilise dotenv

Il continue de fonctionner, et c'est voulu : dotenv ne remplace jamais une variable déjà présente dans l'environnement. process.env.TOTO vaut donc TATA, que le fichier existe ou non.

Le seul cas qui ne marche pas est une application qui lit le fichier elle-même, par exemple pour en tirer la liste de ses clés. Monter un vrai .env dans le conteneur n'est pas prévu aujourd'hui : la sortie est de commiter un .env d'exemple dans votre dépôt, l'environnement l'emportant ensuite sur son contenu.

Poser une variable

Depuis l'interface

Sur la fiche d'un site, le bloc Variables d'environnement a deux zones, une par moment.

Variables du site : la liste des noms posés, l'ajout d'une variable à la fois, et un collage de fichier .env entier. Le collage envoie tout en un seul appel, donc un seul redémarrage, là où l'ajout unitaire en provoque un par variable.
Variables de construction : la liste des noms déjà posés, et une zone au format .env qui remplace l'ensemble. Le remplacement est le seul mode possible, parce que les valeurs ne sont jamais relues : elles ne peuvent donc pas être complétées une par une. Coller un texte vide retire le lot.

La valeur n'est jamais réaffichée après coup, y compris à vous. Pour la changer, reposez la variable avec la nouvelle valeur.

Astuce

Le format attendu dans les deux zones est celui de votre fichier : une ligne CLE=VALEUR par variable. Les commentaires, les lignes vides, le préfixe export et les valeurs entre guillemets sont acceptés. Si une ligne n'est pas de la forme attendue, rien n'est posé et la ligne fautive est nommée : il vaut mieux ne rien poser que la moitié.

L'avertissement sur la fiche du site

Si une variable porte un nom que les cadriciels inlinent à la construction, c'est-à-dire préfixé PUBLIC_, VITE_, NEXT_PUBLIC_, NUXT_PUBLIC_, REACT_APP_, GATSBY_ ou VUE_APP_, et qu'elle n'est posée que du côté démarrage, la fiche du site vous le signale. Elle vaudrait undefined dans le site construit, et rien d'autre ne vous le dirait. L'avertissement vient du serveur, donc get_site le rend aussi, dans un champ avertissements.

Depuis le MCP ou l'API

// MCP
set_site_env({
  site_id: "site_xxxx",
  env: {
    DATABASE_URL: "postgres://...",
    STRIPE_KEY: "sk_live_...",
  },
})

Deux options changent le comportement :

Une valeur vide retire la variable. { ANCIENNE: "" } la supprime. Sans cela il n'y aurait aucun moyen d'en enlever une sans tout remplacer.
remplacer: true remplace l'ensemble au lieu de fusionner. Par défaut, ce que vous passez s'ajoute à ce qui existe.

Ce que la réponse vous dit

Champ	Ce qu'il signifie
env_keys	tous les noms posés sur le site, après fusion
variables_injectees	tout ce qui se retrouve dans l'override : vos variables et celles des bases attachées
retirees	les noms que cet appel a supprimés
compose_up_ok	à regarder : la variable peut être enregistrée alors que le site n'a pas redémarré pour la lire
effet_differe	présent dès qu'une clé `IRIDFLOW_` est posée : elle attend un déploiement

Les quatre réglages de construction

Ce sont les seules clés préfixées IRIDFLOW_ que la plateforme interprète. Elles se posent comme les autres, par set_site_env, et demandent un deploy_site pour prendre effet. Deux par famille de runtime.

Variable	Runtimes	À quoi elle sert
IRIDFLOW_PREBUILD_CMD	nextjs, node-generic	Une commande entre l'installation et la construction : `prisma generate`, un codegen GraphQL, une génération de types. Laissée vide, un `prisma/schema.prisma` présent dans le dépôt déclenche à lui seul la génération du client.
IRIDFLOW_BUILD_ENV	nextjs, node-generic	Les variables dont la construction a besoin, sous la forme `CLE=VALEUR;CLE2=VALEUR2`.
IRIDFLOW_BUILD_CMD	frontend-static	Remplace `npm run build` quand la détection se trompe.
IRIDFLOW_OUTPUT_DIR	frontend-static	Le répertoire produit, quand il n'est ni `dist/`, ni `build/`, ni `out/`. C'est cette variable que réclame le message « build output introuvable ».

Écrire une valeur de IRIDFLOW_BUILD_ENV

// exemple
set_site_env({
  site_id: "site_xxxx",
  env: {
    IRIDFLOW_BUILD_ENV: 'NEXT_PUBLIC_TITRE=Mon site;DATABASE_URL=postgres://factice',
  },
})
// puis, obligatoirement :
deploy_site({ site_id: "site_xxxx" })

Le point-virgule sépare les entrées. C'est le seul caractère interdit dans une valeur.
Une valeur peut contenir des espaces, des guillemets, des dollars et des antislashs : elle est posée telle quelle, sans repasser par l'interpréteur.
Une entrée qui n'est pas de la forme CLE=VALEUR est ignorée, et le journal de construction la nomme au lieu de la laisser disparaître.

Attention

N'y mettez pas de vrai secret. Une valeur de façade suffit quand le module vérifie seulement la présence de la variable. La vraie valeur se pose sans préfixe, et n'atteint alors que le conteneur au démarrage.

Les variables d'une base attachée

Attacher une base injecte ses identifiants sans que vous ayez rien à écrire. Le préfixe est le vôtre :

// MCP
attach_db_to_site({ db_id: "db_xxxx", site_id: "site_xxxx", env_prefix: "DATABASE_" })
// pose DATABASE_HOST, DATABASE_PORT, DATABASE_NAME,
//      DATABASE_USER, DATABASE_PASSWORD et DATABASE_URL

Elles vivent dans le même override que les vôtres, donc au démarrage seulement. Le préfixe doit être un début de nom de variable valide : une lettre ou un souligné, puis des lettres, des chiffres et des soulignés. Deux bases sur un même site demandent deux préfixes différents. Voir Bases de données.

Poser des variables dès la création

create_site accepte un champ env, écrit avant la première construction. C'est ce qui évite la séquence « création en échec, puis set_site_env, puis redéploiement », soit trois appels pour ce qui tient en un.

// MCP
create_site({
  project_id: "proj_xxxx",
  name: "mon-site",
  runtime: "nextjs",
  source_git: { url: "https://gitlab.exemple.fr/moi/mon-site.git", branch: "main", token: "..." },
  env: {
    IRIDFLOW_BUILD_ENV: "DATABASE_URL=postgres://factice",
    STRIPE_KEY: "sk_live_...",
  },
})

Ce qui est accepté comme nom et comme valeur

	Règle	Sinon
Nom	une lettre ou un souligné, puis lettres, chiffres et soulignés	refusé, avec le nom fautif dans le message
Valeur	tout, sauf un retour à la ligne. Espaces, guillemets, dollars, antislashs et croisillons passent et arrivent intacts dans le conteneur	un retour à la ligne est refusé : il casserait le fichier compose. Encodez la valeur, en base64 par exemple

Ce que la plateforme rend, et ce qu'elle ne rend jamais

Aucun outil de lecture ne rend la valeur d'une variable, seulement son nom. Savoir quelles variables sont posées sert à exploiter un site ; connaître leurs valeurs n'y sert pas.

Chemin	Nom	Valeur
get_site, list_sites, get_project	oui, dans `env_keys`	non
list_audit_log	oui	non
export_site	non	non : l'archive exclut `.env` et l'override
exec_site	oui	oui, et c'est pourquoi l'outil est réservé aux administrateurs
logs_site	—	seulement si votre application les écrit elle-même dans ses journaux
Sauvegarde nocturne	oui	oui : une sauvegarde doit pouvoir remettre le site exactement comme il était

Note

Un agent branché sur un compte client ne peut donc pas lire vos valeurs : exec_site lui est refusé. Vos sauvegardes, elles, contiennent les valeurs en clair sur votre espace de stockage : qui y accède accède aux variables de vos sites.

Le fichier .env de votre dépôt

Si votre dépôt contient son propre .env, le comportement dépend du runtime, et dans tous les cas Iridflow ne perd rien de ce qu'il a écrit.

nextjs, nextjs-ssg, node-generic, python-generic, php-generic, django, rails, frontend-static : le .env d'Iridflow est préservé, au même titre que le Dockerfile, le compose et le .dockerignore. Celui du dépôt n'est pas copié à la racine du site.
custom, docker-image : même préservation du .env et du compose, le Dockerfile du dépôt étant lui accepté, puisque c'est la raison d'être de ces runtimes.
static, wordpress : la source est copiée dans un sous-répertoire (site/, wp_content/), donc un .env du dépôt y atterrit et ne croise jamais celui de la plateforme.

Dans l'autre sens, Iridflow ne supprime jamais un .env qu'il n'a pas écrit. Le fichier qu'il génère porte un en-tête qui le désigne, et c'est à cet en-tête qu'il se reconnaît avant de le retirer.

Le .env généré est en outre inaccessible depuis le web, comme .git : le vhost renvoie 404 sur ces chemins.

Les erreurs les plus fréquentes

Ce que vous voyez	Ce qui se passe	Remède
La construction s'arrête sur `X is not set`, alors que vous venez de poser X	X est posée pour le démarrage, pas pour la construction	Ajoutez-la à `IRIDFLOW_BUILD_ENV`, puis redéployez
Vous posez une clé `IRIDFLOW_` et rien ne change	`set_site_env` relance le conteneur, il ne reconstruit pas l'image	`deploy_site`. La réponse le signalait dans `effet_differe`
La variable est annoncée posée, l'application ne la voit pas	L'override est écrit mais le conteneur n'a pas redémarré	Regardez `compose_up_ok` et `compose_stderr`, puis `restart_site`
`nom de variable invalide`	Un tiret, un point ou un espace dans le nom	Lettres, chiffres et soulignés, sans commencer par un chiffre
Une entrée de `IRIDFLOW_BUILD_ENV` disparaît	Elle n'a pas la forme `CLE=VALEUR`	Le journal de construction nomme l'entrée ignorée

Astuce

En cas de doute sur ce qui est réellement en place, get_site rend env_keys, la liste de tout ce qui est posé sur le site. C'est la source de vérité, et l'interface l'affiche telle quelle.

Variables d'environnement

La distinction qui explique tout le reste

Une variable peut être nécessaire à deux moments, et ce ne sont pas les mêmes fichiers qui les servent.

Moment	Fichier écrit par Iridflow	Ce qui le lit	Prise d'effet
Au démarrage du conteneur	docker-compose.override.yml	votre application, une fois lancée	immédiate, le conteneur est relancé
Pendant la construction	.env	docker compose, puis `docker build`	au prochain `deploy_site`

Attention

« Je veux TOTO=TATA », concrètement

C'est la question la plus posée, et elle a trois réponses selon le moment où votre code a besoin de la variable. Dans aucune des trois vous n'écrivez un fichier.

Votre besoin	Ce que vous posez	Ensuite
L'application lit `TOTO` quand elle tourne. Le cas courant.	nom `TOTO`, valeur `TATA`	rien, le site est relancé
`TOTO` est exigée pendant la construction	nom `IRIDFLOW_BUILD_ENV`, valeur `TOTO=TATA`	`deploy_site`, obligatoire
Les deux	les deux lignes ci-dessus	`deploy_site`

Ce que vous obtenez, et ce que vous n'obtenez pas

Posez TOTO = TATA et vous obtenez ceci dans l'override, qui met la variable dans l'environnement du conteneur :

// docker-compose.override.yml
services:
  web:
    environment:
      TOTO: "TATA"

Vous n'obtenez pas un fichier .env contenant TOTO=TATA. Et si vous ajoutez IRIDFLOW_BUILD_ENV = TOTO=TATA, le .env généré contient la ligne enveloppante, pas votre variable :

// .env généré par Iridflow
# Genere par Iridflow (set_site_env). Lu par docker compose pour
# interpoler le compose. Ne pas editer a la main.
IRIDFLOW_BUILD_ENV="TOTO=TATA"

Note

Si votre code utilise dotenv

Il continue de fonctionner, et c'est voulu : dotenv ne remplace jamais une variable déjà présente dans l'environnement. process.env.TOTO vaut donc TATA, que le fichier existe ou non.

Poser une variable

Depuis l'interface

Sur la fiche d'un site, le bloc Variables d'environnement a deux zones, une par moment.

Variables du site : la liste des noms posés, l'ajout d'une variable à la fois, et un collage de fichier .env entier. Le collage envoie tout en un seul appel, donc un seul redémarrage, là où l'ajout unitaire en provoque un par variable.
Variables de construction : la liste des noms déjà posés, et une zone au format .env qui remplace l'ensemble. Le remplacement est le seul mode possible, parce que les valeurs ne sont jamais relues : elles ne peuvent donc pas être complétées une par une. Coller un texte vide retire le lot.

La valeur n'est jamais réaffichée après coup, y compris à vous. Pour la changer, reposez la variable avec la nouvelle valeur.

Astuce

L'avertissement sur la fiche du site

Depuis le MCP ou l'API

// MCP
set_site_env({
  site_id: "site_xxxx",
  env: {
    DATABASE_URL: "postgres://...",
    STRIPE_KEY: "sk_live_...",
  },
})

Deux options changent le comportement :

Une valeur vide retire la variable. { ANCIENNE: "" } la supprime. Sans cela il n'y aurait aucun moyen d'en enlever une sans tout remplacer.
remplacer: true remplace l'ensemble au lieu de fusionner. Par défaut, ce que vous passez s'ajoute à ce qui existe.

Ce que la réponse vous dit

Champ	Ce qu'il signifie
env_keys	tous les noms posés sur le site, après fusion
variables_injectees	tout ce qui se retrouve dans l'override : vos variables et celles des bases attachées
retirees	les noms que cet appel a supprimés
compose_up_ok	à regarder : la variable peut être enregistrée alors que le site n'a pas redémarré pour la lire
effet_differe	présent dès qu'une clé `IRIDFLOW_` est posée : elle attend un déploiement

Les quatre réglages de construction

Variable	Runtimes	À quoi elle sert
IRIDFLOW_PREBUILD_CMD	nextjs, node-generic	Une commande entre l'installation et la construction : `prisma generate`, un codegen GraphQL, une génération de types. Laissée vide, un `prisma/schema.prisma` présent dans le dépôt déclenche à lui seul la génération du client.
IRIDFLOW_BUILD_ENV	nextjs, node-generic	Les variables dont la construction a besoin, sous la forme `CLE=VALEUR;CLE2=VALEUR2`.
IRIDFLOW_BUILD_CMD	frontend-static	Remplace `npm run build` quand la détection se trompe.
IRIDFLOW_OUTPUT_DIR	frontend-static	Le répertoire produit, quand il n'est ni `dist/`, ni `build/`, ni `out/`. C'est cette variable que réclame le message « build output introuvable ».

Écrire une valeur de IRIDFLOW_BUILD_ENV

// exemple
set_site_env({
  site_id: "site_xxxx",
  env: {
    IRIDFLOW_BUILD_ENV: 'NEXT_PUBLIC_TITRE=Mon site;DATABASE_URL=postgres://factice',
  },
})
// puis, obligatoirement :
deploy_site({ site_id: "site_xxxx" })

Le point-virgule sépare les entrées. C'est le seul caractère interdit dans une valeur.
Une valeur peut contenir des espaces, des guillemets, des dollars et des antislashs : elle est posée telle quelle, sans repasser par l'interpréteur.
Une entrée qui n'est pas de la forme CLE=VALEUR est ignorée, et le journal de construction la nomme au lieu de la laisser disparaître.

Attention

Les variables d'une base attachée

Attacher une base injecte ses identifiants sans que vous ayez rien à écrire. Le préfixe est le vôtre :

// MCP
attach_db_to_site({ db_id: "db_xxxx", site_id: "site_xxxx", env_prefix: "DATABASE_" })
// pose DATABASE_HOST, DATABASE_PORT, DATABASE_NAME,
//      DATABASE_USER, DATABASE_PASSWORD et DATABASE_URL

Poser des variables dès la création

// MCP
create_site({
  project_id: "proj_xxxx",
  name: "mon-site",
  runtime: "nextjs",
  source_git: { url: "https://gitlab.exemple.fr/moi/mon-site.git", branch: "main", token: "..." },
  env: {
    IRIDFLOW_BUILD_ENV: "DATABASE_URL=postgres://factice",
    STRIPE_KEY: "sk_live_...",
  },
})

Ce qui est accepté comme nom et comme valeur

	Règle	Sinon
Nom	une lettre ou un souligné, puis lettres, chiffres et soulignés	refusé, avec le nom fautif dans le message
Valeur	tout, sauf un retour à la ligne. Espaces, guillemets, dollars, antislashs et croisillons passent et arrivent intacts dans le conteneur	un retour à la ligne est refusé : il casserait le fichier compose. Encodez la valeur, en base64 par exemple

Ce que la plateforme rend, et ce qu'elle ne rend jamais

Aucun outil de lecture ne rend la valeur d'une variable, seulement son nom. Savoir quelles variables sont posées sert à exploiter un site ; connaître leurs valeurs n'y sert pas.

Chemin	Nom	Valeur
get_site, list_sites, get_project	oui, dans `env_keys`	non
list_audit_log	oui	non
export_site	non	non : l'archive exclut `.env` et l'override
exec_site	oui	oui, et c'est pourquoi l'outil est réservé aux administrateurs
logs_site	—	seulement si votre application les écrit elle-même dans ses journaux
Sauvegarde nocturne	oui	oui : une sauvegarde doit pouvoir remettre le site exactement comme il était

Note

Le fichier .env de votre dépôt

Si votre dépôt contient son propre .env, le comportement dépend du runtime, et dans tous les cas Iridflow ne perd rien de ce qu'il a écrit.

nextjs, nextjs-ssg, node-generic, python-generic, php-generic, django, rails, frontend-static : le .env d'Iridflow est préservé, au même titre que le Dockerfile, le compose et le .dockerignore. Celui du dépôt n'est pas copié à la racine du site.
custom, docker-image : même préservation du .env et du compose, le Dockerfile du dépôt étant lui accepté, puisque c'est la raison d'être de ces runtimes.
static, wordpress : la source est copiée dans un sous-répertoire (site/, wp_content/), donc un .env du dépôt y atterrit et ne croise jamais celui de la plateforme.

Le .env généré est en outre inaccessible depuis le web, comme .git : le vhost renvoie 404 sur ces chemins.

Les erreurs les plus fréquentes

Ce que vous voyez	Ce qui se passe	Remède
La construction s'arrête sur `X is not set`, alors que vous venez de poser X	X est posée pour le démarrage, pas pour la construction	Ajoutez-la à `IRIDFLOW_BUILD_ENV`, puis redéployez
Vous posez une clé `IRIDFLOW_` et rien ne change	`set_site_env` relance le conteneur, il ne reconstruit pas l'image	`deploy_site`. La réponse le signalait dans `effet_differe`
La variable est annoncée posée, l'application ne la voit pas	L'override est écrit mais le conteneur n'a pas redémarré	Regardez `compose_up_ok` et `compose_stderr`, puis `restart_site`
`nom de variable invalide`	Un tiret, un point ou un espace dans le nom	Lettres, chiffres et soulignés, sans commencer par un chiffre
Une entrée de `IRIDFLOW_BUILD_ENV` disparaît	Elle n'a pas la forme `CLE=VALEUR`	Le journal de construction nomme l'entrée ignorée

Astuce

En cas de doute sur ce qui est réellement en place, get_site rend env_keys, la liste de tout ce qui est posé sur le site. C'est la source de vérité, et l'interface l'affiche telle quelle.