ss-tools/docs/enterprise-clean.md

Enterprise Clean Deployment (internal-only)

Для разворота в корпоративной сети используйте профиль enterprise clean:

• очищенный дистрибутив без test/demo/load-test данных;
• запрет внешних интернет-источников;
• загрузка ресурсов только с внутренних серверов компании;
• обязательная блокирующая проверка clean/compliance перед выпуском.

Операционный workflow (CLI/API/TUI)

1) Headless flow через CLI (рекомендуется для CI/CD)

cd backend

# 1. Регистрация кандидата
.venv/bin/python3 -m src.scripts.clean_release_cli candidate-register \
  --candidate-id 2026.03.09-rc1 \
  --version 1.0.0 \
  --source-snapshot-ref git:release/2026.03.09-rc1 \
  --created-by release-operator

# 2. Импорт артефактов
.venv/bin/python3 -m src.scripts.clean_release_cli artifact-import \
  --candidate-id 2026.03.09-rc1 \
  --artifact-id artifact-001 \
  --path backend/dist/package.tar.gz \
  --sha256 deadbeef \
  --size 1024

# 3. Сборка манифеста
.venv/bin/python3 -m src.scripts.clean_release_cli manifest-build \
  --candidate-id 2026.03.09-rc1 \
  --created-by release-operator

# 4. Запуск compliance
.venv/bin/python3 -m src.scripts.clean_release_cli compliance-run \
  --candidate-id 2026.03.09-rc1 \
  --actor release-operator

2) API flow (автоматизация через сервисы)

• V2 candidate/artifact/manifest API:
  • POST /api/clean-release/candidates
  • POST /api/clean-release/candidates/{candidate_id}/artifacts
  • POST /api/clean-release/candidates/{candidate_id}/manifests
  • GET /api/clean-release/candidates/{candidate_id}/overview
• Legacy compatibility API (оставлены для миграции клиентов):
  • POST /api/clean-release/candidates/prepare
  • POST /api/clean-release/checks
  • GET /api/clean-release/checks/{check_run_id}

3) TUI flow (тонкий клиент поверх facade)

cd /home/busya/dev/superset-tools
./run_clean_tui.sh 2026.03.09-rc1

Горячие клавиши:

• F5: Run Compliance
• F6: Build Manifest
• F7: Reset Draft
• F8: Approve
• F9: Publish
• F10: Refresh Overview

Важно: TUI требует валидный TTY. Без TTY запуск отклоняется с инструкцией использовать CLI/API.

Типовые внутренние источники:

• repo.intra.company.local
• artifacts.intra.company.local
• pypi.intra.company.local

Если найден внешний endpoint, выпуск получает статус BLOCKED до исправления.

Docker release для изолированного контура

Текущий enterprise clean профиль уже задаёт policy-level ограничения для внутреннего контура. Следующий логичный шаг для релизного процесса — выпускать не только application artifacts, но и готовый Docker bundle для разворота без доступа в интернет.

Целевой состав offline release-пакета:

• backend image с уже установленными Python-зависимостями;
• frontend image с уже собранным SvelteKit bundle;
• postgres image или внутренний pinned base image;
• docker-compose.enterprise-clean.yml для запуска в air-gapped окружении;
• .env.enterprise-clean.example с обязательными переменными;
• manifest с версиями, sha256 и перечнем образов;
• инструкции по docker load / docker compose up без обращения к внешним registry.

Рекомендуемый workflow для такого релиза:

# 1. Собрать образы в подключённом контуре
./build.sh bundle v1.0.0-rc2-docker

# Результат: dist/docker/
#   backend.v1.0.0-rc2-docker.tar.xz
#   frontend.v1.0.0-rc2-docker.tar.xz
#   postgres.v1.0.0-rc2-docker.tar.xz
#   manifest + sha256sums + docker-compose.enterprise-clean.yml + .env.enterprise-clean.example

# 2. Передать dist/docker/* в изолированный контур
# 3. Импортировать образы локально (распаковка на лету)
xz -dc dist/docker/backend.v1.0.0-rc2-docker.tar.xz | docker load
xz -dc dist/docker/frontend.v1.0.0-rc2-docker.tar.xz | docker load
xz -dc dist/docker/postgres.v1.0.0-rc2-docker.tar.xz | docker load

# 4. Подготовить env из шаблона
cp dist/docker/.env.enterprise-clean.example .env.enterprise-clean

# 4a. Для первого запуска задать bootstrap администратора
# INITIAL_ADMIN_CREATE=true
# INITIAL_ADMIN_USERNAME=<org-admin-login>
# INITIAL_ADMIN_PASSWORD=<temporary-strong-secret>

# 5. Запустить только локальные образы
docker compose --env-file .env.enterprise-clean -f dist/docker/docker-compose.enterprise-clean.yml up -d

Для легковесного all-in-one образа (без Playwright, ~104 MB вместо 575 MB):

# Сборка
./build.sh bundle:light v1.0.0

# Результат:
#   dist/docker/superset-tools.v1.0.0.tar.xz  (×5.5 меньше за счёт xz -9)
#   dist/docker/docker-compose.light.yml
#   dist/docker/manifest-light.v1.0.0.txt
#   dist/docker/sha256sums-light.v1.0.0.txt

# Загрузка и запуск:
xz -dc dist/docker/superset-tools.v1.0.0.tar.xz | docker load
docker compose -f dist/docker/docker-compose.light.yml up

Bootstrap администратора выполняется entrypoint-скриптом внутри backend container:

• если INITIAL_ADMIN_CREATE=true, контейнер вызывает create_admin.py перед стартом API;
• если администратор уже существует, учётная запись не меняется;
• теги в .env.enterprise-clean.example должны совпадать с фактически загруженными образами superset-tools-backend:v1.0.0-rc2-docker и superset-tools-frontend:v1.0.0-rc2-docker;
• после первого входа пароль должен быть ротирован, а INITIAL_ADMIN_CREATE возвращён в false.

Ограничения для production-grade offline release:

• build не должен тянуть зависимости в изолированном контуре;
• все base images должны быть заранее зеркалированы во внутренний registry или поставляться как tar;
• runtime-конфигурация не должна ссылаться на внешние API/registry/telemetry endpoints;
• clean/compliance manifest должен включать docker image digests как часть evidence package.

Практический план внедрения:

• pinned Docker image tags и отдельный enterprise-clean compose profile добавлены;
• unified build.sh bundle <tag> добавлен для build -> save -> checksum (заменил scripts/build_offline_docker_bundle.sh);
• следующим шагом стоит включить docker image digests в clean-release manifest;
• следующим шагом стоит добавить smoke-check, что compose-файлы не содержат внешних registry references вне allowlist.