Перейти к основному содержимому

Локальный запуск

Полный пошаговый рецепт первого запуска живёт в корневом README.md — здесь только рабочий цикл разработки и грабли, на которые наступают повторно.

Рабочий цикл: инфраструктура в Docker, backend на хосте​

Для разработки backend Docker-образ не пересобирают. Пересборка образа — только для smoke-проверки всего compose-пакета.

cp .env.example .env
cp apps/backend/.env.template apps/backend/.env   # обязательно, см. ниже
npm install

docker compose up -d postgres redis meilisearch minio minio-init

cd apps/backend && npx medusa db:migrate --execute-safe-links && cd ../..
npm run backend:dev                                # http://localhost:9000, админка /app
npm run dev -w @auto-paint-store/web -- --port 3100 # витрина

Порты всех сервисов проброшены наружу (docker-compose.override.yml), поэтому backend с хоста видит контейнерные postgres/redis/meilisearch/minio.

:::danger apps/backend/.env — отдельный файл, и он обязателен Команды Medusa CLI (db:migrate, medusa user) запускаются с хоста и читают конфигурацию из apps/backend, не из корневого .env. В свежем git worktree этого файла нет — только .env.template. Без него DATABASE_URL уходит в несуществующую БД, а отсутствующий MEDUSA_FF_RBAC тихо пропускает миграцию RBAC. Симптом — падающие тесты, никак не связанные с тем, что вы правите. :::

Проверки​

npm run build                                      # сборка всех workspace
npm run lint
npm run test:unit -w @dtc/backend                  # jest
npm run test:integration:http -w @dtc/backend
npm run test:integration:modules -w @dtc/backend
npm run test -w @auto-paint-store/web              # node:test
npm run build -w @auto-paint-store/web             # next build

Один тест — из apps/backend, с TEST_TYPE=unit и NODE_OPTIONS=--experimental-vm-modules:

npx jest --runInBand path/to/file.spec.ts

:::warning Unit-тесты не заменяют сборку Зелёные unit-тесты пропускали падение next build на типах. Перед приёмкой работы всегда прогоняйте настоящую сборочную команду приложения. :::

Демо-каталог​

npm run backend:seed (src/scripts/seed-commerce.ts) наполняет магазин демо-товарами и создаёт собственный sales channel «Auto Paint Storefront». Это ручной шаг для разработки и демо, не часть автонастройки: на боевом развёртывании новой компании его запускать не нужно.

Что делать, если​

migrate в compose завис на «Running migrations...». Это одноразовый сервис, который гейтит старт backend; он умеет виснуть независимо от ваших изменений. Не расследуйте — мигрируйте с хоста (npx medusa db:migrate из apps/backend) и поднимайте backend отдельно.

Ошибка relation ... does not exist на старте backend. Рантайм-образ схему не мигрирует (npm run start, без auto-migrate). Прогоните миграции до старта.

Ошибка site_link does not exist на локальных миграциях — вероятно, загрязнённая БД, см. docs/known-quirks.md.

Store API падает по CORS при проверке витрины. STORE_CORS разрешает конкретно http://localhost:8000, а не http://127.0.0.1:8000. Открывайте через localhost. В браузерной автоматизации это выглядит как статус 503 или зависшая загрузка, а не как явная ошибка CORS.