Référence des variables d'environnement
Toutes les variables d'environnement employées par les composants de Kuploy, regroupées par sujet.
Les licences
| Variable | Description | Par défaut | Obligatoire |
|---|
LICENSE_KEY | La clé de licence obtenue sur kuploy.app | (aucune) | Oui (Cloud) |
LICENSE_HUB_URL | L'URL du centre de licences | https://kuploy.app | Non |
LICENSE_SYNC_INTERVAL_SECONDS | La fréquence de synchronisation de la consommation avec le centre de licences. Les valeurs hors de l'intervalle 60–3600 sont ramenées à ses bornes. | 3600 (1 heure) | Non |
LICENSE_KEY et LICENSE_HUB_URL se configurent aussi depuis l'interface d'administration (Admin → Domains → License Hub Integration). La configuration enregistrée dans l'interface a priorité sur les variables d'environnement, et n'exige aucun redémarrage.
La facturation Stripe
| Variable | Description | Par défaut | Obligatoire |
|---|
STRIPE_SECRET_KEY | La clé secrète d'API Stripe | (aucune) | Oui (Cloud) |
STRIPE_PUBLISHABLE_KEY | La clé publiable Stripe | (aucune) | Oui (Cloud) |
STRIPE_WEBHOOK_SECRET | Le secret de signature des webhooks | (aucun) | Oui (Cloud) |
La passerelle de paiement (epay)
Un recours, lorsque la configuration par l'interface d'administration, sous Admin → Payment Gateway, n'a pas été utilisée. Voir Passerelle de paiement et la documentation d'administration d'epay-gateway.
| Variable | Description | Par défaut | Obligatoire |
|---|
EPAY_GATEWAY_URL | L'URL publique de votre déploiement epay-gateway | (aucune) | Non |
EPAY_GATEWAY_ADMIN_KEY | Le jeton Bearer pour les /api/manage/* d'epay-gateway | (aucun) | Non |
EPAY_MERCHANT_CODE | L'identifiant du compte marchand de l'exploitant, dans epay-gateway | (aucun) | Non |
EPAY_MERCHANT_KEY | Le secret HMAC qui sert à vérifier les signatures de webhook | (aucun) | Non |
L'authentification
| Variable | Description | Par défaut | Obligatoire |
|---|
BETTER_AUTH_SECRET | Le secret d'authentification, 32 caractères au minimum | (aucun) | Oui (Cloud) |
PLATFORM_ADMIN_EMAIL | L'adresse du premier administrateur de plateforme | (aucune) | Recommandée |
Le SSO (OpenID Connect)
À utiliser lorsqu'un produit consommateur (leeram-business, et kuploy-cloud à terme) fédère son identité avec kuploy-hub. Voir Le SSO avec kuploy-hub pour le parcours d'enregistrement.
Chez le consommateur
| Variable | Description | Par défaut | Obligatoire |
|---|
KUPLOY_HUB_URL | L'URL de base du centre (https://kuploy.app). C'est aussi là que requireInstanceAdmin appelle /oauth2/userinfo. | (aucune) | Oui pour le SSO |
KUPLOY_OIDC_CLIENT_ID | L'identifiant de client de confiance, enregistré sur le centre. | (aucun) | Oui pour le SSO |
KUPLOY_OIDC_CLIENT_SECRET | Correspond à la valeur clientSecret de l'entrée du consommateur dans le KUPLOY_OIDC_TRUSTED_CLIENTS du centre. | (aucun) | Oui pour le SSO |
NEXT_PUBLIC_APP_URL | L'URL publique du consommateur ; envoyée comme post_logout_redirect_uri lors d'une déconnexion à l'initiative du client. Doit figurer dans les redirectUrls du client de confiance. | (aucune) | Oui pour le SSO |
Sur le centre
| Variable | Description | Par défaut | Obligatoire |
|---|
KUPLOY_OIDC_TRUSTED_CLIENTS | Un tableau JSON des consommateurs SSO de confiance. Les redirectUrls de chaque entrée doivent comporter à la fois l'URL de rappel OAuth et l'URL de retour après déconnexion — c'est le même tableau qui est validé pour les deux. | [] | Si vous servez le SSO |
Sans l'entrée de retour après déconnexion dans redirectUrls, le point d'accès endsession du centre rejette les demandes de déconnexion avec invalid_request: post_logout_redirect_uri is not registered for this client. Voir Le comportement à la déconnexion.
Le SMTP
| Variable | Description | Par défaut | Obligatoire |
|---|
SMTP_HOST | Le nom d'hôte du serveur SMTP | (aucun) | Recommandée |
SMTP_PORT | Le port SMTP | 587 | Non |
SMTP_USER | L'identifiant d'authentification SMTP | (aucun) | Si SMTP_HOST est définie |
SMTP_PASS | Le mot de passe d'authentification SMTP | (aucun) | Si SMTP_HOST est définie |
SMTP_FROM | L'adresse d'expédition | (aucune) | Si SMTP_HOST est définie |
SMTP_FROM_NAME | Le nom d'expédition affiché | Kuploy | Non |
La base de données
| Variable | Description | Par défaut | Obligatoire |
|---|
DATABASE_URL | La chaîne de connexion PostgreSQL | (aucune) | Oui |
REDIS_URL | La chaîne de connexion Redis | (aucune) | Oui |
Le chiffrement
| Variable | Description | Par défaut | Obligatoire |
|---|
APP_SECRET | La clé de chiffrement des secrets enregistrés depuis l'administration : jeton Stalwart, mot de passe de registre, clés Stripe, etc. Elle doit être identique sur toutes les répliques et tous les déploiements qui partagent une base de données. | (aucune) | Oui (Cloud) |
Si deux déploiements partagent une base de données mais ont des APP_SECRET différents, les champs chiffrés enregistrés par l'un ne peuvent pas être déchiffrés par l'autre. L'interface d'administration affiche alors une alerte « token decryption failed » et se replie sur les variables d'environnement. Voir Héberger la messagerie pour le détail.
Le registre de conteneurs par défaut
| Variable | Description | Par défaut | Obligatoire |
|---|
DEFAULT_REGISTRY_URL | Le nom d'hôte du registre de conteneurs (par exemple registry.ceduth.dev) | (aucun) | Si elle n'est pas définie dans l'administration |
DEFAULT_REGISTRY_USERNAME | L'identifiant du registre (par exemple robot$kuploy+kuploy pour Harbor) | (aucun) | Si elle n'est pas définie dans l'administration |
DEFAULT_REGISTRY_PASSWORD | Le mot de passe du registre, ou le jeton du compte robot | (aucun) | Si elle n'est pas définie dans l'administration |
DEFAULT_REGISTRY_IMAGE_PREFIX | Le préfixe d'espace de noms des images (par exemple kuploy) | (aucun) | Non |
Se configure également sous Admin → Default Registry, le mot de passe étant chiffré en base. Les réglages de l'interface d'administration ont priorité.
L'hébergement de la messagerie (Stalwart)
| Variable | Description | Par défaut | Obligatoire |
|---|
STALWART_API_URL | L'URL de l'API REST de gestion de Stalwart (par exemple http://stalwart-api:8080) | (aucune) | Si elle n'est pas définie dans l'administration |
STALWART_API_TOKEN | La clé d'API Stalwart : le jeton Bearer de Directory → API Keys | (aucun) | Si elle n'est pas définie dans l'administration |
Se configure également sous Admin → Email Hosting (Stalwart), le jeton étant chiffré en base. Les réglages de l'interface d'administration ont priorité.
La page d'état (kuploy-cloud)
| Variable | Description | Par défaut | Obligatoire |
|---|
STATUS_PROBE_INTERVAL_SECONDS | La fréquence de l'ordonnanceur de sondes interne au processus (borné entre 60 et 3600) | 300 (5 min) | Non |
PLATFORM_STATUS_URL | L'URL qui prime pour le flux d'état de la plateforme en amont. Définissez-la à vide pour masquer entièrement la ligne « Upstream platform ». | ${LICENSE_HUB_URL}/api/status | Non |
La page d'état (kuploy-app, le centre de licences)
| Variable | Description | Par défaut | Obligatoire |
|---|
REGISTRY_PROBE_URL | Le nom d'hôte du registre de conteneurs partagé à sonder sur la page d'état centrale (par exemple registry.ceduth.dev) | (aucun) | Non |
REGISTRY_PROBE_USER | L'identifiant de registre pour la sonde — un accès en lecture seule suffit | (aucun) | Si REGISTRY_PROBE_URL est définie |
REGISTRY_PROBE_PASSWORD | Le mot de passe ou le jeton de registre pour la sonde | (aucun) | Si REGISTRY_PROBE_URL est définie |
Ces variables sont distinctes des DEFAULT_REGISTRY_* de kuploy-cloud, parce que kuploy-app, qui tourne sur Vercel, ne partage pas la configuration de kuploy-cloud. La sonde n'a besoin que d'un accès en lecture : un compte robot en lecture seule est l'idéal.
L'application
| Variable | Description | Par défaut | Obligatoire |
|---|
NEXT_PUBLIC_APP_URL | L'URL publique de l'instance kuploy-cloud | (aucune) | Recommandée |
PORT | Le port sur lequel l'application écoute | 3000 | Non |
NODE_ENV | L'environnement Node.js | production | Non |
Les tâches planifiées
| Variable | Description | Par défaut | Obligatoire |
|---|
CRON_SECRET | Le secret qui authentifie les requêtes des tâches planifiées | (aucun) | Si vous utilisez des tâches planifiées |
L'API d'import de sites
| Variable | Description | Par défaut | Obligatoire |
|---|
ADMIN_API_KEY | La clé d'API d'administration, pour un accès programmatique — elle contourne le cloisonnement par organisation | (aucune) | Non |
ADMIN_API_KEY est destinée aux exploitants de plateforme qui lancent des scripts de migration. Les utilisateurs ordinaires doivent plutôt se servir des clés d'API générées depuis Account → API Keys.
La priorité des configurations
Lorsqu'un même réglage est disponible à la fois par une variable d'environnement et par le tableau de bord d'administration :
- Le tableau de bord d'administration, stocké chiffré en base — la priorité la plus haute
- La variable d'environnement — le recours
Vous pouvez donc surcharger une variable d'environnement depuis le tableau de bord d'administration, sans redémarrer l'application. Voir Le tableau de bord d'administration pour le détail.