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

Начало

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

Оглавление

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

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

Для первой установки выберите инструкции своей ОС: Node.js 24, Git для macOS, Windows и Linux, Docker Desktop для macOS/Windows/Linux или Docker Engine для Linux. После установки откройте новый терминал. На Windows используйте среду WSL 2 с Linux-терминалом: команды руководства рассчитаны на Unix shell. Установка WSL.

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

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.

Получить проект и выбрать каталог

SSH-адрес ниже соответствует основному remote проекта. Для клонирования настройте SSH-ключ в своём аккаунте SourceCraft; текущий адрес и альтернативный HTTPS-способ берите из кнопки клонирования репозитория. Ошибку Permission denied (publickey) решают настройкой SSH, а не сменой файлов проекта.

mkdir -p ~/projects
cd ~/projects
git clone ssh://git@ssh.sourcecraft.dev/zakharov-dev/gheilt.git
cd gheilt
pwd
git status --short --branch

pwd должен заканчиваться на /projects/gheilt; ls показывает package.json, apps, docs и compose.yaml. Откройте этот каталог в редакторе через «Открыть папку». Перед первым изменением создайте собственную ветку и worktree по Git-главе. Установку зависимостей и дальнейшие команды выполняйте из корня выбранного worktree; в терминале редактора также проверьте pwd.

Режим 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:external
pnpm cms:dry-run --snapshot var/content-import/external.json
pnpm cms:import --snapshot var/content-import/external.json
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

После pnpm setup и pnpm infra:up:

pnpm cms:up
pnpm cms:token
pnpm cms:snapshot:external
pnpm cms:import --snapshot var/content-import/external.json
pnpm stack:up
ЧтоАдрес
Сайтhttp://localhost:8080
Strapihttp://cms.localhost:8080/admin

Если cms.localhost не разрешается, проверьте DNS/hosts:

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, при условии, что один экземпляр CMS обслуживает оба приложения.

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

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; готовность контента проверяет /api/content-health.

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

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

Ожидаемый ответ webhook — 200 и {"revalidated":true}. При следующем посещении Next.js обновит HTML из CMS.

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

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

pnpm stack:down

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

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

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

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

Команды внешнего импорта выше сохранены как исторический ручной путь. Автоматические полные стенды используют опубликованную текущую CMS и Garage: инструкция.