mnemo_cards/mnemo_cards_backend/ENVIRONMENT_VARIABLES.md

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

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

### PostgreSQL
```bash
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
```bash
PORT=3000                     # Порт на котором запускается backend
SERVER_ADDRESS=0.0.0.0       # Адрес для bind (0.0.0.0 = все интерфейсы)
WORK_DIR=/app                # Рабочая директория
DEBUG=false                  # Режим отладки (true для разработки)
```

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

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

---

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

### YooKassa (платежи)
```bash
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
```bash
BACKUP_DIR=/app/backups      # Директория для бэкапов (опционально)
```

---

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

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

```bash
# Linux/macOS
openssl rand -base64 32

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

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

```bash
# Linux/macOS
openssl rand -base64 24
```

---

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

### Для разработки (.env.local)
```bash
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)
```bash
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` файла:

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

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

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

---

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

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

### В терминале (Linux/macOS)
```bash
echo $DB_HOST
```

### В Docker контейнере
```bash
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` - используйте его как шаблон!**