Переменные окружения и секреты

Переменные окружения представляют собой пары «имя = значение», которые платформа передаёт вашему сервису. В них держат конфигурацию, которая зависит от окружения или не должна попадать в репозиторий: токены, ключи, параметры подключения к базе данных, режимы работы.

Две причины:

• Безопасность. Секрет в репозитории означает утечку: он остаётся в истории git даже после удаления.
• Переносимость. Значения на платформе отличаются от локальных (например, у базы данных здесь свой внутренний адрес).

Переменные задаются отдельно для каждого сервиса и доступны как во время сборки, так и во время работы приложения.

Как задать

В настройках сервиса добавьте переменную: имя и значение. Требования к имени:

• только латинские буквы, цифры и подчёркивание;
• не начинается с цифры.

Пример: BOT_TOKEN, DATABASE_URL, APP_KEY, LOG_LEVEL.

Обычная переменная или секрет

При добавлении переменную можно пометить как секрет. Разница только в отображении: значение секрета скрывается в интерфейсе (его не видно после сохранения). На хранение это не влияет: все значения шифруются, секретные и обычные одинаково.

Помечайте секретами токены, пароли и ключи. Обычными оставляйте безобидные настройки (уровень логирования, режим), которые удобно видеть в списке.

Как прочитать из кода

Переменные читаются стандартными средствами языка:

# Python
import os
token = os.environ["BOT_TOKEN"]

// Node.js
const token = process.env.BOT_TOKEN;

// PHP
$token = getenv("APP_KEY");

Зарезервированные имена

Часть имён занята платформой и их задать нельзя:

• PORT: задаётся портом сервиса; вручную запрещён (иначе разойдётся с маршрутизацией и health-check). Приложение читает PORT как обычно, платформа подставляет его сама.
• Префикс COOLIFY_: внутренние переменные платформы.

Переменные с префиксом NIXPACKS_ задавать можно: это настройки сборки (например, NIXPACKS_NODE_VERSION или NIXPACKS_PYTHON_VERSION).

Когда изменения вступают в силу

Это частый источник путаницы. Изменения переменных применяются при следующем деплое сервиса. Добавив, изменив или удалив переменную, запустите деплой (вручную из интерфейса или новым коммитом), иначе работающий контейнер продолжит использовать прежние значения.

Ограничения

• Длина значения ограничена 32 КБ. Для больших данных (файлы, сертификаты целиком) переменные не предназначены.
• Переменные задают конфигурацию, а не хранилище. Постоянные данные держите в базе данных, см. «Данные не сохраняются в контейнере».

Частые ошибки

Дальше

• Связь сервисов и подключение к базе данных
• Данные не сохраняются в контейнере
• Что нужно, чтобы деплой прошёл