# Установка и настройка ss-tools

Эта документация описывает процесс установки и настройки ss-tools для локальной разработки и продакшн-среды.

## Содержание

- [Требования](#требования)
- [Установка через Docker](#установка-через-docker)
- [Offline Docker Bundle](#offline-docker-bundle)
- [Локальная установка](#локальная-установка)
- [Первая настройка](#первая-настройка)
- [Конфигурация окружений](#конфигурация-окружений)
- [Troubleshooting](#troubleshooting)

## Требования

### Минимальные требования для локальной разработки

- **Python**: 3.9 или новее
- **Node.js**: 18 или новее
- **npm**: 9 или новее
- **RAM**: 4 GB
- **Диск**: 5 GB свободного места
- **Операционная система**: Linux, macOS или WSL2

### Рекомендуемые требования для продакшн

- **Docker Engine**: 24 или новее
- **Docker Compose**: v2.3 или новее
- **RAM**: 8 GB
- **Диск**: 15+ GB свободного места
- **PostgreSQL**: 16 (через Docker)

### Дополнительные зависимости

Для локальной разработки могут потребоваться:

- **Git**: для клонирования репозитория
- **Curl**: для тестирования API
- **Python-разработчик**: для компиляции некоторых Python пакетов

## Установка через Docker

### 1. Клонирование репозитория

```bash
git clone <repository-url>
cd ss-tools
```

### 2. Настройка переменных окружения

Создайте файл `.env` в корневой директории:

```bash
# Backend и Frontend порты
BACKEND_PORT=8000
FRONTEND_PORT=5173

# PostgreSQL порт
POSTGRES_HOST_PORT=5432

# Альтернативные образы PostgreSQL (если есть проблемы с основным)
POSTGRES_IMAGE=postgres:16-alpine

# Порты для Docker контейнеров
BACKEND_HOST_PORT=8001
FRONTEND_HOST_PORT=8000
```

### 3. Запуск контейнеров

```bash
# Сборка и запуск всех сервисов
docker compose up --build

# Запуск в фоне с логами
docker compose up -d

# Мониторинг логов
docker compose logs -f
```

### 4. Проверка установки

После запуска проверьте доступность сервисов:

```bash
# Frontend
curl http://localhost:8000

# Backend API
curl http://localhost:8001/docs

# PostgreSQL
docker exec ss_tools_db pg_isready -U postgres
```

## Локальная установка

### 1. Backend установка

```bash
cd backend

# Создание виртуального окружения
python3 -m venv .venv

# Активация виртуального окружения
source .venv/bin/activate  # На Linux/macOS
# или
.venv\Scripts\activate  # На Windows

# Установка зависимостей
pip install -r requirements.txt

# Запуск backend
python3 -m uvicorn src.app:app --reload --port 8000
```

### 2. Frontend установка

Откройте новый терминал:

```bash
cd frontend

# Установка зависимостей
npm install

# Запуск dev сервера
npm run dev -- --port 5173
```

### 3. Настройка PostgreSQL

Для локальной разработки можно использовать встроенную PostgreSQL или подключиться к существующей:

```bash
# Создание БД (если не создана через Docker)
createdb ss_tools

# Или подключение к существующей
psql -U postgres -d ss_tools
```

## Offline Docker Bundle

Этот режим предназначен для enterprise clean-развёртывания в контуре без доступа к внешнему интернету.

### 1. Сборка bundle в подключённом контуре

```bash
cd /home/busya/dev/ss-tools
./scripts/build_offline_docker_bundle.sh v1.0.0-rc2
```

Результат появится в `dist/docker/`:
- `backend.v1.0.0-rc2.tar`
- `frontend.v1.0.0-rc2.tar`
- `postgres.v1.0.0-rc2.tar`
- `sha256sums.v1.0.0-rc2.txt`
- `manifest.v1.0.0-rc2.txt`
- `docker-compose.enterprise-clean.yml`
- `.env.enterprise-clean.example`

### 2. Перенос bundle в изолированный контур

Передайте каталог `dist/docker/` во внутреннюю сеть любым утверждённым способом.

### 3. Импорт образов

```bash
docker load -i backend.v1.0.0-rc2.tar
docker load -i frontend.v1.0.0-rc2.tar
docker load -i postgres.v1.0.0-rc2.tar
```

### 4. Подготовка конфигурации

```bash
cp .env.enterprise-clean.example .env.enterprise-clean
```

Минимально проверьте:
- `BACKEND_IMAGE`
- `FRONTEND_IMAGE`
- `POSTGRES_IMAGE`
- `POSTGRES_PASSWORD`
- `STORAGE_ROOT`

### 5. Запуск в offline-контуре

```bash
docker compose --env-file .env.enterprise-clean -f docker-compose.enterprise-clean.yml up -d
```

Compose-файл использует `pull_policy: never`, поэтому runtime не должен обращаться к внешним registry.

## Первая настройка

### 1. Инициализация базы данных

```bash
cd backend
source .venv/bin/activate

# Создание таблиц
python src/scripts/init_auth_db.py
```

### 2. Создание администратора

```bash
python src/scripts/create_admin.py --username admin --password admin
```

**Важно**: После создания администратора измените пароль в продакшн-среде!

### 3. Настройка окружений

Перейдите в админ-панель (http://localhost:8000/settings) и добавьте свои Superset окружения:

- **Source Environment**: окружение для миграции данных
- **Target Environment**: целевое окружение
- **Superset URL**: базовый URL Superset (например, https://superset.example.com)
- **API URL**: URL API Superset (обычно /api/v1)
- **Auth Type**: Basic Auth или OAuth2

### 4. Настройка Git-конфигураций

Если планируете использовать Git-интеграцию:

1. Перейдите в **Settings → Git**
2. Добавьте конфигурацию Git-сервера:
   - **Name**: идентификатор (например, "GitHub Production")
   - **Type**: GitHub, GitLab или Bitbucket
   - **URL**: URL репозитория
   - **Username**: имя пользователя
   - **Personal Access Token**: токен с правами на репозитории

### 5. Настройка LLM-провайдеров

Для LLM-аналитики и документации:

1. Перейдите в **Settings → LLM**
2. Добавьте провайдера:
   - **Name**: идентификатор (например, "OpenAI Production")
   - **Provider**: OpenAI, Anthropic и т.д.
   - **API Key**: ключ API (будет зашифрован)
   - **Model**: используемая модель (например, gpt-4-turbo)
   - **Binding**: для каких задач использовать (validation, docs, commit)

## Конфигурация окружений

### Структура конфигурации

Конфигурация хранится в PostgreSQL в таблице `app_configurations`:

```sql
SELECT * FROM app_configurations WHERE key = 'global_settings';
```

### Основные настройки

```json
{
  "global_settings": {
    "enable_belief_state_logging": true,
    "task_log_level": "INFO",
    "retention_period_days": 30,
    "storage_path": "/app/storage",
    "git_repos_path": "/app/backend/git_repos"
  },
  "environments": [
    {
      "id": "dev",
      "name": "Development",
      "superset_url": "http://localhost:8088",
      "api_url": "/api/v1",
      "auth_type": "basic",
      "username": "admin",
      "password": "password"
    },
    {
      "id": "staging",
      "name": "Staging",
      "superset_url": "https://staging.superset.example.com",
      "api_url": "/api/v1",
      "auth_type": "oauth2",
      "oauth_url": "https://sso.example.com/oauth2/authorize",
      "token_url": "https://sso.example.com/oauth2/token"
    }
  ]
}
```

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

Основные переменные окружения:

```bash
# Database
DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools
TASKS_DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools
AUTH_DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools

# Server
BACKEND_PORT=8000
FRONTEND_PORT=5173

# Security
SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440

# LLM (опционально)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Git (опционально)
GIT_USERNAME=your-git-username
GIT_EMAIL=your-email@example.com
```

### Включение/отключение функций

```bash
# Включение belief state логирования
export ENABLE_BELIEF_STATE_LOGGING=true

# Уровень логирования задач
export TASK_LOG_LEVEL=DEBUG

# Период retention (в днях)
export RETENTION_PERIOD_DAYS=90
```

## Enterprise Clean Release (изолированный контур)

### Назначение

Сценарий enterprise clean-профиля предназначен для подготовки дистрибутива:
- без test/demo/load-test данных;
- без внешних интернет-источников;
- только с внутренними серверами ресурсов компании.

### Операторский цикл (CLI/API/TUI)

#### A) Headless CLI (основной сценарий для CI/CD)

```bash
cd /home/busya/dev/ss-tools/backend

# Регистрация кандидата
.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

# Импорт артефакта
.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

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

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

#### B) API-автоматизация

Поддерживаемые endpoint’ы:
- V2 lifecycle:
  - `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 (для постепенной миграции интеграций):
  - `POST /api/clean-release/candidates/prepare`
  - `POST /api/clean-release/checks`
  - `GET /api/clean-release/checks/{check_run_id}`

#### C) TUI thin client

```bash
cd /home/busya/dev/ss-tools
./run_clean_tui.sh <candidate_id>
```

Горячие клавиши:
- `F5`: Run Compliance
- `F6`: Build Manifest
- `F7`: Reset Draft
- `F8`: Approve
- `F9`: Publish
- `F10`: Refresh Overview

Ожидаемый flow:
1. Выбрать `candidate_id`.
2. Подтвердить `profile=enterprise-clean`.
3. Выполнить `F6` (если манифест отсутствует).
4. Выполнить `F5` для compliance.
5. При `COMPLIANT` — перейти к `F8` и `F9`.
6. При `BLOCKED` — устранить нарушения и повторить `F5`.

По умолчанию `run_clean_tui.sh` запускает TUI в `real` режиме (`CLEAN_TUI_MODE=real`) без инъекции демонстрационных нарушений.
Важно: TUI запускается только в интерактивном TTY; для headless-среды используйте CLI/API.

### Переменные запуска `run_clean_tui.sh`

```bash
# Опционально: явный режим (real|demo), по умолчанию real
export CLEAN_TUI_MODE=real

# Опционально: bootstrap данных кандидата/политики/реестра
export CLEAN_TUI_BOOTSTRAP_JSON=/absolute/path/bootstrap.json

# Опционально: артефакты для подготовки manifest, если он еще не создан
export CLEAN_TUI_ARTIFACTS_JSON=/absolute/path/artifacts.json

# Запуск (candidate_id можно передать первым аргументом)
./run_clean_tui.sh 2026.03.03-rc1

# Явный демонстрационный режим
./run_clean_tui.sh --demo
```

Минимальный пример `bootstrap.json`:

```json
{
  "candidate_id": "2026.03.03-rc1",
  "version": "1.0.0",
  "source_snapshot_ref": "v1.0.0-rc1",
  "created_by": "operator",
  "allowed_hosts": ["internal-repo.company.com"],
  "prohibited_artifact_categories": ["test-data", "demo", "load-test"],
  "required_system_categories": ["core"]
}
```

### Политика источников (internal-only)

Разрешены только хосты из внутреннего реестра компании, например:
- `repo.intra.company.local`
- `artifacts.intra.company.local`
- `pypi.intra.company.local`

Любой внешний endpoint (например `pypi.org`) трактуется как `external-source` и блокирует выпуск.

### Recovery при BLOCKED

1. Открыть детали нарушений (категория, location, remediation).
2. Удалить запрещённые данные или заменить внешний источник на внутренний.
3. Повторить запуск проверки (F5) до статуса `COMPLIANT`.

### Обязательный CI gate

После операторского TUI-прогона тот же профиль должен пройти в CI.
Только `COMPLIANT` в CI допускает релиз в корпоративный контур.

## Troubleshooting

### Проблемы с Docker

**Проблема**: Контейнеры не запускаются

```bash
# Проверка статуса
docker compose ps

# Просмотр логов
docker compose logs backend
docker compose logs frontend

# Очистка и пересборка
docker compose down -v
docker compose up --build
```

**Проблема**: PostgreSQL порт занят

```bash
# Изменение порта в .env
POSTGRES_HOST_PORT=5433

# Перезапуск
docker compose down
docker compose up -d
```

### Проблемы с Python

**Проблема**: ImportError при импорте модулей

```bash
# Проверка Python версии
python3 --version  # Должен быть 3.9+

# Пересоздание виртуального окружения
cd backend
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt --upgrade
```

**Проблема**: Нет прав на создание файлов

```bash
# На Linux/macOS
chmod +x run.sh
chmod +x build.sh

# На Windows
# Права обычно не требуются для .sh скриптов
```

### Проблемы с Node.js

**Проблема**: npm не устанавливает зависимости

```bash
# Очистка кэша npm
npm cache clean --force

# Пересоздание node_modules
cd frontend
rm -rf node_modules package-lock.json
npm install
```

### Проблемы с БД

**Проблема**: Подключение к PostgreSQL не удается

```bash
# Проверка доступности БД
docker exec ss_tools_db pg_isready -U postgres

# Проверка таблиц
docker exec ss_tools_db psql -U postgres -d ss_tools -c "\dt"

# Ручная инициализация
docker exec -it ss_tools_db psql -U postgres -d ss_tools
```

**Проблема**: Сломанные миграции

```bash
# Откат последней миграции
cd backend
source .venv/bin/activate
alembic downgrade -1

# Повторная инициализация
python src/scripts/init_auth_db.py
```

### Проблемы с Git-интеграцией

**Проблема**: Не удается инициализировать репозиторий

```bash
# Проверка прав на директорию
ls -la backend/git_repos/

# Создание директории вручную
mkdir -p backend/git_repos/
chmod 755 backend/git_repos/

# Проверка Git конфигураций
git config --global user.name
git config --global user.email
```

**Проблема**: Нет доступа к репозиторию

```bash
# Проверка токена
# Токен должен иметь права на:
# - Push
# - Pull
# - Create branches
# - Delete branches (если нужно)
```

## Проверка установки

### Тестирование API

```bash
# Тестирование health endpoint
curl http://localhost:8001/health

# Тестирование списка плагинов
curl http://localhost:8001/api/plugins

# Тестовая аутентификация
curl -X POST http://localhost:8001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}'
```

### Тестирование фронтенда

1. Откройте браузер на http://localhost:8000
2. Проверьте, что вы можете войти с учетными данными администратора
3. Проверьте доступность основных разделов:
   - Dashboard Hub
   - Dataset Hub
   - Settings
   - Reports

## Дополнительные ресурсы

- [Архитектура системы](architecture.md)
- [Настройка окружений](settings.md)
- [Разработка плагинов](plugin_dev.md)
- [API документация](http://localhost:8001/docs)
- [GitHub Issues](https://github.com/yourusername/ss-tools/issues)

## Поддержка

Если вы столкнулись с проблемами, не описанными в этом документе:

1. Проверьте раздел [Troubleshooting](#troubleshooting)
2. Посмотрите логи в Docker: `docker compose logs -f`
3. Откройте issue на GitHub с подробным описанием проблемы
4. Обратитесь в техническую поддержку