Showcase — ТЗ для Delivery (devops)

Документ можно переслать исполнителю как есть.
Связанная общая схема: https://mdview.io/s/showcase.

Цель: среда, в которой фронт и дизайнер по кнопке получают
https://showcase.test.ru/content/<unique-id>/
из репозитория + ветки GitLab, а панель доступна под паролем на
https://showcase.test.ru/.

Инструмент разработки у команды: Claude Code. Delivery его не настраивает (кроме доступов GitLab); скиллы ставит фронт/дизайнер.


0. Зона ответственности

Delivery делает

Delivery не делает


1. Этап A — GitLab (сделать первым)

Блокер для интеграции панели. Можно параллельно с этапом B.

1.1. Инстанс

1.2. Группы

Группа Назначение
agency-tooling Панель, скиллы, infra-репо
agency-templates Шаблоны типов проектов
clients (или по брендам) Боевые проекты

1.3. Создать пустые репозитории

Owner/настройка — delivery; Maintainer на код — фронт:

Репо Назначение
agency-tooling/showcase-panel Nuxt-панель + Dockerfile
agency-tooling/claude-skills Скиллы Claude Code
agency-templates/twig-embed Шаблон типа twig+S3
agency-templates/static-promo Шаблон лендов

Позже по запросу фронта: vue-pixi, site, fullstack.

1.4. Project Templates

После того как фронт положит код в agency-templates/*:

1.5. Пользователи и роли

Аккаунт Роли
Фронт Maintainer: agency-tooling, agency-templates; Maintainer/Developer: clients
Дизайнер Developer на нужные clients/*; Reporter минимум на templates
showcase-bot Сервисный для панели: API + clone

1.6. Токены (секреты, не в git)

Для панели / worker выдать фронту и прописать в .env на сервере:

1.7. Protected branches

На шаблонах: main — только Maintainer.

1.8. Документ GITLAB.md

В agency-tooling: URL, группы, создание из template, куда писать при 403.

Критерий готовности A: фронт clone/push в showcase-panel и claude-skills; дизайнер clone проекта из template; токеном бота через API видны проекты и ветки.


2. Этап B — Сервер и домен

Блокер для публичных ссылок клиенту.

2.1. VPS

2.2. DNS и TLS

2.3. Firewall

2.4. Каталоги на сервере

Создать заранее:

/var/showcase/
  content/     # раздача /content/<id>/
  work/        # временные clone + build
  data/        # БД панели (volume)
  logs/
/opt/showcase/
  panel/       # compose, .env

Критерий готовности B: HTTPS на showcase.test.ru живой; каталоги есть; docker у deploy работает.


3. Этап C — Что и когда разворачивать

Фронт поставляет код и образ. Delivery раскатывает в порядке ниже.

3.1. C1 — Инфра до первого образа панели (один раз)

Сервис Зачем Когда
PostgreSQL (или SQLite volume — как скажет фронт в README) Метаданные деплоев, users До панели
Redis (рекомендуется) Очередь build-job До worker; на MVP фронт может разрешить без Redis
nginx (или Traefik) TLS, маршруты До публикации URL
Container Registry Образ панели Предпочтительно GitLab Container Registry

Отдельный Harbor не поднимать без нужды.

3.2. C2 — Образ панели (поставляет фронт)

Репо agency-tooling/showcase-panel содержит:

Действия delivery:

  1. CI GitLab (или согласованный ручной build):
    docker build → push в Registry, теги: showcase-panel:main и semver / YYYYMMDD.
  2. На сервере /opt/showcase/panel/.env из example (см. список переменных ниже).
  3. docker compose pull && docker compose up -d.
  4. Проверить healthcheck панели.

Когда обновлять: каждый релиз фронта → pull + up. Откат = предыдущий тег образа.

Переменные окружения (минимум)

Переменная Смысл
GITLAB_URL URL инстанса
GITLAB_TOKEN токен showcase-bot
GITLAB_GROUP_IDS / пути групп clients, agency-templates
DATABASE_URL или путь SQLite БД панели
REDIS_URL если есть очередь
CONTENT_ROOT /var/showcase/content
WORK_ROOT /var/showcase/work
PUBLIC_BASE_URL https://showcase.test.ru
AUTH_SECRET / пароли users логин панели

Точные имена — из .env.example фронта; таблица выше — чеклист смысла.

3.3. C3 — Build worker (одновременно с первой панелью)

Без worker кнопка Deploy бесполезна.

Worker должен:

  1. git clone ветки по токену.
  2. Прочитать showcase.json.
  3. Выполнить preview.install → preview.build.
  4. Скопировать preview.outDir → /var/showcase/content/<unique-id>/.
  5. Вернуть статус + лог в панель.
  6. Таймаут сборки ~10 мин; параллельность 1–2 job на старте.

Node: одна зафиксированная с фронтом LTS (20 или 22). Пакетный менеджер в шаблонах — npm (одна политика).

Предпочтительная схема (если фронт описал в README):

3.4. C4 — nginx маршруты

Псевдосхема (точный конфиг — по README-DEPLOY.md фронта):

https://showcase.test.ru/
  → reverse_proxy на panel (например :3000)

https://showcase.test.ru/content/<id>/
  → файлы из /var/showcase/content/<id>/

Draft:
  → доступ только авторизованным
  (auth_request к panel /api/auth/check
   ИЛИ раздача draft через Nuxt — как опишет фронт)

Published:
  → публично без пароля

Когда: до объявления дизайнеру «можно Publish клиенту».


4. Этап D — Приёмка с фронтом

Чек-лист (оба присутствуют):

  1. Логин в панель под designer и front.
  2. В списке виден тестовый проект из template.
  3. Deploy ветки prototype → ready → файлы в /var/showcase/content/<id>/.
  4. URL открывается; draft снаружи закрыт; после Publish открыт без логина.
  5. Вторая выкладка = новый id; старый не затёрт.
  6. Падающий build:preview → ошибка и лог видны в панели.
  7. Очистка work/ / старых draft не сносит published без подтверждения.

Критерий D = MVP инфраструктуры сдан.


5. Этап E — Шаблоны и пилот

  1. Фронт пушит код в twig-embed и static-promo.
  2. Delivery включает Template + обновляет GITLAB.md.
  3. Создать clients/pilot-static и clients/pilot-twig.
  4. Дизайнеру — доступ только на пилоты.
  5. Регламент: новый клиентский проект только из template.

6. Этап F — Эксплуатация

Событие Действие
Релиз панели build/push image → compose pull/up
Новый сотрудник GitLab user + роль панели; скиллы Claude Code ставит фронт по своей инструкции
Диск полный чистка work/, старых draft; эскалация по published
Утечка токена ротация GITLAB_TOKEN, AUTH_SECRET
Новый тип шаблона репо в agency-templates/*, те же права
Фаза 2: deliver zip / S3 место на диске или bucket — по запросу фронта

7. Артефакты от фронта ДО этапа C2

Без этого delivery не угадывает env и nginx:


8. Таймлайн

Неделя 1:  Этап A (GitLab) + B (VPS/DNS/TLS)
           Фронт параллельно: каркас панели + showcase.json + claude-skills

Неделя 2:  Этап C (registry, БД/Redis, образ, nginx, worker)
           Фронт: шаблоны twig-embed + static-promo

Неделя 3:  Этап D приёмка + E пилот с дизайнером

Далее:     Этап F + новые шаблоны (vue-pixi / site / fullstack) по мере проектов

9. Контракт, который ест worker (showcase.json)

Для справки при отладке сборок:

{
  "name": "project-name",
  "type": "twig-embed",
  "preview": {
    "install": "npm ci",
    "build": "npm run build:preview",
    "outDir": "dist/preview",
    "runtime": "static"
  },
  "deliver": {
    "build": "npm run build:deliver",
    "outDir": "dist/deliver"
  }
}

На MVP worker выполняет только блок preview. Блок deliver — зона фронта (фаза 2 может добавить кнопку в панели).


10. Критерий успеха для Delivery

Среда стабильно превращает «репо + ветка» в URL
https://showcase.test.ru/content/<id>/.
Обновление панели = смена Docker-образа без ручной правки кода на сервере.