# Середовище та властивості

Elide завантажує файли `.env` як типові значення оточення застосунку, а файли `.properties` — як типові значення
системних властивостей Java. Бібліотека dotenv у застосунку не потрібна. Обидва формати підтримують зашифровані
значення, сумісні з dotenvx.

> [!NOTE] Доступно в Elide 1.6.2
> У цьому посібнику описано підтримку контексту запуску в Elide 1.6.2.

## Завантаження конфігурації

Створіть `.env` у каталозі, з якого викликаєте Elide:

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

Створіть `app.ts`:

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

```sh
elide run app.ts
```

```text
Hello from greeter
8080
```

Успадкована змінна оточення має пріоритет, навіть якщо її значення порожнє:

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

Другий виклик отримує порожній `APP_PORT` замість `8080`. Читайте змінні оточення через
[`process.env`](/docs/env-variables), `os.environ` у Python або інтерфейс оточення вашої мови.
Дочірні процеси теж отримують чинне оточення. Якщо політика оточення фільтрує успадковані змінні, запущені процеси
Java, завдання проєкту й дочірні процеси Node успадковують лише дозволений знімок. Явні записи оточення завдання або
JVM застосовуються після цього; явна мапа `env` дочірнього процесу Node замінює успадкування.
Завантаження файлів не надає додаткових можливостей пісочниці
і не розширює доступ маніфесту до оточення; чинні обмеження `--allow-env` і далі застосовуються.

## Автоматичний пошук файлів

У кожному вибраному каталозі Elide читає ці файли по черзі:

| Конфігурація | Першим | Другим, перевизначає перший |
| --- | --- | --- |
| Оточення | `.env` | `.env.local` |
| Властивості Java | `.properties` | `.properties.local` |

Відсутні автоматичні файли ігноруються. Наявні файли, які не вдається прочитати чи розібрати, спричиняють помилку.
Формати незалежні: змінна оточення з назвою `app.mode` не задає властивість Java `app.mode`.

Типово лаунчер перевіряє лише каталог виклику. Розташування скрипта цей каталог не змінює.
`elide run services/api/app.ts` не вибирає `services/api/.env` автоматично.

З `--project PATH` Elide вибирає цей каталог проєкту або батьківський каталог, якщо `PATH` вказує на маніфест.
Спершу завантажуються зовнішні каталоги, що містять `elide.pkl`, від найзовнішнішого до найвнутрішнього, потім
вибраний каталог. У кожному каталозі локальний файл іде після базового. Пізніші каталоги перевизначають ранніші.
Довільні предки, домашній каталог і непов'язані учасники робочого простору не впливають на конфігурацію лаунчера.

```sh
elide --project services/api run app.ts
```

Завдання проєкту також використовують свої зовнішні рівні оточення, рівень робочого простору й рівень учасника.
Вибирайте проєкт явно, якщо його зовнішня конфігурація має бути доступна під час запуску. Див.
[Налаштування проєкту](/docs/projects).

Elide не вибирає автоматично `.env.production`, `.env.test`, `.properties.production` і подібні назви.
`NODE_ENV`, іменований профіль виконання та файли профілів dotenvx не вибирають файли конфігурації. Вказуйте такі
файли явно.

## Явний вибір файлів

`--env-file` замінює автоматичний пошук файлів dotenv. `--properties-file` незалежно замінює автоматичний пошук файлів
властивостей. Повторюйте будь-який із прапорців, щоб нашаровувати файли; за збігу назв перемагають пізніші аргументи.
Шляхи вказуються відносно каталогу виклику, навіть якщо задано `--project`.

```sh
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
```

Явно вказані файли обов'язкові: відсутній файл — це помилка. Вибір лише `.env.production` не завантажує додатково
`.env` чи `.env.local`. Вкажіть кожен потрібний файл.

| Прапорець | Дія |
| --- | --- |
| `--no-env` | Вимикає завантаження dotenv. Успадковані змінні оточення залишаються доступними. |
| `--no-properties` | Вимикає завантаження файлів властивостей. |
| `--no-env --no-properties` | Вимикає обидва види завантаження файлів. |

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

Поєднання `--no-env` з `--env-file` або `--no-properties` з `--properties-file` — помилка використання.
Можна вимкнути один формат і явно вибрати файли для іншого.

Запуск окремих вихідних файлів Java теж ураховує явний вибір файлів, `--no-env` і `--no-properties`, не виконуючи
повторний автоматичний пошук.

## Пріоритет

Пріоритет оточення, від найнижчого до найвищого:

1. Вибрані файли dotenv у порядку пошуку або аргументів.
2. Успадковане оточення процесу, зокрема порожні значення.
3. Явні присвоєння оточення для конкретного завдання чи дочірнього процесу в межах цієї області виконання.

Пріоритет властивостей Java, від найнижчого до найвищого:

1. Вибрані файли властивостей у порядку пошуку або аргументів.
2. Присвоєння JVM `-D`, задані оператором, коли Elide працює на вже наявній JVM.
3. Явні присвоєння властивостей у CLI Elide, наприклад `--vm app.mode=production`.

Типові значення властивостей, які надає VM, не вважаються присвоєннями оператора. Застосунки отримують властивості
до своєї ініціалізації. Дочірні запуски Java отримують типові значення властивостей застосунку до власних явних
аргументів JVM. Завдання з відмінними властивостями VM виконується в окремій VM; його властивості не змінюють
глобальний стан драйвера збирання.

## Синтаксис dotenv

Файли dotenv підтримують коментарі, значення в лапках, багаторядкові значення, порожні значення та інтерполяцію
`${NAME}`. Одинарні лапки зберігають вміст буквально. Подвійні лапки дозволяють інтерполяцію.

```dotenv
# 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` — це буквальний рядок `${APP_NAME}`. `APP_COMMAND` — буквальний рядок `$(echo hello)`;
Elide не виконує підстановку команд оболонки у файлах конфігурації.

Інтерполяція відбувається під час розбору кожного файлу. Вона може використовувати успадковані змінні й попередні
присвоєння в тому самому файлі. Вона не виконується повторно, коли пізніші файли перевизначають значення. Якщо `.env`
задає `APP_NAME=greeter` і `APP_MESSAGE="Hello from ${APP_NAME}"`, а потім `.env.local` змінює `APP_NAME` на `api`,
повідомлення й далі буде `Hello from greeter`. Не покладайтеся на інтерполяцію між різними файлами.

## Властивості Java

Для застосунків на Java або Kotlin створіть `.properties`:

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

Читайте їх через `System.getProperty("app.name")` у Java або Kotlin. Наприклад, збережіть `Main.java`:

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

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

Перший виклик виводить `Hello world`, другий — `Hello from the CLI`.
`app.multiline` дорівнює `firstsecond`; `app.unicode` дорівнює `☺`; `app.literal` лишається `${APP_NAME}`.

Властивості використовують синтаксис Java: коментарі `#` і `!`, екрановані роздільники, рядки продовження та
екранування `\uXXXX`. Лапки входять до значення й не працюють як лапки dotenv. Властивості не інтерполюють вирази
dotenv і не виконують команди. Для переносного вмісту поза ASCII використовуйте екранування Unicode: читач
властивостей декодує байти як Windows-1252.

Назви властивостей не можуть бути порожніми й не можуть містити NUL або `=`. Значення можуть містити `=`, але не NUL.
Простори назв властивостей `java.*`, `elide*` і `org.graalvm*` обмежено, крім `elide.diag.*`.
Шифрування не обходить ці обмеження. Налаштування `polyglot.*` обробляються як параметри рушія.
Для таких налаштувань, як розмір купи, використовуйте параметри VM у CLI; файл властивостей не є файлом аргументів
JVM.

Коли Elide працює на вже запущеній JVM, завантаження файлів передає шари оточення застосункам і дочірнім процесам.
Воно не переписує `System.getenv()` цієї JVM і не змінує заднім числом її налаштування запуску.

## Зашифровані значення

Elide розшифровує сумісні з dotenvx значення `encrypted:` у файлах dotenv і властивостях Java. Відкриті та
зашифровані значення можуть бути в одному файлі й підпорядковуються однаковим правилам пріоритету. Зашифрованому
значенню, яке замінено пізнішим відкритим значенням або успадкованим значенням оточення, ключ розшифрування не
потрібен.

Створюйте шифротекст сумісним інструментом шифрування. Elide розшифровує значення під час завантаження конфігурації,
але не надає команди шифрування. Наприклад, зі встановленим dotenvx:

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

Коли з'явиться запит, виберіть локальне сховище `.env.keys` у dotenvx. Його
[процес шифрування](https://dotenvx.com/docs/custody/env-keys/) залишає шифротекст у вибраному файлі dotenv і
записує закритий ключ у `.env.keys`. Для `.env.production` ключ має назву `DOTENV_PRIVATE_KEY_PRODUCTION`.
Elide і далі вимагає `--env-file .env.production`; суфікс ключа файл не вибирає.

### Передавання закритих ключів

Elide приймає успадковані змінні `DOTENV_PRIVATE_KEY` і `DOTENV_PRIVATE_KEY_*` із суфіксом або ключі в `.env.keys`
поруч із вибраними джерелами конфігурації. Оточення та властивості використовують спільний пошук ключів.

1. Elide перевіряє `.env.keys` поруч із вибраними джерелами dotenv, потім поруч із вибраними джерелами властивостей,
   у порядку джерел. Кожен каталог перевіряється один раз; пізніші присвоєння з файлів ключів замінюють ранніші з
   тією самою назвою.
2. Успадковані присвоєння `DOTENV_PRIVATE_KEY*` перевизначають збіжні назви з файлів ключів.
3. Доступні ключі пробуються на чинних зашифрованих значеннях. Суфікс ключа не обмежує розшифрування конкретною
   назвою файлу конфігурації.

Файли ключів читаються лише тоді, коли чинне зашифроване значення потрібно розшифрувати. Запуску лише з відкритими
значеннями `.env.keys` не потрібен. Пошук ключів не охоплює довільних предків і ваш домашній каталог.

У CI передайте відповідну змінну із закритим ключем через сховище секретів CI і запускайте Elide як зазвичай:

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

Не додавайте `.env.keys` до системи контролю версій, зберігайте його резервну копію окремо й обмежте доступ до файлу.
Перевіряйте конфігурацію перед комітом: якщо частину значень зашифровано, це не означає, що зашифровано всі.
Не виводьте секрети застосунку й не передавайте закриті ключі відкритим текстом у командах оболонки та журналах.

Записи з `.env.keys` використовуються лише для розшифрування; до конфігурації застосунку вони не додаються.
Записи `DOTENV_PUBLIC_KEY*` у файлах конфігурації — це метадані, і до завантажених значень застосунку вони не
потрапляють. Присвоєння `DOTENV_PRIVATE_KEY*` у файлі dotenv або файлі властивостей застосунку — помилка.
На успадковані змінні із закритими ключами поширюються звичайні правила видимості успадкованого оточення.

### Зашифровані властивості Java

Властивість Java може містити сумісний шифротекст без лапок:

```properties
app.secret=encrypted:...
```

Три крапки позначають справжній шифротекст і не є допустимим зашифрованим значенням. Elide спершу розбирає
властивості Java, а потім розшифровує декодоване значення тими самими ключами, що й для dotenv. Не розраховуйте, що
CLI dotenvx уміє розбирати чи переписувати файли властивостей Java. Розшифрований текст використовується як значення:
його не розбирають повторно як конфігурацію, не інтерполюють і не виконують.

## Команди, тести та помилки

Автоматичне завантаження застосовується до `run`, `serve`, `dev`, `install`, `build`, `test`, `project`, `classpath`,
`publish`, `java`, `python`, `repl` і до прямого запуску файлів. Довідка, версія, автодоповнення й непов'язані
адміністративні команди пропускають автоматичний пошук конфігурації. Команди інструментів, як-от `javac` і `kotlinc`,
не завантажують ці файли автоматично. Явні прапорці файлів запитують завантаження конфігурації для команд, які
доходять до лаунчера застосунку.

Для відтворюваних тестів вибирайте файли явно або вимикайте обидва формати:

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

Ці прапорці не очищують успадковані змінні оточення. Задавайте або видаляйте їх окремо в засобі запуску тестів.
Розв'язаний виклик зберігає свій знімок конфігурації; щоб урахувати змінені файли чи ключі, почніть новий виклик.

Непридатні для читання вибрані файли, некоректний синтаксис, заборонені записи, недійсні ключі та чинні значення, які
не вдається розшифрувати, спричиняють помилку до запуску відповідного застосунку чи завдання. Діагностика повідомляє
категорію помилки та шлях до джерела, не виводячи рядки джерела, значення, шифротекст чи закриті ключі.
Виправте вказане джерело або явно вимкніть його формат.
Частково розв'язана конфігурація з формату з помилкою не публікується.

Про змінні, що налаштовують сам Elide, див.
[Змінні оточення середовища виконання](/docs/runtime-env-variables). Подробиці про прапорці:
[Довідник CLI](/docs/cli-references).