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

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

Две причины:

• Безопасность. Секрет в репозитории — это утечка: он остаётся в истории 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 КБ. Для больших данных (файлы, сертификаты целиком) переменные не предназначены.
• Переменные — это конфигурация, а не хранилище. Постоянные данные держите в базе данных, см. «Данные не сохраняются в контейнере».

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

Дальше

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