Учебное руководство
Главы руководства
На этой странице

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

Оглавление · Далее: архитектура

Что требуется

  • Node.js 24.x. Предпочтительна актуальная версия ветки 24 LTS.
  • pnpm 12.8.1 — версия закреплена в корневом packageManager.
  • Docker Engine или Docker Desktop с работающим Compose.
  • Git; для работы с GitHub дополнительно удобен gh, но локальный запуск его не требует.

Проверка окружения:

node --version
pnpm --version
docker version
docker compose version

docker version должен показывать не только Client, но и доступный Server. На macOS Docker Desktop или другой Docker daemon нужно запустить заранее. Production-override использует YAML-тег !reset: нужен Compose, который его поддерживает.

Если pnpm отсутствует, один из способов установки:

npm install --global pnpm@12.8.1

Не устанавливайте зависимости Strapi через корневой pnpm: это самостоятельный npm-проект, его стандартный запуск в этом репозитории выполняется через Docker.

Режим 1: Next на хосте, CMS и S3 в Docker

Без CMS можно выполнять typecheck и unit tests. Для build нужна CMS; полная изолированная проверка доступна через node scripts/check-static-site.mjs. Для host Next используйте Docker CMS/S3:

pnpm install --frozen-lockfile
pnpm setup
pnpm infra:up
pnpm cms:up
pnpm cms:token
pnpm cms:snapshot
pnpm cms:dry-run
pnpm cms:import
pnpm dev

Сайт — http://localhost:3000; CMS — http://127.0.0.1:1337/admin. Создайте администратора при первом открытии CMS. Read-only token хранится только в корневом .env; next.config читает его через process.loadEnvFile, а не через передаваемый дочерним процессам Node flag.

Публикация записи через Content Manager меняет сайт после обновления страницы. Импорт — явная одноразовая команда: старые редакторские правки по sourceId сохраняются. Описание snapshots, dry-run и безопасного повторного запуска — в CMS.

Режим 2: сайт и воркер на хосте, инфраструктура в Docker

Терминал A:

pnpm install --frozen-lockfile
pnpm setup
pnpm infra:up
docker compose exec -T hatchet /hatchet-admin seed --config /config
pnpm infra:token
pnpm cms:up
pnpm cms:token
pnpm cms:snapshot
pnpm cms:import
pnpm dev

Явный seed нужен для первичной инициализации пользователя и обычного tenant Hatchet на новой базе. Запуск Lite и наличие HTTP-панели сами по себе не доказывают, что рабочий tenant создан. Команда seed с обычной конфигурацией повторно использует уже существующие записи. Production выполняет этот шаг отдельным Python-скриптом.

Терминал B:

pnpm dev:functions

Ожидайте сообщение о подключении воркера gheilt-functions к Hatchet. Панель Hatchet доступна на http://localhost:8888. Стандартный локальный seed использует admin@example.com / Admin123!!; это только локальный учебный аккаунт. Production использует отдельные случайные секреты и дополнительную аутентификацию.

pnpm setup создаёт .env с правами 600 и случайными секретами. Существующий файл не перезаписывается. Токен Hatchet сначала пуст: infra:token получает его после seed. Если ранее была собственная конфигурация Hatchet или tenant, смотрите диагностику токена.

Режим 3: весь стек в Docker

После setup, infra:up, seed и infra:token:

pnpm cms:up
pnpm cms:token
pnpm cms:snapshot
pnpm cms:import
pnpm stack:up
ЧтоАдрес
Сайтhttp://localhost:8080
Strapihttp://cms.localhost:8080/admin
Hatchethttp://localhost:8888

При первом открытии Strapi создайте администратора CMS. Этот аккаунт отличается от аккаунта Hatchet. Если cms.localhost не разрешается в вашем окружении, проверьте DNS/hosts; для HTTP-проверки можно явно указать адрес:

curl --resolve cms.localhost:8080:127.0.0.1 http://cms.localhost:8080/admin

stack:up включает Compose profile app, собирает образы и ждёт healthcheck. Первый запуск Strapi заметно дольше запуска Next.js: собираются CMS и её admin UI. Обычный pnpm dev и Docker-сайт могут работать одновременно на портах 3000 и 8080, но не запускайте второй воркер без намерения увеличить число исполнителей.

Первая проверка

curl --fail http://localhost:3000/api/health
curl --fail http://localhost:3000/api/trpc/news.list

Для Docker-сайта замените 3000 на 8080. Health возвращает {"status":"ok"}. Ответ tRPC содержит объект result.data со списком новостей. Проверка health подтверждает ответ Next.js, но не выполнение фоновой задачи.

Отправка учебного события без вывода секрета в терминал:

node --env-file=.env --input-type=module <<'JS'
const response = await fetch('http://localhost:3000/api/webhooks/strapi', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    authorization: `Bearer ${process.env.STRAPI_WEBHOOK_SECRET}`,
  },
  body: JSON.stringify({
    event: 'entry.update', model: 'news', entry: { documentId: 'learning-demo' },
  }),
});
console.log(response.status, await response.text());
JS

Ожидаемый ответ — 200 и {"revalidated":true}. Откройте страницу заново: Next.js обновит статический HTML из CMS. Этот webhook не запускает Hatchet worker.

Остановка и обычный рабочий цикл

Для процессов в терминалах — Ctrl+C. Для контейнеров:

pnpm stack:down

Тома сохраняются. Команда с down -v удалила бы данные — она не нужна для обычной остановки. Следующий stack:up поднимет сохранённые базы и файлы.

pnpm check
git status --short
git diff
git add <изменённые-файлы>
git commit -m '<описание-завершённого-этапа>'

Последние три строки — шаблон, замените значения в угловых скобках. Push в main запускает реальный деплой; учебные эксперименты делайте в отдельной ветке.

Где смотреть код