# Настройки только в .env-файлах

Стандарт jcb-dotenv - v1.0 - 2026-11-16

## Суть

Всё, что отличается между окружениями (адреса, порты, база, секреты, переключатели), лежит в `.env`-файлах.
В коде **нет значений по умолчанию** для этих настроек: всё берётся из окружения. Если обязательной переменной нет,
сервер не запускается и пишет, какой именно.

## Файлы

| Файл | В git | Режим |
|---|---|---|
| `.env.development` | да | разработка |
| `.env.test` | да | автопроверки |
| `.env.test.<вид>` | да | только если нужно: вид проверок со своими серверами (например, сквозные) |
| `.env.local` | нет | личное поверх разработки: своя почта админа, ключи внешних служб, пароли |
| `.env.production.example` | да | шаблон для сервера: все переменные, секреты без значений |

На сервере файлов нет: переменные задаются окружению процесса или контейнера.

## Правила

- **У всех файлов один набор переменных в одном порядке**, отличаются только значения. Ненужное в режиме — пусто.
  Новая переменная — сразу во все файлы.
- **Переключатели — словами из короткого списка**: `on|off`, `log|smtp`, `open|admins`. Не `1`/`true`/`yes`.
- **Переключатели задаются явно**: нет значения или оно не из списка — сервер не стартует и называет переменную.
  Код не угадывает режим. В шаблоне для сервера у переключателей стоят боевые значения (лимиты `on`, тестовые
  ручки `off`), секреты — пустые.
- **Ключи внешней службы — не переключатель**: их наличие и есть настройка. Все пустые — функции нет, все заданы —
  есть; отдельного `on|off` не нужно. Задана только часть ключей службы — сервер не стартует и называет недостающие.
- **Приоритет.** Разработка: окружение оболочки > `.env.local` > `.env.development`. Автопроверки: файл главнее
  оболочки, `.env.local` не читается — проверки не зависят от того, что задано у человека.
- **Закоммиченные файлы — без боевых значений**: секреты вида `dev-secret-…`/`test-secret-…`, адреса `localhost` /
  `*.test`, база локальная.
- **Правила продукта — в коде, а не в окружении**: сроки, лимиты, длины. Окружение — только то, что меняется между
  местами запуска.
- **«test» — только автопроверки.** Живой стенд перед боевым сайтом называется «staging» и получает свой шаблон.
- **Чтение — в одном модуле**: он проверяет значения при старте, остальной код берёт их оттуда, а не из
  `process.env` напрямую.
- **Каждая переменная описана** в одном документе проекта — `docs/env.md`: что делает, какие значения бывают, что
  стоит в каждом файле. У каждой переменной свой заголовок вида `` ### `ИМЯ` `` (несколько связанных — в одном:
  `` ### `SMTP_HOST`, `SMTP_PORT` ``). Оформление внутри раздела — на усмотрение проекта.

## Проверка

Автопроверка в проекте читает все файлы и требует:
- одинаковый набор и порядок переменных во всех файлах;
- каждая переменная, которую читает код, есть в файлах;
- переключатели заданы во всех файлах и только из списка значений;
- закоммиченные файлы без боевых значений; шаблон без секретов; в шаблоне тестовые ручки выключены, лимиты включены;
- `.env.local` в `.gitignore`;
- в `docs/env.md` у каждой переменной из файлов есть заголовок, и нет заголовков переменных, которых в файлах нет.

## История

- v1.0 — 2026-11-16: первая версия, из практики MoveTap.
