Local Development
Локальная инфраструктура для разработки: PostgreSQL + Redis через Docker Compose, синхронизация данных с production.
Summary
- Инфраструктура запускается через
docker-compose.dev.yml(PostgreSQL 16 + Redis 7) - Application code запускается через
pnpm dev(backend, frontend, admin — НЕ в Docker) - Данные синхронизируются с production через
dev-db-sync.sh(SSH + pg_dump)
Почему не всё в Docker?
Backend/frontend запускаются нативно для быстрого hot-reload и отладки. Docker только для инфраструктуры, которую неудобно ставить вручную.
Prerequisites
| Tool | Version | Проверка | Установка (WSL2) |
|---|---|---|---|
| Docker Engine | 20+ | docker --version | docs.docker.com |
| Docker Compose | v2+ | docker compose version | Включён в Docker Engine |
| Node.js | 18+ | node --version | nvm install 20 |
| pnpm | 9+ | pnpm --version | corepack enable && corepack prepare pnpm@latest |
| SSH access | — | ssh SERVER_HOST | Только для синхронизации БД |
Quick Start
1. Запустить инфраструктуру
docker compose -f docker-compose.dev.yml up -d
Дождаться health checks (~10 сек):
docker compose -f docker-compose.dev.yml up -d --wait
2. Настроить environment
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
В backend/.env указать Docker Compose defaults:
DATABASE_URL=postgresql://goloot:goloot@localhost:5432/goloot
3. Синхронизировать данные с production
bash scripts/db/dev-db-sync.sh root@YOUR_VPS_IP
Скрипт через SSH выполняет pg_dump на сервере и восстанавливает данные в локальный PostgreSQL.
Production данные
Синхронизированная БД содержит реальные пользовательские данные. Локальная БД — только для разработки.
4. Запустить приложение
pnpm dev
| Сервис | URL |
|---|---|
| Frontend | http://localhost:3001 |
| Backend API | http://localhost:4000 |
| Admin Panel | http://localhost:3002 |
| API Docs | http://localhost:4000/docs |
Database Sync
Как работает dev-db-sync.sh
Использование
# Аргументом
bash scripts/db/dev-db-sync.sh root@1.2.3.4
# Или через env (backend/.env)
# DEV_SYNC_SSH_HOST=root@1.2.3.4
bash scripts/db/dev-db-sync.sh
Скрипт автоматически:
- Находит PostgreSQL контейнер на сервере
- Определяет имя БД и пользователя из env контейнера
- Запрашивает подтверждение
- Выполняет drop + create + restore
Когда обновлять данные
- После изменений в Prisma schema (новые модели, поля)
- Когда нужны свежие данные для тестирования UI
- После крупных миграций на production
Architecture
Управление
| Действие | Команда |
|---|---|
| Запуск | docker compose -f docker-compose.dev.yml up -d |
| Остановка | docker compose -f docker-compose.dev.yml down |
| Логи | docker compose -f docker-compose.dev.yml logs -f |
| Полная очистка (с данными) | docker compose -f docker-compose.dev.yml down -v |
| Синхронизация prod данных | bash scripts/db/dev-db-sync.sh SSH_HOST |
| Применить Prisma schema | cd backend && npx prisma db push |
| Prisma Studio (GUI) | cd backend && npx prisma studio |
Troubleshooting
| Проблема | Причина | Решение |
|---|---|---|
| Port 5432 already in use | Windows PostgreSQL или другой контейнер | Остановить конфликтующий сервис или изменить порт в docker-compose.dev.yml |
| Port 6379 already in use | Windows Redis или другой контейнер | Аналогично |
| Backend стартует без Redis | Redis опционален | Backend работает без кэша (медленнее, но функционально) |
| pg_restore version mismatch | Разные минорные версии PostgreSQL | Обычно не критично с -Fc форматом. Обновить image если ошибки |
| WSL2: localhost не доступен из Windows | NAT networking mode | Использовать IP из hostname -I или включить networkingMode=mirrored в .wslconfig |
| dev-db-sync.sh: permission denied | SSH ключи не настроены | Настроить SSH key auth: ssh-copy-id root@server |