Variables d'environnement

Les variables d'environnement vous permettent de configurer votre application sans toucher à son code. Elles servent aux clés d'API, aux identifiants de base de données, aux indicateurs de fonctionnalité et à toute autre valeur de configuration.

Ajouter des variables

1. Ouvrez votre application
2. Allez dans l'onglet Environment
3. Cliquez sur Add Variable
4. Saisissez la clé et la valeur
5. Cliquez sur Save

# Exemple de format
DATABASE_URL=postgresql://utilisateur:motdepasse@hote:5432/base
API_KEY=votre-cle-api-secrete
NODE_ENV=production

Sécurité

Les variables d'environnement contenant des secrets sont chiffrées au repos, et ne réapparaissent jamais ni dans les logs ni dans l'interface une fois enregistrées.

Variables de build et variables d'exécution

Kuploy distingue deux types de variables.

Variables de build

Disponibles pendant la construction de l'image. Utilisez-les pour :

• la configuration propre au build
• l'installation de dépendances privées
• la compilation conditionnelle

# Exemples de variables de build
NPM_TOKEN=npm_xxx          # Pour des paquets npm privés
BUILD_ENV=production       # Options d'optimisation du build
NEXT_PUBLIC_API_URL=...    # Valeurs publiques, côté navigateur

Pour rendre une variable disponible au build :

1. Ajoutez la variable
2. Cochez l'option Available at build time

Variables d'exécution

Disponibles quand votre application tourne. Utilisez-les pour :

• les connexions aux bases de données
• les clés d'API et les secrets
• les indicateurs de fonctionnalité

# Exemples de variables d'exécution
DATABASE_URL=postgresql://...
STRIPE_SECRET_KEY=sk_live_xxx
FEATURE_NEW_UI=true

astuce

Par défaut, une variable n'existe qu'à l'exécution. Ne l'exposez au build que si c'est nécessaire : cela rallonge les builds dès que sa valeur change.

Import en masse depuis un fichier .env

Importez plusieurs variables d'un coup depuis un fichier .env :

1. Allez dans l'onglet Environment
2. Cliquez sur Bulk Import
3. Collez le contenu de votre .env, ou déposez le fichier
4. Relisez les variables détectées
5. Cliquez sur Import

# Exemple de fichier .env
DATABASE_URL=postgresql://localhost:5432/monapp
REDIS_URL=redis://localhost:6379
SECRET_KEY=votre-cle-secrete

DEBUG=false

# Les commentaires sont ignorés
# Les lignes vides aussi

info

L'import en masse reconnaît :

• le format CLE=valeur
• les valeurs entre guillemets : CLE="valeur avec des espaces"
• les commentaires commençant par #
• les valeurs sur plusieurs lignes, entre guillemets

Référencer une base de données gérée par la plateforme

Quand vous créez une base de données dans Kuploy, ses paramètres de connexion sont automatiquement disponibles sous forme de variables.

PostgreSQL

# Disponibles automatiquement dès qu'une base PostgreSQL est liée
POSTGRES_HOST=pg-xxx.kuploy.internal
POSTGRES_PORT=5432
POSTGRES_USER=kuploy
POSTGRES_PASSWORD=mot-de-passe-genere
POSTGRES_DATABASE=app_production

# Chaîne de connexion complète
DATABASE_URL=postgresql://kuploy:motdepasse@pg-xxx.kuploy.internal:5432/app_production

MySQL / MariaDB

MYSQL_HOST=mysql-xxx.kuploy.internal
MYSQL_PORT=3306
MYSQL_USER=kuploy
MYSQL_PASSWORD=mot-de-passe-genere
MYSQL_DATABASE=app_production

DATABASE_URL=mysql://kuploy:motdepasse@mysql-xxx.kuploy.internal:3306/app_production

MongoDB

MONGO_HOST=mongo-xxx.kuploy.internal
MONGO_PORT=27017
MONGO_USER=kuploy
MONGO_PASSWORD=mot-de-passe-genere
MONGO_DATABASE=app_production

MONGO_URL=mongodb://kuploy:motdepasse@mongo-xxx.kuploy.internal:27017/app_production

Redis

REDIS_HOST=redis-xxx.kuploy.internal
REDIS_PORT=6379
REDIS_PASSWORD=mot-de-passe-genere

REDIS_URL=redis://:motdepasse@redis-xxx.kuploy.internal:6379

Lier une base de données

Pour que ces variables soient injectées automatiquement :

1. Allez dans l'onglet Environment de votre application
2. Cliquez sur Link Resource
3. Choisissez la base de données dans votre projet
4. Sélectionnez les variables à injecter
5. Cliquez sur Link

Les variables sont mises à jour toutes seules si les identifiants de la base changent.

Interpolation

Une valeur peut en référencer une autre :

# Valeurs de base
APP_HOST=monapp.com
APP_PORT=3000

# Reprises dans une autre variable
APP_URL=https://${APP_HOST}:${APP_PORT}

Groupes de variables

Créez des groupes réutilisables pour les configurations communes :

1. Allez dans Project Settings → Variable Groups
2. Cliquez sur Create Group
3. Ajoutez-y vos variables partagées
4. Liez le groupe aux applications concernées

C'est utile pour :

• une clé d'API partagée entre plusieurs microservices
• une configuration commune à la pré-production et à la production
• les valeurs par défaut de votre équipe

Des valeurs par environnement

Utilisez des valeurs différentes selon l'environnement :

Variable	Développement	Pré-production	Production
NODE_ENV	development	staging	production
LOG_LEVEL	debug	info	error
API_URL	localhost:3000	staging.api.com	api.com

Deux façons de faire :

1. créer une application distincte par environnement ;
2. ou déployer par branche, avec un jeu de variables propre à chacune.

Bonnes pratiques

1. Ne versionnez jamais un secret — les données sensibles passent toujours par des variables d'environnement
2. Donnez des noms parlants — STRIPE_API_KEY vaut mieux que KEY1
3. Documentez les variables attendues — gardez un fichier .env.example dans votre dépôt
4. Renouvelez vos secrets régulièrement — changez périodiquement clés d'API et mots de passe
5. Servez-vous des groupes de variables — pour partager une configuration entre services
6. Séparez build et exécution — n'exposez une variable que là où elle sert

# .env.example — à versionner dans votre dépôt
DATABASE_URL=
REDIS_URL=
API_KEY=
SECRET_KEY=

# .env — à ne jamais versionner
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
API_KEY=la-vraie-cle
SECRET_KEY=le-vrai-secret