architect/standards/PLATFORM2_DEV_SETUP.md

Platform 2 — Минимальная конфигурация разработки

Версия: 1.0.0
Дата: 2026-03-11


Что запускаем локально

Принцип: минимум — только то что нужно для разработки

ЛОКАЛЬНО:                   НА DEV СЕРВЕРЕ:
 PostgreSQL (Supabase)     Supabase (полный)
 FastAPI (hot reload)      FastAPI
 Refine (dev server)       Refine
 Redis                     Redis + Celery
 Mailpit (email catcher)   Meilisearch
                             n8n
                             PostHog (lite)

Postal, LiteLLM, Gotenberg, n8n — запускаете только когда разрабатываете эти функции.


Шаг 1: Установить Supabase CLI

# Установка
brew install supabase/tap/supabase    # macOS
# или
npm install -g supabase               # любая ОС

# Инициализация проекта
supabase init

# Запуск локального Supabase
supabase start

supabase start автоматически поднимает:
- PostgreSQL :5432
- PostgREST (REST API) :54321
- GoTrue (Auth) :54321/auth
- Studio (admin UI) :54323
- Inbucket (email catcher для auth писем)

Supabase CLI управляет всеми своими сервисами сам — docker-compose писать не нужно.


Шаг 2: docker-compose.dev.yml

Для остальных сервисов платформы:

# docker-compose.dev.yml
version: '3.8'

services:

  # Кэш и очередь
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --loglevel warning

  # FastAPI (hot reload)
  api:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app                    # hot reload
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgresql://postgres:postgres@host.docker.internal:5432/postgres
      REDIS_URL: redis://redis:6379
      SUPABASE_URL: http://host.docker.internal:54321
      SUPABASE_KEY: ${SUPABASE_ANON_KEY}
      SMTP_HOST: mailpit
      SMTP_PORT: 1025
    command: uvicorn app.main:app --reload --host 0.0.0.0 --port 8080
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Linux: доступ к Supabase CLI
    depends_on:
      - redis

  # Refine (Next.js — hot reload, на Linux без потерь производительности)
  frontend:
    image: node:20-alpine
    working_dir: /app
    volumes:
      - ./frontend:/app
      - frontend_modules:/app/node_modules  # node_modules в контейнере
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_SUPABASE_URL: http://host.docker.internal:54321
      NEXT_PUBLIC_SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY}
      NEXT_PUBLIC_API_URL: http://host.docker.internal:8080
    command: sh -c "npm install && npm run dev"
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Linux: доступ к хосту

  # Celery worker (опционально — только если разрабатываете async задачи)
  worker:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
    environment:
      DATABASE_URL: postgresql://postgres:postgres@host.docker.internal:5432/postgres
      REDIS_URL: redis://redis:6379
    command: celery -A app.worker worker --loglevel=debug
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on:
      - redis
    profiles:
      - worker                    # запускается только с --profile worker

  # Email catcher (замена Postal для разработки)
  mailpit:
    image: axllent/mailpit:latest
    ports:
      - "8025:8025"               # веб-UI: http://localhost:8025
      - "1025:1025"               # SMTP
    environment:
      MP_MAX_MESSAGES: 100

  # Meilisearch (опционально — только если разрабатываете поиск)
  meilisearch:
    image: getmeili/meilisearch:v1.6
    ports:
      - "7700:7700"
    environment:
      MEILI_MASTER_KEY: dev_master_key
      MEILI_ENV: development
    volumes:
      - meilisearch_data:/meili_data
    profiles:
      - search

  # Gotenberg (опционально — только если разрабатываете PDF)
  gotenberg:
    image: gotenberg/gotenberg:8
    ports:
      - "3002:3002"
    profiles:
      - pdf

volumes:
  meilisearch_data:
  frontend_modules:        # node_modules изолированы в контейнере

Шаг 3: Dockerfile.dev (FastAPI)

# Dockerfile.dev
FROM python:3.12-slim

WORKDIR /app

# Зависимости
COPY requirements.txt .
RUN pip install -r requirements.txt

# watchfiles для hot reload
RUN pip install watchfiles

EXPOSE 8080

Шаг 4: .env.dev

# Supabase (значения из: supabase start)
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_KEY=eyJ...
POSTGRES_PASSWORD=postgres

# Redis
REDIS_URL=redis://localhost:6379

# Email (Mailpit)
SMTP_HOST=localhost
SMTP_PORT=1025

# AI
ANTHROPIC_API_KEY=sk-ant-...

# Dev режим
ENV=development
DEBUG=true

Запуск

Базовый (каждый день)

# 1. Supabase
supabase start

# 2. Всё остальное (включая Refine)
docker compose -f docker-compose.dev.yml up -d

С дополнительными сервисами

# + Celery worker
docker compose -f docker-compose.dev.yml --profile worker up -d

# + Поиск (Meilisearch)
docker compose -f docker-compose.dev.yml --profile search up -d

# + PDF (Gotenberg)
docker compose -f docker-compose.dev.yml --profile pdf up -d

Остановка

docker compose -f docker-compose.dev.yml down
supabase stop

Адреса в браузере (локально)

Сервис URL
Refine (приложение) http://localhost:3000
FastAPI docs http://localhost:8080/docs
Supabase Studio http://localhost:54323
Mailpit (email UI) http://localhost:8025
Meilisearch http://localhost:7700

Конфигурация DEV сервера

DEV сервер = полный стек, но с dev-настройками.

docker-compose.dev-server.yml

# На DEV сервере запускаем больше сервисов
# Supabase — официальный docker-compose (не CLI)
# + платформа + инструменты

# Отличия от PROD:
# - DEBUG=true
# - Простые пароли
# - Нет SSL (или самоподписанный)
# - Меньше реплик
# - Mailpit вместо Postal
# - PostHog в dev режиме

Что на DEV сервере и чего нет

Сервис DEV сервер Причина
Supabase ✅ полный нужна среда близкая к проду
FastAPI тестирование API
Refine ✅ build тестирование UI
Redis + Celery тестирование async
Meilisearch тестирование поиска
n8n тестирование автоматизаций
PostHog ✅ lite тестирование аналитики
Mailpit вместо Postal
Gotenberg тестирование PDF
LiteLLM тестирование AI
Marimo тестирование документов
Postal только PROD
Certbot/SSL только PROD
Uptime Kuma только PROD

Ресурсы

Среда RAM CPU Disk
Локально 4 GB (для Docker) 2+ 20 GB
DEV сервер 4 GB 2 40 GB
PROD сервер 8–16 GB 4–8 80–150 GB

Makefile для удобства

# Makefile

dev-start:
    supabase start
    docker compose -f docker-compose.dev.yml up -d

dev-stop:
    docker compose -f docker-compose.dev.yml down
    supabase stop

dev-logs:
    docker compose -f docker-compose.dev.yml logs -f api

dev-reset:
    supabase db reset
    docker compose -f docker-compose.dev.yml restart api

test:
    docker compose -f docker-compose.dev.yml exec api pytest

migrate:
    supabase db push

Запуск одной командой:

make dev-start

См. также: PLATFORM2_ARCHITECTURE.md