Environnement et propriétés

Elide charge les fichiers .env comme valeurs par défaut de l’environnement de l’application et les fichiers .properties comme valeurs par défaut des propriétés système Java. Aucune bibliothèque dotenv n’est nécessaire dans l’application. Les deux formats prennent en charge les valeurs chiffrées compatibles avec dotenvx.

Charger la configuration

Créez .env dans le répertoire depuis lequel vous invoquez Elide :

APP_NAME=greeter
APP_PORT=8080
APP_MESSAGE="Hello from ${APP_NAME}"

Créez app.ts :

console.log(process.env.APP_MESSAGE);
console.log(process.env.APP_PORT);

elide run app.ts

Hello from greeter
8080

Une variable d’environnement héritée est prioritaire, y compris avec une valeur vide :

APP_PORT=9090 elide run app.ts
APP_PORT= elide run app.ts

La seconde invocation reçoit un APP_PORT vide au lieu de 8080. Lisez les variables d’environnement via process.env, os.environ en Python ou l’interface d’environnement de votre langage. Les processus enfants reçoivent aussi l’environnement effectif. Lorsqu’une politique d’environnement filtre les variables héritées, les processus Java lancés, les tâches du projet et les processus enfants Node n’héritent que de l’instantané autorisé. Les entrées d’environnement explicites d’une tâche ou de la JVM sont appliquées ensuite ; une map env explicite d’un processus enfant Node remplace l’héritage. Le chargement de fichiers n’accorde aucune capacité de bac à sable supplémentaire et n’élargit pas l’accès à l’environnement d’un manifeste ; les contrôles --allow-env existants restent appliqués.

Découverte automatique des fichiers

Dans chaque répertoire sélectionné, Elide lit ces fichiers dans l’ordre :

Les fichiers automatiques absents sont ignorés. Les fichiers existants qui ne peuvent pas être lus ou analysés provoquent une erreur. Les deux formats sont distincts : une variable d’environnement nommée app.mode ne définit pas la propriété Java app.mode.

Par défaut, le lanceur ne consulte que le répertoire d’invocation. L’emplacement d’un script ne change pas ce répertoire. Exécuter elide run services/api/app.ts ne sélectionne pas automatiquement services/api/.env.

Avec --project PATH, Elide sélectionne ce répertoire de projet, ou le répertoire parent lorsque PATH désigne son manifeste. Il charge d’abord les répertoires englobants qui contiennent elide.pkl, du plus externe au plus interne, puis le répertoire sélectionné. Dans chaque répertoire, le fichier local suit le fichier de base. Les répertoires suivants remplacent les précédents. Les ancêtres arbitraires, le répertoire personnel et les membres sans rapport de l’espace de travail n’apportent aucune configuration au lanceur.

elide --project services/api run app.ts

Les tâches du projet utilisent aussi leurs couches d’environnement englobantes, d’espace de travail et de membre. Sélectionnez un projet explicitement lorsque sa configuration englobante doit être disponible au démarrage. Voir Configuration du projet.

Elide ne sélectionne pas automatiquement .env.production, .env.test, .properties.production ni des noms similaires. NODE_ENV, un profil d’exécution nommé et les fichiers de profil dotenvx ne sélectionnent pas de fichiers de configuration. Choisissez ces fichiers explicitement.

Choisir les fichiers explicitement

--env-file remplace la découverte automatique des fichiers dotenv. --properties-file remplace, indépendamment, la découverte automatique des propriétés. Répétez l’une ou l’autre option pour superposer des fichiers ; pour les noms en double, les derniers arguments l’emportent. Les chemins sont relatifs au répertoire d’invocation, y compris lorsque --project est fourni.

elide --env-file .env --env-file .env.production run app.ts
elide --properties-file config/base.properties --properties-file config/production.properties run Main.java
elide --env-file config/service.env --properties-file config/service.properties run Main.java

Les fichiers explicites sont obligatoires : un fichier absent est une erreur. Sélectionner seulement .env.production ne charge pas aussi .env ni .env.local. Incluez chaque fichier voulu.

elide --no-env --no-properties run app.ts

Combiner --no-env avec --env-file, ou --no-properties avec --properties-file, est une erreur d’utilisation. Vous pouvez désactiver un format tout en sélectionnant explicitement des fichiers pour l’autre.

Les lancements de sources Java autonomes respectent aussi les sélections explicites de fichiers, --no-env et --no-properties, sans redécouvrir les fichiers automatiques.

Priorité

Priorité de l’environnement, de la plus basse à la plus haute :

1. Fichiers dotenv sélectionnés, dans l’ordre de découverte ou des arguments.
2. Environnement hérité du processus, y compris les valeurs vides.
3. Affectations d’environnement explicites pour une tâche ou un processus enfant donné, dans cette portée d’exécution.

Priorité des propriétés Java, de la plus basse à la plus haute :

1. Fichiers de propriétés sélectionnés, dans l’ordre de découverte ou des arguments.
2. Affectations JVM -D fournies par l’opérateur lorsque Elide s’exécute sur une JVM existante.
3. Affectations explicites de propriétés dans la CLI d’Elide, comme --vm app.mode=production.

Les valeurs par défaut de propriétés fournies par la VM ne comptent pas comme des affectations de l’opérateur. Les applications reçoivent les propriétés avant leur initialisation. Les lancements Java enfants reçoivent les valeurs par défaut des propriétés de l’application avant leurs propres arguments JVM explicites. Une tâche avec des propriétés de VM distinctes s’exécute dans une VM séparée ; ses propriétés ne modifient pas l’état global du pilote de build.

Syntaxe dotenv

Les fichiers dotenv prennent en charge les commentaires, les valeurs entre guillemets, les valeurs multilignes, les valeurs vides et l’interpolation ${NAME}. Les guillemets simples préservent le contenu littéral. Les guillemets doubles autorisent l’interpolation.

# Application defaults
APP_NAME=greeter
APP_MESSAGE="Hello from ${APP_NAME}"
APP_LITERAL='${APP_NAME}'
APP_EMPTY=
APP_MULTILINE="first line
second line"
APP_COMMAND='$(echo hello)'

APP_LITERAL est la chaîne littérale ${APP_NAME}. APP_COMMAND est la chaîne littérale $(echo hello) ; Elide n’exécute pas de substitutions de commandes shell dans les fichiers de configuration.

L’interpolation a lieu pendant l’analyse de chaque fichier. Elle peut utiliser les variables héritées et les affectations antérieures du même fichier. Elle n’est pas réexécutée lorsque des fichiers ultérieurs remplacent des valeurs. Si .env définit APP_NAME=greeter et APP_MESSAGE="Hello from ${APP_NAME}", puis que .env.local change APP_NAME en api, le message reste Hello from greeter. Ne comptez pas sur l’interpolation entre fichiers distincts.

Propriétés Java

Pour les applications Java ou Kotlin, créez .properties :

app.name=greeter
app.message=Hello world
app.empty=
app.multiline=first\
  second
app.unicode=\u263A
app.literal=${APP_NAME}

Lisez-les avec System.getProperty("app.name") en Java ou Kotlin. Par exemple, enregistrez Main.java :

class Main {
  public static void main(String[] args) {
    System.out.println(System.getProperty("app.message"));
  }
}

elide run Main.java
elide --vm app.message="Hello from the CLI" run Main.java

La première invocation affiche Hello world ; la seconde affiche Hello from the CLI. app.multiline vaut firstsecond ; app.unicode vaut ☺ ; app.literal reste ${APP_NAME}.

Les propriétés utilisent la syntaxe Java : commentaires # et !, séparateurs échappés, lignes de continuation et échappements \uXXXX. Les guillemets font partie de la valeur ; ce ne sont pas des guillemets dotenv. Les propriétés n’interpolent pas les expressions dotenv et n’exécutent pas de commandes. Pour un contenu non ASCII portable, utilisez des échappements Unicode ; le lecteur de propriétés décode les octets en Windows-1252.

Les noms de propriétés ne doivent pas être vides et ne doivent contenir ni NUL ni =. Les valeurs peuvent contenir =, mais pas NUL. Les espaces de noms de propriétés java.*, elide* et org.graalvm* sont restreints, sauf elide.diag.*. Le chiffrement ne contourne pas ces restrictions. Les réglages polyglot.* suivent le chemin des options du moteur. Utilisez les options de VM de la CLI pour des réglages comme la taille du heap ; un fichier de propriétés n’est pas un fichier d’arguments JVM.

Lorsque Elide s’exécute sur une JVM déjà démarrée, le chargement de fichiers fournit des couches d’environnement aux applications et aux processus enfants. Il ne réécrit pas System.getenv() de cette JVM et ne modifie pas rétroactivement ses réglages de démarrage.

Valeurs chiffrées

Elide déchiffre les valeurs encrypted: compatibles avec dotenvx dans les fichiers dotenv et les propriétés Java. Les valeurs en clair et chiffrées peuvent cohabiter dans le même fichier et suivent les mêmes règles de priorité. Une valeur chiffrée remplacée par une valeur en clair ultérieure, ou par une valeur héritée de l’environnement, n’a pas besoin de clé de déchiffrement.

Utilisez un outil de chiffrement compatible pour produire le texte chiffré. Elide assure le déchiffrement au chargement de la configuration ; il ne fournit pas de commande de chiffrement. Par exemple, avec dotenvx installé :

dotenvx encrypt -f .env.production
elide --env-file .env.production run app.ts

Choisissez le stockage local .env.keys de dotenvx lorsqu’il vous est proposé. Son processus de chiffrement conserve le texte chiffré dans le fichier dotenv sélectionné et écrit la clé privée dans .env.keys. Pour .env.production, la clé se nomme DOTENV_PRIVATE_KEY_PRODUCTION. Elide exige toujours --env-file .env.production ; le suffixe de la clé ne sélectionne pas le fichier.

Fournir les clés privées

Elide accepte les variables héritées DOTENV_PRIVATE_KEY et DOTENV_PRIVATE_KEY_* suffixées, ou des clés dans .env.keys à côté des sources de configuration sélectionnées. L’environnement et les propriétés partagent la même recherche de clés.

1. Elide consulte .env.keys à côté des sources dotenv sélectionnées, puis des sources de propriétés sélectionnées, dans l’ordre des sources. Chaque répertoire est consulté une fois ; les affectations ultérieures des fichiers de clés remplacent les précédentes de même nom.
2. Les affectations DOTENV_PRIVATE_KEY* héritées remplacent les noms correspondants des fichiers de clés.
3. Les clés disponibles sont essayées sur les valeurs chiffrées effectives. Un suffixe de clé ne limite pas le déchiffrement à un nom de fichier de configuration particulier.

Les fichiers de clés ne sont lus que lorsqu’une valeur chiffrée effective doit être déchiffrée. Une exécution uniquement en clair n’exige pas .env.keys. La recherche de clés ne parcourt ni les ancêtres arbitraires ni votre répertoire personnel.

En CI, injectez la variable de clé privée correspondante via le gestionnaire de secrets de la CI, puis lancez Elide normalement :

# DOTENV_PRIVATE_KEY_PRODUCTION is supplied by the CI environment.
elide --env-file .env.production run app.ts

Gardez .env.keys hors du contrôle de versions, sauvegardez-le séparément et limitez l’accès au fichier. Relisez la configuration avant de la versionner : le chiffrement de certaines valeurs ne signifie pas que toutes le sont. Évitez d’afficher les secrets de l’application ou de passer des clés privées en clair dans les commandes shell et les journaux.

Les entrées de .env.keys servent uniquement au déchiffrement ; elles ne sont pas ajoutées à la configuration de l’application. Les entrées DOTENV_PUBLIC_KEY* des fichiers de configuration sont des métadonnées et sont omises des valeurs chargées dans l’application. Placer des affectations DOTENV_PRIVATE_KEY* dans un fichier dotenv ou de propriétés de l’application est une erreur. Les variables de clé privée héritées restent soumises à la visibilité ordinaire de l’environnement hérité.

Propriétés Java chiffrées

Une propriété Java peut contenir une valeur chiffrée compatible sans guillemets :

app.secret=encrypted:...

Les points de suspension remplacent le texte chiffré réel ; ce n’est pas une valeur chiffrée valide. Elide analyse d’abord les propriétés Java, puis déchiffre la valeur décodée avec les mêmes clés que pour dotenv. Ne supposez pas que la CLI dotenvx sait analyser ou réécrire les fichiers de propriétés Java. Le texte déchiffré est utilisé comme valeur : il n’est ni réanalysé comme configuration, ni interpolé, ni exécuté.

Commandes, tests et erreurs

Le chargement automatique s’applique à run, serve, dev, install, build, test, project, classpath, publish, java, python, repl et à l’exécution directe de fichiers. L’aide, la version, les complétions et les commandes d’administration sans rapport ignorent la découverte automatique de la configuration. Les commandes d’outils comme javac et kotlinc ne chargent pas automatiquement ces fichiers. Les options de fichier explicites demandent le chargement de la configuration pour les commandes qui atteignent le lanceur de l’application.

Pour des tests reproductibles, choisissez les fichiers explicitement ou désactivez les deux formats :

elide --env-file .env.test --no-properties test
elide --no-env --no-properties test

Ces options n’effacent pas les variables d’environnement héritées. Définissez-les ou supprimez-les séparément dans le lanceur de tests. Une invocation résolue conserve son instantané de configuration ; lancez une nouvelle invocation pour prendre en compte des fichiers ou des clés modifiés.

Les fichiers sélectionnés illisibles, la syntaxe invalide, les entrées interdites, les clés invalides et les valeurs effectives indéchiffrables échouent avant l’exécution de l’application ou de la tâche concernée. Les diagnostics indiquent une catégorie d’erreur et le chemin source, sans afficher de lignes source, de valeurs, de texte chiffré ni de clés privées. Corrigez la source signalée ou désactivez explicitement son format. Aucune configuration partiellement résolue issue d’un format en échec n’est publiée.

Pour les variables qui configurent Elide lui-même, voir Variables d’environnement d’exécution. Pour le détail des options, voir Référence CLI.