Variables d'environnement et secrets

Gardez tokens de bot, clés d’API et mots de passe de base de données hors de votre code source. Définissez-les comme variables d’environnement de l’application : votre code les lit à l’exécution comme n’importe quelle autre variable.

Définir des variables

Les variables d’environnement appartiennent à une seule application. Elles survivent aux redémarrages et aux commits, mais un nouvel envoi crée une nouvelle application sans elles : définissez-les à nouveau sur celle-ci.

Tableau de bord
CLI
VS Code
API

Ouvrez votre application dans le tableau de bord et allez dans Paramètres → Variables d’environnement.
Ajoutez chaque clé et sa valeur, ou importez un fichier .env existant.
Cliquez sur Enregistrer. Le tableau de bord vous propose de redémarrer l’application : redémarrez-la pour qu’elle prenne en compte les nouvelles valeurs.

Lorsque vous envoyez une nouvelle application depuis le tableau de bord, vous pouvez aussi ajouter des variables sur l’écran d’envoi, avant le premier démarrage.

Lancez les commandes depuis le dossier de votre projet. La CLI cible l’application dont l’ID figure dans votre squarecloud.app. Pour en cibler une autre, passez --app <ID de l'application> (pour list, passez l’ID en argument).

# Ajouter ou modifier des variables (les autres restent inchangées)
squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info

# Envoyer chaque ligne d'un fichier .env local
squarecloud app env set --from-file .env

# Lister les variables actuelles
squarecloud app env list

# Supprimer une variable
squarecloud app env remove LOG_LEVEL

# Redémarrer pour appliquer les changements
squarecloud app restart

squarecloud app env replace remplace l’ensemble des variables par celles que vous passez, après confirmation. Chaque commande et option est détaillée dans les variables d’environnement depuis la CLI ; pour installer la CLI et vous connecter, consultez le démarrage rapide de la CLI.

Envoyez les variables à POST /v2/apps/{app_id}/envs avec une clé d’API disposant du scope envs:write :

curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"envs": {"DISCORD_TOKEN": "your-token"}}'

Le même chemin permet aussi de lister (GET), de remplacer (PUT) et de supprimer (DELETE) des variables. L’API ne redémarre pas l’application : appelez ensuite l’endpoint de redémarrage.

Les variables sont chargées au démarrage de l’application. Après toute modification, redémarrez l’application, sinon elle continue de tourner avec les anciennes valeurs.

Les lire dans votre code

const token = process.env.DISCORD_TOKEN;

if (!token) {
  throw new Error("DISCORD_TOKEN is not set");
}

import os

token = os.environ.get("DISCORD_TOKEN")

if not token:
    raise RuntimeError("DISCORD_TOKEN is not set")

Échouer immédiatement quand une variable manque vous donne un message clair dans les logs, au lieu d’une erreur déroutante plus tard, comme un token invalide.

Variables définies par Square Cloud

Votre application démarre avec ces variables déjà définies :

Variable	Valeur	Sert à
`PORT`	`80`	Choisir le port sur lequel votre serveur web écoute.
`HOST`	`0.0.0.0`	Choisir l’adresse à laquelle votre serveur web se lie.
`SQUARECLOUD_APP_ID`	L’ID de votre application	Identifier l’application à l’exécution.
`NODE_ENV`	`production`	Indiquer aux bibliothèques Node.js qu’elles tournent en production (runtimes Node.js et TypeScript).

Ne redéfinissez pas PORT ni HOST sur un site web : la plateforme ne joint un serveur que sur le port 80 et l’hôte 0.0.0.0.

Comme NODE_ENV vaut production, npm install ignore les devDependencies. Si votre commande START compile le projet (par exemple avec typescript ou vite), listez ces outils de build dans les dependencies de package.json.

Comment les variables parviennent à votre app

Square Cloud stocke les variables dans un fichier .squarecloud/.env à l’intérieur de l’application et les charge avec un shell à chaque démarrage, avant l’installation des dépendances et l’exécution de votre commande START ou de votre fichier MAIN. Deux conséquences :

Les noms doivent utiliser des lettres, des chiffres et des tirets bas, et ne pas commencer par un chiffre.
Les valeurs contenant des espaces ou des caractères spéciaux du shell comme $, &, ; ou | doivent être entre guillemets, sinon le shell les coupe ou les interprète. Le tableau de bord et squarecloud app env set ajoutent les guillemets pour vous. Dans l’extension VS Code ou l’API, entourez vous-même une telle valeur de guillemets simples : saisissez 'p@ss word$1', ou envoyez "PASSWORD": "'p@ss word$1'" dans le corps de la requête API.

Les limites sont de 256 variables par application, 1 024 caractères par nom et 4 096 caractères par valeur. Les sites statiques (HTML/CSS) ne prennent pas en charge les variables d’environnement et renvoient STATIC_APP_ENV_NOT_SUPPORTED.

Garder les secrets hors de votre envoi

Si votre code charge lui-même un fichier .env (par exemple avec dotenv), ce fichier doit faire partie de l’envoi. Lister .env dans squarecloud.ignore démarre alors l’app sans ses secrets, et un bot échoue avec un token invalide. La configuration la plus sûre : déplacez chaque valeur de votre .env dans les variables d’environnement de l’application, comme indiqué ci-dessus. Une fois qu’elles sont définies, vous pouvez exclure .env de l’envoi et de votre dépôt Git. dotenv n’écrase pas les variables qui existent déjà : le même code continue donc de fonctionner sur votre machine et sur Square Cloud.

Ne commitez jamais de tokens ni de mots de passe dans un dépôt public. Si l’un d’eux a fuité, révoquez-le chez le fournisseur (par exemple, réinitialisez le token du bot dans le Developer Portal de Discord) et définissez la nouvelle valeur ici.

Étapes suivantes

Fichier de configuration

Définissez MAIN, MEMORY, START et les autres champs de squarecloud.app.

Héberger un bot Discord

Déployez un bot qui lit son token dans une variable d’environnement.

Erreurs des bots Discord

Corrigez un token invalide, des intents manquants et les bots qui passent hors ligne.

Erreurs de connexion aux bases de données

Connectez-vous avec un DATABASE_URL et les bons réglages SSL.

Services

Dépannage

Runtimes

Plateforme

Changelog

Variables d'environnement et secrets

Définir des variables

Les lire dans votre code

Variables définies par Square Cloud

Comment les variables parviennent à votre app

Garder les secrets hors de votre envoi

Étapes suivantes

Fichier de configuration

Héberger un bot Discord

Erreurs des bots Discord

Erreurs de connexion aux bases de données

​Définir des variables

​Les lire dans votre code

​Variables définies par Square Cloud

​Comment les variables parviennent à votre app

​Garder les secrets hors de votre envoi

​Étapes suivantes

Fichier de configuration

Héberger un bot Discord

Erreurs des bots Discord

Erreurs de connexion aux bases de données

Définir des variables

Les lire dans votre code

Variables définies par Square Cloud

Comment les variables parviennent à votre app

Garder les secrets hors de votre envoi

Étapes suivantes