Инфраструктура

Тема

страница целиком, в Markdown — вставьте в чат с моделью

Чек-лист запуска ​

Используйте этот чек-лист для отслеживания прогресса при выводе нового сервиса от нуля до продакшена. Каждый пункт ссылается на соответствующую документацию, где это применимо.

Развёрнутая версия с готовыми файлами — Новый сервис: от репозитория до прода.

Репозиторий и структура проекта ​

  • [ ] 1. Создайте репозиторий в группе integrations. Используйте соглашение об именовании my-tool. Путь проекта в GitLab становится путём образа в registry, поэтому группа важна.

  • [ ] 2. Заведите три ветки — dev, stage, main. Пуши в остальные ветки пайплайн не запускают.

  • [ ] 3. Настройте структуру проекта в соответствии со стандартным расположением файлов для вашего стека.

    Структура для фронтенда
    my-tool/
├── src/
├── public/
├── index.html
├── package.json
├── nginx.conf
├── Dockerfile
├── .gitlab-ci.yml
└── nomad/
    ├── my-tool.nomad.hcl
    ├── vars-dev.hcl
    ├── vars-stage.hcl
    └── vars-prod.hcl
    Структура для full-stack
    my-tool/
├── frontend/
│   ├── src/
│   ├── nginx.conf
│   └── package.json
├── backend/
│   ├── src/
│   ├── migrations/
│   └── package.json
├── Dockerfile
├── .gitlab-ci.yml
└── nomad/
    ├── my-tool.nomad.hcl
    ├── vars-dev.hcl
    ├── vars-stage.hcl
    └── vars-prod.hcl

  • [ ] 4. Инициализируйте приложение — установите зависимости, создайте точку входа и убедитесь, что приложение запускается локально.

Артефакты деплоя ​

Полные примеры каждого файла смотрите на странице Файлы деплоя.

  • [ ] 5. Создайте Dockerfile — multi-stage сборка с правильными базовыми образами.

    • Фронтенд: node:20-alpine (сборка) → nginx:1.27-alpine (раздача)
    • Бэкенд: node:22-alpine (зависимости) → node:22-alpine + tini (продакшен)

  • [ ] 6. Создайте nginx.conf (если есть фронтенд) — SPA fallback, gzip, кэш /assets/ на 1 год, /index.html без кэша, /health возвращает 200.

  • [ ] 7. Создайте .gitlab-ci.yml — подключите .docker_build из meduza/infra, задайте REGISTRY_HOST: registry.amztop.io и DUAL_PUSH: "false", опишите три задачи деплоя через Nomad API. Каждой задаче — тег раннера new-server.

  • [ ] 8. Создайте Nomad job-файл (nomad/my-tool.nomad.hcl) — группы, constraint по meta.env, теги Traefik с env=${var.env} первым, health-проверки, блок update с канарейкой, consul {} для групп с шаблонами.

  • [ ] 9. Создайте Nomad vars-файлы — по одному на каждое окружение:

    • nomad/vars-dev.hcl
    • nomad/vars-stage.hcl
    • nomad/vars-prod.hcl

  • [ ] 10. Проверьте HCL до пуша — nomad job validate для каждой среды.

Конфигурация бэкенда (если применимо) ​

  • [ ] 11. Добавьте записи в Consul KV — один JSON-документ на среду по ключу my-tool/<env>/config. Как минимум:

    • port
    • database_url
    • node_env
    • log_level

  • [ ] 12. Выполните миграции базы данных, если бэкенд использует БД.

  • [ ] 13. Проверьте, что эндпоинт /health возвращает 200 OK — и только тогда, когда сервис действительно готов принимать запросы.

Dev-окружение ​

  • [ ] 14. Запушьте в ветку dev и убедитесь, что GitLab CI отработал успешно.

  • [ ] 15. Проверьте, что Docker-образ запушен в registry:

    bash
    curl -su <логин>:<токен> https://registry.amztop.io/v2/integrations/my-tool/backend/tags/list

  • [ ] 16. Проверьте, что Nomad job задеплоен — откройте Nomad UI (не забудьте переключить namespace) или выполните:

    bash
    nomad job status -namespace=dev my-tool

    Нужный результат: Deployment completed successfully, аллокации running и healthy.

  • [ ] 17. Проверьте, что health-проверки проходят в Consul UI или через:

    bash
    consul catalog services | grep my-tool

  • [ ] 18. Передайте домены на подключение — маршрутизация внешних имён настраивается централизованно. Пришлите строку вида my-tool — dev, stage, prod — dev-my-tool.amzhub.ai, stage-my-tool.amzhub.ai, my-tool.amzhub.ai.

  • [ ] 19. Проверьте доступность сервиса по адресу https://dev-my-tool.amzhub.ai — после того как домен подключён.

Stage-окружение ​

  • [ ] 20. Смержите в ветку stage и убедитесь, что CI задеплоил сервис.

  • [ ] 21. Проверьте доступность сервиса по адресу https://stage-my-tool.amzhub.ai.

  • [ ] 22. Проведите базовое smoke-тестирование — пройдите основные пользовательские сценарии и проверьте API-эндпоинты.

Продакшен ​

  • [ ] 23. Смержите в main и запустите ручной deploy job в GitLab CI — прод выкатывается только по кнопке.

  • [ ] 24. Проверьте доступность сервиса по адресу https://my-tool.amzhub.ai.

  • [ ] 25. Проверьте TLS — убедитесь, что сертификат валиден и выдан Let's Encrypt:

    bash
    curl -vI https://my-tool.amzhub.ai 2>&1 | grep "subject:"

  • [ ] 26. Проверьте health-проверки в Consul.

  • [ ] 27. Проверьте маршрутизацию Traefik — убедитесь, что фронтенд и бэкенд (если применимо) отвечают по правильным путям.

  • [ ] 28. Мониторьте логи первые несколько минут после деплоя:

    bash
    nomad alloc logs -namespace=prod -f <alloc-id>

После запуска ​

  • [ ] 29. Добавьте сервис во внутренний каталог инструментов / лендинг, если применимо.

  • [ ] 30. Оповестите команду о том, что новый сервис запущен.

WARNING

Не пропускайте stage-окружение. Проблемы, обнаруженные на stage, обходятся значительно дешевле, чем проблемы в продакшене.

Документация по инфраструктуре