mnemo_cards/mnemo_cards_backend/ENVIRONMENT_VARIABLES.md

🔧 Переменные окружения для mnemo_cards_backend

📋 Обязательные переменные

PostgreSQL

DB_HOST=localhost              # Hostname PostgreSQL (в Coolify: internal hostname)
DB_PORT=5432                   # Порт PostgreSQL
DB_NAME=mnemo_cards           # Имя базы данных
DB_USER=mnemo_user            # Пользователь БД
DB_PASSWORD=secret_password   # Пароль БД (ОБЯЗАТЕЛЬНО изменить!)
DB_SSL_MODE=disable           # 'disable' для разработки, 'require' для продакшена

Backend settings

PORT=3000                     # Порт на котором запускается backend
SERVER_ADDRESS=0.0.0.0       # Адрес для bind (0.0.0.0 = все интерфейсы)
WORK_DIR=/app                # Рабочая директория
DEBUG=false                  # Режим отладки (true для разработки)

JWT Authentication

JWT_SECRET=your_jwt_secret_here              # Секрет для JWT токенов (min 32 символа)
JWT_REFRESH_SECRET=your_refresh_secret_here  # Секрет для refresh токенов

Admin

ADMIN_IDS=1,2,3              # ID администраторов через запятую

---

📋 Опциональные переменные

YooKassa (платежи)

YOOKASSA_SHOP_ID=            # Shop ID от YooKassa (обязательно)
YOOKASSA_SECRET_KEY=         # Secret Key от YooKassa (обязательно)
YOOKASSA_RETURN_URL=         # Базовый URL для возврата после оплаты (опционально)
                              # По умолчанию: https://mnemo-cards.online/payment/return
                              # Формат: https://your-domain.com/payment/return

Backup

BACKUP_DIR=/app/backups      # Директория для бэкапов (опционально)

---

🔒 Генерация секретов

Генерация JWT секретов

# Linux/macOS
openssl rand -base64 32

# или
cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

Генерация пароля БД

# Linux/macOS
openssl rand -base64 24

---

📝 Примеры конфигураций

Для разработки (.env.local)

DB_HOST=localhost
DB_PORT=5432
DB_NAME=mnemo_cards_dev
DB_USER=mnemo_user
DB_PASSWORD=dev_password_change_me
DB_SSL_MODE=disable

PORT=3000
SERVER_ADDRESS=0.0.0.0
WORK_DIR=/root/mnemo_cards_backend
DEBUG=true

ADMIN_IDS=1

JWT_SECRET=dev_jwt_secret_12345678901234567890
JWT_REFRESH_SECRET=dev_refresh_secret_12345678901234567890

BACKUP_DIR=/app/backups

Для продакшена (Coolify/Docker)

DB_HOST=mnemo-postgres        # Internal hostname в Coolify
DB_PORT=5432
DB_NAME=mnemo_cards
DB_USER=mnemo_user
DB_PASSWORD=<сгенерированный пароль>
DB_SSL_MODE=require           # SSL для продакшена!

PORT=3000
SERVER_ADDRESS=0.0.0.0
WORK_DIR=/app
DEBUG=false

ADMIN_IDS=1,2,3

JWT_SECRET=<сгенерированный секрет 32+ символов>
JWT_REFRESH_SECRET=<другой сгенерированный секрет 32+ символов>

YOOKASSA_SHOP_ID=<ваш shop id>
YOOKASSA_SECRET_KEY=<ваш secret key>

BACKUP_DIR=/app/backups

---

⚠️ Важные замечания

Безопасность

1. НИКОГДА не коммитить .env файлы в Git!
2. ОБЯЗАТЕЛЬНО изменить все пароли и секреты в продакшене
3. Использовать DB_SSL_MODE=require в продакшене
4. JWT секреты должны быть минимум 32 символа
5. Регулярно ротировать секреты

В Coolify

1. Переменные окружения хранятся безопасно
2. Использовать Internal hostnames для связи между сервисами
3. Coolify автоматически управляет SSL/TLS
4. Можно использовать Secrets для паролей

Docker Compose (локально)

При использовании docker-compose.yml переменные читаются из .env файла:

# Создать .env из примера
cp .env.example .env

# Отредактировать .env
nano .env

# Запустить
docker-compose up -d

---

🔍 Проверка переменных

В коде

// Чтение переменной окружения
final dbHost = Platform.environment['DB_HOST'] ?? 'localhost';

В терминале (Linux/macOS)

echo $DB_HOST

В Docker контейнере

docker exec mnemo_backend env | grep DB_

В Coolify

Открыть Environment Variables в настройках приложения

---

🆘 Troubleshooting

Ошибка: "Environment variable not found"

Причина: Переменная не установлена

Решение:

1. Проверить .env файл
2. Проверить переменные в Coolify
3. Перезапустить приложение

Ошибка: "Invalid JWT secret"

Причина: Секрет слишком короткий

Решение: Использовать секрет минимум 32 символа

Ошибка: "Cannot connect to database"

Причина: Неправильные DB_* переменные

Решение:

1. Проверить DB_HOST, DB_PORT, DB_NAME
2. Проверить DB_USER, DB_PASSWORD
3. Проверить что PostgreSQL запущен

---

Все переменные настроены в .env.example - используйте его как шаблон!