Окружения

Руководство по настройке и управлению различными окружениями для Integ API.

Runtime Environment Injection

Integ API использует runtime injection переменных окружения через Doppler. Это означает:

• Переменные читаются из process.env при запуске приложения
• Один Docker образ для всех окружений
• Переключение окружения через DOPPLER_CONFIG

Обзор окружений

Окружение	DOPPLER_CONFIG	MODE	Назначение
Local	local	local	Локальная разработка
Development	dev	dev	Dev сервер
Production	prod	prod	Production сервер

Структура environment.ts

Файл src/environments/environment.ts читает переменные из process.env в runtime:

export const environment = {
	port: getEnvNumber("PORT", 3000),
	mode: getEnv("MODE", "local") as "local" | "dev" | "prod",
	database: {
		host: getEnv("POSTGRES_HOST"),
		port: getEnvNumber("POSTGRES_PORT", 5432),
		username: getEnv("POSTGRES_USERNAME"),
		password: getEnv("POSTGRES_PASSWORD"),
		name: getEnv("POSTGRES_NAME"),
		ssl: Boolean(process.env.POSTGRES_CERTIFICATE) || Boolean(process.env.POSTGRES_CERTIFICATE_BASE64)
	},
	jwt: {
		secret: getEnv("JWT_SECRET")
	},
	crypto: {
		masterKey: getEnv("CRYPTO_KEY"),
		salt: getEnv("CRYPTO_SALT")
	}
	// ... остальные поля
};

Local Environment

Запуск с дефолтами

Для быстрого старта можно запустить без Doppler — используются дефолтные значения:

# Запуск PostgreSQL
npm run docker:up

# Запуск приложения (дефолтные значения)
npm start

Запуск с Doppler

# Установка Doppler config
doppler setup --config local

# Запуск с injection
doppler run --config local -- npm start

Переменные для local

Переменная	Значение	Описание
MODE	local	Режим окружения
PORT	3005	Порт сервера
POSTGRES_HOST	localhost	Хост БД (Docker)
POSTGRES_PORT	5435	Порт БД
POSTGRES_USERNAME	-	Пользователь
POSTGRES_PASSWORD	-	Пароль
POSTGRES_NAME	-	Имя БД
POSTGRES_CERTIFICATE	false	SSL отключен
INTEG_CORE_URL	http://localhost:3010	URL integ-core
INNGEST_URL	http://localhost:8288	URL Inngest

Особенности local

• ✅ Hot reload включен
• ✅ PostgreSQL в Docker
• ✅ LocalSqlite для эмуляции D1/KV
• ✅ Дефолтные значения для быстрого старта
• ❌ Cloudflare API не используется

Development Environment

Запуск

# С Doppler
doppler run --config dev -- npm run start:prod

# Или в Docker
docker run -e DOPPLER_TOKEN=xxx -e DOPPLER_CONFIG=dev ghcr.io/happ-ai/integ-api:dev

Переменные для dev

Переменная	Описание
MODE	dev
POSTGRES_HOST	Managed DB host
POSTGRES_CERTIFICATE	true (SSL обязателен)
POSTGRES_CERTIFICATE_BASE64	CA сертификат в base64
CLOUDFLARE_ACCOUNT_ID	Account ID
CLOUDFLARE_WORKERS_API_TOKEN	API Token
CLOUDFLARE_INTEG_DB_ID	Dev D1 ID
CLOUDFLARE_INTEG_KV_ID	Dev KV ID

Особенности dev

• ✅ SSL для БД
• ✅ Cloudflare D1/KV в dev режиме
• ✅ Отдельные ресурсы от production
• ⚠️ Тестовые данные

Production Environment

Запуск

# В Docker на сервере
docker run -e DOPPLER_TOKEN=xxx -e DOPPLER_CONFIG=prod ghcr.io/happ-ai/integ-api:latest

Переменные для prod

Переменная	Описание
MODE	prod
POSTGRES_HOST	Production DB host
POSTGRES_CERTIFICATE	true
POSTGRES_CERTIFICATE_BASE64	Production CA сертификат
JWT_SECRET	Сильный секрет (64+ символов)
CRYPTO_KEY	Сильный ключ (64+ символов)
CLOUDFLARE_INTEG_DB_ID	Production D1 ID
CLOUDFLARE_INTEG_KV_ID	Production KV ID

Особенности prod

• ✅ SSL обязателен
• ✅ Сильные секреты
• ✅ Managed database с backups
• ✅ Production Cloudflare ресурсы
• ❌ Debug режимы отключены

Полный список переменных

Приложение

Переменная	Тип	Default	Описание
PORT	number	3000	Порт сервера
MODE	string	local	Режим (local/dev/prod)

База данных

Переменная	Тип	Default	Описание
POSTGRES_HOST	string	-	Хост
POSTGRES_PORT	number	5432	Порт
POSTGRES_USERNAME	string	-	Пользователь
POSTGRES_PASSWORD	string	-	Пароль
POSTGRES_NAME	string	-	Имя БД
POSTGRES_CERTIFICATE	string	-	Использовать SSL
POSTGRES_CERTIFICATE_BASE64	string	-	CA сертификат base64

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

Переменная	Тип	Default	Описание
JWT_SECRET	string	-	Секрет JWT
CRYPTO_KEY	string	-	Ключ шифрования
CRYPTO_SALT	string	-	Соль шифрования

Администратор

Переменная	Тип	Default	Описание
ADMIN_EMAIL	string	-	Email админа
ADMIN_PASSWORD	string	-	Пароль админа

Scalar (API Docs)

Переменная	Тип	Default	Описание
SWAGGER_INTERNAL_USERNAME	string	admin	Логин для внутренней доки
SWAGGER_INTERNAL_PASSWORD	string	admin	Пароль для внутренней доки

Cloudflare

Переменная	Тип	Default	Описание
CLOUDFLARE_ACCOUNT_ID	string	-	Account ID
CLOUDFLARE_WORKERS_API_TOKEN	string	-	API Token
CLOUDFLARE_INTEG_DB_ID	string	-	D1 Database ID
CLOUDFLARE_INTEG_KV_ID	string	-	KV Namespace ID
CLOUDFLARE_LOCAL_DATA_PATH	string	../integ-core/data/miniflare	Путь к miniflare

Сервисы

Переменная	Тип	Default	Описание
INTEG_CORE_URL	string	http://localhost:3010	URL integ-core
INNGEST_URL	string	http://localhost:8288	URL Inngest
INNGEST_SIGNING_KEY	string	-	Ключ Inngest

AI/Testing

Переменная	Тип	Default	Описание
CLAUDE_API_KEY	string	-	Claude API ключ
ELEVENLABS_API_KEY	string	-	ElevenLabs ключ
ELEVENLABS_API_URL	string	https://api.elevenlabs.io/v1	ElevenLabs URL

SSL сертификат для БД

Для dev/prod с managed database нужен CA сертификат:

Конвертация в base64

# Закодировать сертификат
cat ca-certificate.crt | base64 -w 0 > cert-base64.txt

# Добавить в Doppler
doppler secrets set POSTGRES_CERTIFICATE_BASE64 "$(cat cert-base64.txt)" --config dev

Как это работает

// data-source.ts
function getCertificate(): string | undefined {
	const base64Cert = process.env.POSTGRES_CERTIFICATE_BASE64;
	if (!base64Cert) return undefined;
	return Buffer.from(base64Cert, "base64").toString("utf-8");
}

Переключение окружений

Локально

# Local (с дефолтами)
npm start

# Local (с Doppler)
doppler run --config local -- npm start

# Dev
doppler run --config dev -- npm start

# Prod
doppler run --config prod -- npm start

В Docker

# Local
docker run -e DOPPLER_TOKEN=xxx -e DOPPLER_CONFIG=local image

# Dev
docker run -e DOPPLER_TOKEN=xxx -e DOPPLER_CONFIG=dev image

# Prod
docker run -e DOPPLER_TOKEN=xxx -e DOPPLER_CONFIG=prod image

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

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

# Для dev (32 символа)
openssl rand -hex 32

# Для prod (64 символа)
openssl rand -hex 64

Проверка что секреты разные

doppler secrets get JWT_SECRET --config local --plain
doppler secrets get JWT_SECRET --config dev --plain
doppler secrets get JWT_SECRET --config prod --plain
# Они должны быть РАЗНЫМИ!

Best Practices

✅ DO:

• Используйте разные секреты для каждого окружения
• Используйте разные D1/KV для dev и prod
• Генерируйте сильные пароли (32+ символов)
• Включите SSL в dev и prod
• Храните сертификаты в base64

❌ DON'T:

• Не используйте одинаковые секреты
• Не отключайте SSL в prod
• Не используйте production ресурсы для dev
• Не коммитьте секреты в git

Следующие шаги

• Docker - Docker deployment
• Deployment Overview - Общий обзор