DÉPLOYER

Variables d’environnement et secrets

Configurez chaque application, partagez via des jeux de variables, et gardez vos secrets hors de Git.

La configuration qui change d’un environnement à l’autre — une URL de base, un jeton d’API, un drapeau de fonctionnalité — appartient aux variables d’environnement, pas au dépôt. DockBoard les stocke chiffrées et les injecte au démarrage du conteneur.

Par application

L’onglet Environnement d’une application. Ajoutez clés et valeurs, enregistrez, redéployez. Les valeurs sont chiffrées au repos et ne ressortent jamais dans un log de déploiement ou une sortie de build.

Un changement prend effet au prochain déploiement, pas immédiatement. L’environnement d’un conteneur en marche n’est pas modifiable à chaud — c’est Docker, pas DockBoard. Enregistrez, puis redéployez.

Partagées à l’échelle d’un projet

Six applications qui ont toutes besoin du même REDIS_URL ne doivent pas en porter six copies. Un jeu de variables de projet se définit une fois et atteint toutes les applications du projet.

Un jeu est soit valable pour tout le projet, soit limité à un environnement. D’où la forme réellement souhaitée : un DATABASE_URL pour la préproduction, un autre pour la production, sous le même nom de clé.

Quelle valeur l’emporte

Trois couches, de la plus large à la plus étroite. La suivante l’emporte sur la précédente :

TEXT

project-wide set        REDIS_URL=redis://shared:6379
  ↓ beaten by
environment set         REDIS_URL=redis://staging:6379
  ↓ beaten by
the application itself  REDIS_URL=redis://localhost:6379

Le tableau de bord indique, pour chaque clé que l’application recevra réellement, de quelle couche elle vient. C’est la réponse à « pourquoi cette variable n’est-elle pas celle que j’ai posée » sans avoir à raisonner sur l’ordre.

Réservez la couche projet à ce qui est réellement partagé, et la couche application aux exceptions. Une clé surchargée dans chaque application est une clé qui n’a sa place qu’au niveau application — la valeur partagée devient sinon un leurre, qui a l’air de faire foi et ne s’applique jamais.

Les variables que votre dépôt transporte déjà

Un déploiement depuis Git n’ignore pas les fichiers .env versionnés dans le dépôt — un projet qui démarre en local sur ses valeurs par défaut doit démarrer ici aussi. Ils sont lus depuis le clone et fusionnés sous tout ce qui est défini dans DockBoard : rien dans le dépôt ne peut donc déplacer discrètement une valeur posée depuis le tableau de bord.

Dans un même dossier, cinq noms sont lus dans cet ordre, chacun l’emportant sur les précédents :

TEXT

.env.example   →   .env.local.example   →   .env.production   →   .env   →   .env.local

.env.example est lu volontairement, à la priorité la plus basse : un dépôt qui ne fournit qu’un modèle se déploie quand même du premier coup. Mais si rien d’autre ne définit une clé, ce paramètre fictif devient la valeur de production — le log de build nomme donc chaque clé fournie par un seul modèle, et signale celles qui semblent non modifiées. JWT_SECRET=change_me dans un dépôt public est un secret public.

Monorepos : deux dossiers, pas un

Quand une application vit dans un sous-dossier d’un monorepo, les cinq noms ci-dessus sont lus deux fois : une fois à la racine du clone, une fois dans le sous-dossier de l’application. Le sous-dossier l’emporte.

C’est ce qui fait qu’un .env à la racine d’un monorepo se comporte comme ses auteurs l’entendaient : des valeurs par défaut communes à tous les packages, chaque package restant libre de surcharger ce qui le concerne. Rien à configurer pour l’obtenir : cela s’applique dès que l’application a un chemin de sous-dossier.

L’ordre complet

Cinq couches, pour une application en monorepo déployée depuis Git dans un projet qui partage des variables. La suivante l’emporte sur la précédente, sans exception :

TEXT

1  monorepo root .env*        committed, shared by every package
2  sub-folder .env*           committed, belongs to this application
3  project-wide set           DockBoard, every environment
4  environment set            DockBoard, one environment
5  the application itself     DockBoard, this application

La ligne de partage passe entre 2 et 3 : tout ce qui est versionné dans le dépôt se situe sous tout ce qui est défini dans DockBoard. Un DATABASE_URL dans un .env versionné est une valeur par défaut de développement local ; celui de votre jeu de projet est le vrai, et il l’emporte à chaque déploiement.

Les couches 1 et 2 n’existent que pour un déploiement qui clone un dépôt. Une application déployée depuis une image Docker, un modèle du marketplace ou un site PHP n’a pas de clone à lire : elle n’a que les couches 3 à 5.

L’onglet Environnement affiche les variables propres à l’application (couche 5) et ce qu’elle hérite du projet (couches 3 et 4), avec l’origine de chacune. Il ne liste pas ce que fournit le dépôt : ces valeurs n’existent qu’une fois le dépôt cloné, ce qui a lieu pendant le déploiement. Une clé introuvable dans l’onglet mais observée dans le conteneur vient d’un .env versionné ; le log de build les nomme.

Les deux modes de déploiement appliquent ceci à l’identique. Un dépôt construit sur votre hôte de plateforme et le même dépôt construit par un agent sur un serveur distant lisent les mêmes fichiers, dans le même ordre, et produisent les mêmes valeurs.

Comment les secrets sont traités

Les valeurs sont chiffrées au repos avec la clé de chiffrement de l’instance, pas stockées en colonnes claires.
Les lire ou les écrire exige apps:env — une permission qui ne fait pas partie du rôle en lecture seule. Voir votre application n’implique pas voir ses secrets. Voir rôles.
Modifier le jeu partagé du projet est soumis à la même permission que l’onglet par application. Il détient les mêmes secrets de production : il ne doit pas être la porte la moins gardée.
Une clé API ne les atteint qu’avec le scope project:apps:env, que vous pouvez refuser tout en accordant le droit de déployer.

Une variable n’est pas un coffre-fort. Tout ce qui est dans l’environnement est lisible par le processus — et par quiconque peut ouvrir un shell dans le conteneur (apps:exec). Si une valeur ne doit pas être lisible par ceux qui exploitent l’application, elle n’a pas sa place dans une variable d’environnement.

Les variables que DockBoard renseigne pour vous

Une base gérée expose une chaîne de connexion à coller telle quelle dans une variable, pointant déjà sur le nom du réseau de projet et non sur une adresse publique. C’est le chemin prévu : les applications joignent leur base par le réseau privé, et la base n’est jamais publiée.

Les environnements de préview copient les variables de leur application source : un preview pointe donc sur la même base que la branche dont il est issu. C’est délibéré — un environnement de revue sans données ne démarre généralement pas — mais cela signifie qu’un preview peut écrire dans les vraies données.