Быстрый старт

Поднять платформу локально нужно в правильном порядке — у сервисов есть зависимости.

Требования

Что	Версия
Node.js	≥ 20.9
Python	3.13 (Garden) и 3.12 (Bot) — лучше через pyenv или uv
UV	актуальная (`pipx install uv` или `brew install uv`)
Yarn	1.22.x
Docker + Docker Compose	актуальные
Supabase CLI	актуальная (`brew install supabase/tap/supabase`)
Poetry (только для Ansible)	актуальная

Шаг 1. Supabase

Без него ничего не работает — это PostgreSQL + Auth + Storage + Edge Functions.

cd supabase
make start

Поднимается:

Supabase API на :54321
PostgreSQL на :54322
Studio на :54323 (UI)
Inbucket на :54324 (тестовый SMTP — посмотреть, что отправляется)

Запустить Edge Functions локально (для тестирования вебхуков):

make serve   # на :8000 — но на этом же порту dev Django; используйте только при необходимости

Шаг 2. Backend (Garden)

cd ../garden
uv sync                                # установить зависимости
python manage.py migrate                # применить миграции
python manage.py seed_report_templates  # создать шаблон отчёта по умолчанию
python manage.py runserver              # :8000

Создать суперпользователя:

python manage.py createsuperuser

Проверка: curl http://localhost:8000/api/schema/ должен вернуть OpenAPI-схему.

Celery в dev — синхронный режим

По умолчанию в development.py стоит CELERY_TASK_ALWAYS_EAGER=true — задачи выполняются прямо в HTTP-цикле, отдельный воркер запускать не нужно. Если хочется проверить асинхронный путь — выставить переменную окружения CELERY_TASK_ALWAYS_EAGER=false и поднять воркер: celery -A ng_metrics worker -l INFO. Брокер и результат — Redis DB 3 и 4 соответственно.

Шаг 3. Frontend

cd ../frontend
yarn install
cp .env.example .env.local              # настроить переменные
yarn dev                                 # :3000 (с Turbopack + Sentry Spotlight)

Откройте http://localhost:3000 — должен показать страницу входа.

Шаг 4. Telegram-бот (опционально)

Нужен только для проверки доставки уведомлений в Telegram.

cd ../bot
make app-run-db                          # стартовать PostgreSQL и Redis в Docker
cp .env.example .env.local
make run                                  # запустить бота локально (polling-режим)

Конфликт портов: если Garden занимает PostgreSQL на 54322 — для бота используйте отдельный контейнер из bot/docker-compose.yml.

Шаг 5. Туннели (для тестирования вебхуков)

Если работаете с вебхуками от Supabase Auth, Resend или Telegram — нужны публичные URL:

cd ../supabase
make tunnel

Tuna публикует:

Frontend: web-knotta.ru.tuna.am
Supabase API: service-knotta.ru.tuna.am
Backend API: api-knotta.ru.tuna.am
Bot: bot-knotta.ru.tuna.am

Сводная таблица портов

Сервис	Порт	Контекст
Frontend	3000	dev и prod
Backend dev	8000	dev
Backend prod	7000	prod (Docker)
Bot FastAPI	8080	dev и prod
Supabase API (Kong)	54321	local
PostgreSQL	54322	local
Supabase Studio	54323	local
Inbucket	54324	local
Storybook	6006	dev

Проверка работоспособности

Проверка	Команда / URL
Supabase Studio	`http://localhost:54323`
Inbucket (письма)	`http://localhost:54324`
Backend OpenAPI	`http://localhost:8000/api/schema/swagger-ui/`
Frontend	`http://localhost:3000`
Django Admin	`http://localhost:8000/admin/`

Команды разработки

Frontend

yarn dev                                  # dev-сервер
yarn build && yarn start
yarn check:types                          # tsc --noEmit
yarn lint:fix
yarn test                                  # Vitest
yarn test:e2e                              # Playwright
yarn storybook                             # :6006
yarn check:i18n                            # сравнить ru ↔ en по ключам

Garden (Django)

make lint                                 # ruff + mypy
make reformat                              # автоисправление
make test                                  # pytest
python manage.py makemigrations
python manage.py migrate
python manage.py shell_plus

Bot

make lint                                 # mypy + ruff
make app-run-db                           # PG + Redis
make run                                   # локально через UV
make app-build && make app-run            # всё в Docker
make app-logs                              # стрим логов

Supabase

make start
make stop
make migrate
make migrate:status
make serve                                 # Edge Functions локально

Частые проблемы

Симптом	Причина	Решение
`ConnectionRefused` к 54322	Supabase не стартовал	`cd supabase && make start && wait`
401 на `/api/...`	JWT истёк / не передан	Проверить `Authorization: Bearer`
`auth-sync` не сработала	Туннели выключены, Supabase не дошла до Django	Запустить `make tunnel` и обновить webhook URL в Supabase Studio
Email не приходит локально	Inbucket — это локальная ловушка для писем	Открыть `http://localhost:54324`
Не сгенерировался шаблон отчёта	Команда не запущена	`python manage.py seed_report_templates`
MJML не рендерится	`MJML_BACKEND_MODE` не настроен	Проверить `RESEND_API_KEY`, `MJML_BACKEND_MODE=cmd` в `.env` Garden
Уведомления не уходят, в логах нет упоминания backend.send	Воркер не запущен или `EAGER` выключен	Поставить `CELERY_TASK_ALWAYS_EAGER=true` для dev либо запустить воркер: `celery -A ng_metrics worker -l INFO`

Куда дальше

API — что вызывать и как.
Деплой — как разворачивать на проде.
Архитектура → Подсистема уведомлений — если меняете уведомления.