vidconf/docs/deploy/dev-setup.md

Настройка Dev окружения

1. Требования

• Docker + Docker Compose v2
• uv (инструменты backend): brew install uv
• Node 20+ (frontend)

2. Переменные окружения

cp .env.example .env
# отредактируйте .env если нужно (defaults работают для локальной разработки)

Пример переменных окружения:

POSTGRES_USER=vidconf
POSTGRES_PASSWORD=dev_password
POSTGRES_DB=vidconf
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key-here
SEED_ADMIN_EMAIL=admin@example.com
SEED_ADMIN_PASSWORD=admin123

3. Запуск базового стека (без видеоконференций)

docker compose -f deploy/docker-compose.yml --env-file .env up -d
docker compose -f deploy/docker-compose.yml --env-file .env ps

Это запустит:

• postgres — База данных PostgreSQL
• redis — Redis (очередь Celery)
• backend — FastAPI сервис
• worker — Celery worker + beat (асинхронные задачи)
• nginx — Reverse proxy

Backend API доступен:

• Прямой: http://localhost:8000/api/health
• Через Nginx: http://localhost/api/health

3a. Добавить видеоконференции (профиль media: LiveKit + Coturn)

Для включения видеоконференций с LiveKit SFU + Coturn TURN сервером:

docker compose -f deploy/docker-compose.yml --env-file .env --profile media up -d

Это добавит:

• livekit — SFU сервер (слушает на ws://localhost:7880 для signaling, UDP 52000-52100 для media)
• coturn — TURN/STUN relay сервер

Проверка LiveKit:

# Проверить что LiveKit доступен
curl http://localhost:7880/health

# Проверить что Coturn слушает
nc -uz localhost 3478  # STUN

Ручная проверка видео: Откройте два браузерных окна (или вкладки) на http://localhost:5173 (frontend):

1. Первое окно: зарегистрируйтесь и войдите
2. Оба окна: отройте страницу лобби (комнаты)
3. Оба окна: нажмите "Войти" в одну и ту же комнату
4. Проверьте видео-потоки в обоих окнах (должны видеть друг друга)

Структура портов:

• 7880/tcp — LiveKit WebSocket signaling (через nginx /livekit/)
• 7881/tcp — LiveKit HTTPS (опционально)
• 52000-52100/udp — Media stream (RTP/RTCP)
• 3478/tcp,udp — Coturn STUN
• 3479/tcp,udp — Coturn альтернативный
• 5349/tcp,udp — Coturn TURNS (TLS)

4. Миграции БД и тестовые данные

cd backend
uv run alembic upgrade head
uv run python -m scripts.seed

Миграции:

• Создают все 14 таблиц (users, teams, email_verification_tokens, conferences, conference_invitees, guest_access, conference_sessions, conference_participants, session_audio_tracks, phrases, chat_messages, email_deliveries, instance_settings, livekit_webhook_events)
• Включают расширение PostgreSQL btree_gist (установлено, но текущей схемой не используется)

Идемпотентный сид (scripts.seed):

• Создаёт только 1 админ-пользователя (учётные данные из .env, SEED_ADMIN_EMAIL/SEED_ADMIN_PASSWORD)
• Конференции создаются пользователями динамически — предустановленных данных не требуется

5. Запуск Frontend (Разработка)

cd frontend
npm install
npm run dev

Frontend запущен на http://localhost:5173 с включённым hot-reload.

CORS: Frontend подключается к backend через прокси Vite:

• Запрос /api/* → перенаправляется на http://localhost:8000/api/*
• WebSocket /ws/* → перенаправляется на http://localhost:8000/ws/*
• Это настроено в frontend/vite.config.ts (режим разработки)

6. Проверка

Проверить, что всё запущено:

# Backend здоров
curl http://localhost:8000/api/health

# Миграции БД применены
cd backend && uv run alembic current

# Frontend доступен
curl http://localhost:5173

# Worker жив (если запущен)
docker compose -f deploy/docker-compose.yml --env-file .env exec worker celery -A workers.celery_app inspect ping

7. Тестирование и проверка качества

# Backend — lint + форматирование
cd backend
uv run ruff check . && uv run ruff format --check .

# Backend — проверка типов
uv run mypy .

# Backend — unit тесты
uv run pytest -q

# Frontend — lint
cd frontend
npm run lint

# Frontend — проверка сборки
npm run build

# Валидация docker-compose
docker compose -f deploy/docker-compose.yml --env-file .env config -q

8. Пресеты инсталлятора

VidConf поддерживает 5 пресетов инсталлятора:

1. MVP-ядро (лобби, конференции, календарь, закреплённые, гости) — минимум функций
2. +чат — текстовое общение в конференции (WebSocket + Redis pub/sub)
3. +AI min (CPU) — транскрибация + суммаризация на уровне min
4. +AI средний (CPU опционально GPU) — уровень medium
5. +AI макс (GPU обязателен) — уровень max для высокой нагрузки

Для локальной разработки используйте пресет 1 или 3 (с инсталлятором ./install.sh --preset 3).

Детали: docs/deploy/install.md и docs/architecture/adr/004-ai-tier-matrix.md

9. Решение проблем

Backend не может подключиться к БД:

docker compose -f deploy/docker-compose.yml --env-file .env logs postgres

Ошибка подключения Redis:

docker compose -f deploy/docker-compose.yml --env-file .env logs redis

Сборка Frontend не удаётся:

cd frontend
npm install --force  # Повтор установки зависимостей
npm run build

Миграции не выполняются:

cd backend
uv run alembic downgrade base
uv run alembic upgrade head

For more details, see README.md.