# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

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

Патчит official-бинарник MinIO (AIStor), заменяя встроенный публичный ключ лицензии на собственный, и генерирует под него валидную JWT-лицензию. Итог — Docker-образ, где `minio` запускается с self-signed лицензией через `MINIO_LICENSE`. Только для образовательных/тестовых целей.

## Архитектура пайплайна

Весь процесс — многоэтапная сборка в `Dockerfile`, где три компонента выполняются строго по цепочке:

1. **`generate-keys.sh`** — генерирует пару ECDSA `secp384r1` (P-384): `new-private.pem` / `new-public.pem`. Кривая жёстко привязана к алгоритму подписи лицензии (ES384) — менять нельзя.

2. **`replace-key.py <orig-binary> <new-binary> <new-pubkey>`** — бинарный патч. Скачивает оригинальный публичный ключ MinIO с `https://subnet.min.io/downloads/license-pubkey.pem` (сетевой доступ обязателен на этапе сборки) и через простой `bytes.replace()` подменяет его в бинарнике на свой. **Критичный инвариант**: длина нового PEM-ключа должна побайтово совпадать с оригиналом (`len(new) == len(original)`), иначе смещения в бинарнике поедут — скрипт падает с ошибкой. Именно поэтому нельзя произвольно менять формат/кривую ключа.

3. **`generate-license.py <private-key> <output>`** — подписывает JWT (`jwcrypto`, alg `ES384`) приватным ключом из шага 1. Claims (`org`, `cap`, `plan`, `exp`, `aid`, …) захардкожены в самом скрипте — параметры лицензии правятся там, в словаре `jwt_data`. `exp` в формате Unix-timestamp.

Связь между шагами: ключ из (1) → патчится публичная часть в бинарник (2) и подписывается лицензия приватной частью (3). Обе части должны быть из одной пары, иначе MinIO отвергнет лицензию.

## Версия MinIO

Задаётся через `ARG RELEASE` в `Dockerfile` (образ `quay.io/minio/aistor/minio`). При обновлении версии пересборка обязательна — публичный ключ и формат бинарника могут отличаться.

## Команды

Сборка и запуск (основной путь):
```bash
docker-compose up -d --build      # API :9000, Web UI :9001
```

Учётные данные и настройки MinIO берутся из `.env` (`MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `MINIO_VOLUMES`, `MINIO_SITE_REGION`).

Локальный прогон отдельных шагов (нужен оригинальный бинарник `minio` в текущей папке):
```bash
pip install -r requirements.txt
./generate-keys.sh
python3 replace-key.py minio minio-patched new-public.pem
python3 generate-license.py new-private.pem minio.license
MINIO_LICENSE=./minio.license ./minio-patched server ./storage
```

## CI

`.gitea/workflows/docker-build.yml` — Gitea Actions, триггер на push git-тега (`tags: "*"`). Собирает и пушит образ в `git.realmanual.ru` с тегами `<tag>` и `latest`. Требует secret `PUSH_TOKEN`.

## Замечания

- `storage/` — рантайм-данные MinIO, в git не трекается (`.gitignore`), но присутствует локально.
- `.env` содержит реальные креды и закоммичен в репозиторий — при работе с ним не выводить значения.