Max Ronzhin
693db6e774
docker compose определяет .env для подстановки ${VAR} по каталогу
compose-файла (deploy/), а не по текущей директории — repo-root .env,
который использует install.sh и вся документация, молча не подхватывался.
Это и была причина "WARN: LIVEKIT_API_KEY not set" на боевом сервере:
секреты были в .env, но compose их не видел и подставлял небезопасные
дефолты (см. таблицу разведки сервера).
Теперь ставшие обязательными ${VAR:?} в docker-compose.yml (см. предыдущий
коммит) без этого немедленно проваливали бы конфиг на любой из
документированных команд. Добавлен `--env-file .env`/"$ENV_FILE" ко всем
вызовам docker compose в install.sh и в командах из README/docs.
install.sh дополнительно: ensure_default (аналог ensure_secret без генерации
секрета) для новых не-секретных параметров nginx/coturn/livekit
(NGINX_SERVER_NAMES, NGINX_CERT_NAME, LIVEKIT_USE_EXTERNAL_IP,
LIVEKIT_NODE_IP, TURN_EXTERNAL_IP) — дефолты только для локальной
разработки, не перезаписывают значения, заданные вручную на боевом
сервере. Плюс вызов deploy/render-templates.sh перед сборкой/подъёмом
стека.
195 lines
6.9 KiB
Markdown
195 lines
6.9 KiB
Markdown
# Настройка Dev окружения
|
||
|
||
## 1. Требования
|
||
|
||
- Docker + Docker Compose v2
|
||
- `uv` (инструменты backend): `brew install uv`
|
||
- Node 20+ (frontend)
|
||
|
||
## 2. Переменные окружения
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# отредактируйте .env если нужно (defaults работают для локальной разработки)
|
||
```
|
||
|
||
Пример переменных окружения:
|
||
```env
|
||
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. Запуск базового стека (без видеоконференций)
|
||
|
||
```bash
|
||
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 сервером:
|
||
|
||
```bash
|
||
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:**
|
||
```bash
|
||
# Проверить что 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. Миграции БД и тестовые данные
|
||
|
||
```bash
|
||
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 (Разработка)
|
||
|
||
```bash
|
||
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. Проверка
|
||
|
||
Проверить, что всё запущено:
|
||
|
||
```bash
|
||
# 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. Тестирование и проверка качества
|
||
|
||
```bash
|
||
# 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](install.md) и [docs/architecture/adr/004-ai-tier-matrix.md](../architecture/adr/004-ai-tier-matrix.md)
|
||
|
||
## 9. Решение проблем
|
||
|
||
**Backend не может подключиться к БД:**
|
||
```bash
|
||
docker compose -f deploy/docker-compose.yml --env-file .env logs postgres
|
||
```
|
||
|
||
**Ошибка подключения Redis:**
|
||
```bash
|
||
docker compose -f deploy/docker-compose.yml --env-file .env logs redis
|
||
```
|
||
|
||
**Сборка Frontend не удаётся:**
|
||
```bash
|
||
cd frontend
|
||
npm install --force # Повтор установки зависимостей
|
||
npm run build
|
||
```
|
||
|
||
**Миграции не выполняются:**
|
||
```bash
|
||
cd backend
|
||
uv run alembic downgrade base
|
||
uv run alembic upgrade head
|
||
```
|
||
|
||
For more details, see [README.md](../../README.md).
|