Документ можно переслать исполнителю как есть.
Связанная общая схема: https://mdview.io/s/showcase.
Цель: среда, в которой фронт и дизайнер по кнопке получаютhttps://showcase.test.ru/content/<unique-id>/
из репозитория + ветки GitLab, а панель доступна под паролем наhttps://showcase.test.ru/.
Инструмент разработки у команды: Claude Code. Delivery его не настраивает (кроме доступов GitLab); скиллы ставит фронт/дизайнер.
showcase.json без фронта.Блокер для интеграции панели. Можно параллельно с этапом B.
https://git.agency.ru (self-hosted или gitlab.com).| Группа | Назначение |
|---|---|
agency-tooling |
Панель, скиллы, infra-репо |
agency-templates |
Шаблоны типов проектов |
clients (или по брендам) |
Боевые проекты |
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.
После того как фронт положит код в agency-templates/*:
agency-tooling/GITLAB.md: как создать новый клиентский проект.| Аккаунт | Роли |
|---|---|
| Фронт | Maintainer: agency-tooling, agency-templates; Maintainer/Developer: clients |
| Дизайнер | Developer на нужные clients/*; Reporter минимум на templates |
showcase-bot |
Сервисный для панели: API + clone |
Для панели / worker выдать фронту и прописать в .env на сервере:
showcase-bot:read_apiread_repositoryclients и agency-templatesНа шаблонах: main — только Maintainer.
GITLAB.mdВ agency-tooling: URL, группы, создание из template, куда писать при 403.
Критерий готовности A: фронт clone/push в showcase-panel и claude-skills; дизайнер clone проекта из template; токеном бота через API видны проекты и ветки.
Блокер для публичных ссылок клиенту.
deploy с docker + docker compose plugin.A/AAAA showcase.test.ru → IP сервера.showcase.test.ru.Создать заранее:
/var/showcase/
content/ # раздача /content/<id>/
work/ # временные clone + build
data/ # БД панели (volume)
logs/
/opt/showcase/
panel/ # compose, .env
content/ и work/.content/.Критерий готовности B: HTTPS на showcase.test.ru живой; каталоги есть; docker у deploy работает.
Фронт поставляет код и образ. Delivery раскатывает в порядке ниже.
| Сервис | Зачем | Когда |
|---|---|---|
| PostgreSQL (или SQLite volume — как скажет фронт в README) | Метаданные деплоев, users | До панели |
| Redis (рекомендуется) | Очередь build-job | До worker; на MVP фронт может разрешить без Redis |
| nginx (или Traefik) | TLS, маршруты | До публикации URL |
| Container Registry | Образ панели | Предпочтительно GitLab Container Registry |
Отдельный Harbor не поднимать без нужды.
Репо agency-tooling/showcase-panel содержит:
Dockerfiledocker-compose.yml (panel ± worker).env.exampleREADME-DEPLOY.md (обязателен к приёмке)Действия delivery:
docker build → push в Registry, теги: showcase-panel:main и semver / YYYYMMDD./opt/showcase/panel/.env из example (см. список переменных ниже).docker compose pull && docker compose up -d.Когда обновлять: каждый релиз фронта → 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 фронта; таблица выше — чеклист смысла.
Без worker кнопка Deploy бесполезна.
Worker должен:
git clone ветки по токену.showcase.json.preview.install → preview.build.preview.outDir → /var/showcase/content/<unique-id>/.Node: одна зафиксированная с фронтом LTS (20 или 22). Пакетный менеджер в шаблонах — npm (одна политика).
Предпочтительная схема (если фронт описал в README):
node:22 с mount work/ + content/ (изоляция).Псевдосхема (точный конфиг — по 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 клиенту».
Чек-лист (оба присутствуют):
designer и front.prototype → ready → файлы в /var/showcase/content/<id>/.build:preview → ошибка и лог видны в панели.work/ / старых draft не сносит published без подтверждения.Критерий D = MVP инфраструктуры сдан.
twig-embed и static-promo.GITLAB.md.clients/pilot-static и clients/pilot-twig.| Событие | Действие |
|---|---|
| Релиз панели | build/push image → compose pull/up |
| Новый сотрудник | GitLab user + роль панели; скиллы Claude Code ставит фронт по своей инструкции |
| Диск полный | чистка work/, старых draft; эскалация по published |
| Утечка токена | ротация GITLAB_TOKEN, AUTH_SECRET |
| Новый тип шаблона | репо в agency-templates/*, те же права |
| Фаза 2: deliver zip / S3 | место на диске или bucket — по запросу фронта |
Без этого delivery не угадывает env и nginx:
Dockerfile + docker-compose.yml.env.example с описанием каждой переменнойREADME-DEPLOY.md: порты, healthcheck, поведение draft/publish для nginxshowcase.json, коды ошибокclients/pilot-* с зелёным npm run build:previewНеделя 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) по мере проектов
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 может добавить кнопку в панели).
Среда стабильно превращает «репо + ветка» в URLhttps://showcase.test.ru/content/<id>/.
Обновление панели = смена Docker-образа без ручной правки кода на сервере.