Контейнеры и Helm¶

Для закрытого контура поставляются multi-arch образы amd64/arm64, архивы docker save и Helm-чарт. Обращаться к внешнему реестру не нужно: образы загружаются локально, чарт устанавливается из файла.

Образы¶

Образ	Что содержит	Порт
`gitverse.ru/itphx/synth:<version>`	Standalone: core + API + веб-интерфейс	`4300`
`gitverse.ru/itphx/synth-backend:<version>`	API Hub для managed-развёртывания	`5000`
`gitverse.ru/itphx/synth-ui:<version>`	SPA под nginx, проксирует API на backend	`8080`

Тег latest не публикуется — используйте конкретную версию.

Загрузка образов¶

docker load -i synth-<version>-amd64.tar.gz
docker load -i synth-backend-<version>-amd64.tar.gz
docker load -i synth-ui-<version>-amd64.tar.gz

После загрузки образы получают теги с суффиксом архитектуры: gitverse.ru/itphx/synth:<version>-amd64, gitverse.ru/itphx/synth-backend:<version>-amd64, gitverse.ru/itphx/synth-ui:<version>-amd64 (для arm64 — -arm64). Для запуска используйте тег с нужным суффиксом; при желании перетегируйте его в :<version> командой docker tag.

Для arm64 используйте архивы с суффиксом -arm64. На каждый образ и архитектуру — отдельный архив; полный список и SHA256 — в manifest.json и SHA256SUMS рядом с архивами. По умолчанию архивы сжимаются gzip (.tar.gz) для совместимости с Docker 20.10+; для меньшего размера можно собрать с --compression zstd (.tar.zst).

Проверка:

docker image ls | grep 'gitverse.ru/itphx/synth'
docker image inspect gitverse.ru/itphx/synth:<version>-amd64 \
  --format '{{.Os}}/{{.Architecture}}'

Ожидается linux/amd64 или linux/arm64 — в зависимости от загруженного архива. Загружать arm64-архив на amd64-хост бессмысленно: docker load пройдёт, но контейнер не запустится без эмуляции.

Создать архив самостоятельно (например, после загрузки образов из внутреннего реестра на машине нужной архитектуры):

docker save -o synth-<version>-amd64.tar \
  gitverse.ru/itphx/synth:<version>-amd64
docker save -o synth-backend-<version>-amd64.tar \
  gitverse.ru/itphx/synth-backend:<version>-amd64
docker save -o synth-ui-<version>-amd64.tar \
  gitverse.ru/itphx/synth-ui:<version>-amd64

Быстрый запуск¶

docker run -d --name synth \
  -p 4300:4300 \
  -e SYNTH_API_KEY='<api-key>' \
  -v synth-data:/var/synth/data \
  --restart unless-stopped \
  gitverse.ru/itphx/synth:<version>-amd64

Откройте http://localhost:4300 и введите ключ. SYNTH_API_KEY даёт роль ADMIN; для Keycloak используйте профиль из Keycloak и API-key.

Docker Compose¶

compose.yaml для офлайна — с pull_policy: never, чтобы Compose не пытался обратиться к реестру:

services:
  synth:
    image: gitverse.ru/itphx/synth:<version>-amd64
    pull_policy: never
    container_name: synth
    ports:
      - "4300:4300"
    environment:
      SYNTH_API_KEY: "${SYNTH_API_KEY:?set SYNTH_API_KEY in .env}"
    volumes:
      - synth-data:/var/synth/data
    restart: unless-stopped

volumes:
  synth-data:

.env рядом с файлом:

SYNTH_API_KEY=<api-key>

docker compose up -d
docker compose logs -f synth
docker compose ps

Остановка:

docker compose down          # данные в томе сохраняются
docker compose down -v       # удаляет том с данными — необратимо

Helm¶

Чарт ставится из локального .tgz:

helm install synth ./synth-<version>.tgz \
  --namespace synth --create-namespace \
  -f values.yaml

Минимальный values.yaml для офлайн-образов:

backend:
  image:
    repository: gitverse.ru/itphx/synth-backend
    tag: "<version>-amd64"
    pullPolicy: IfNotPresent
  persistence:
    enabled: true
    size: 10Gi

ui:
  image:
    repository: gitverse.ru/itphx/synth-ui
    tag: "<version>-amd64"
    pullPolicy: IfNotPresent

ingress:
  enabled: true
  hosts:
    - host: synth.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: synth-tls
      hosts:
        - synth.example.com

Профили входа (Keycloak и API-key) — в разделе Keycloak и API-key.

Образы на узлах кластера¶

Кластер не сможет pull образ из интернета. Есть два пути:

Внутренний реестр. Загрузите архивы в свой registry и укажите его в backend.image.repository / ui.image.repository. Для приватного реестра задайте imagePullSecrets.
Импорт на каждый узел. Для K3s:

sudo k3s ctr images import synth-<version>-amd64.tar.gz
sudo k3s ctr images import synth-backend-<version>-amd64.tar.gz
sudo k3s ctr images import synth-ui-<version>-amd64.tar.gz

Для containerd:

sudo ctr -n k8s.io images import synth-<version>-amd64.tar.gz
sudo ctr -n k8s.io images import synth-backend-<version>-amd64.tar.gz
sudo ctr -n k8s.io images import synth-ui-<version>-amd64.tar.gz

Образ нужно импортировать на каждом узле, где может запуститься pod, — иначе планировщик попадёт на узел без образа.

Проверка без установки:

tar -xzf synth-<version>.tgz
helm lint ./synth
helm template synth ./synth-<version>.tgz -f values.yaml | less

Multi-arch¶

Реестровые теги — multi-arch: Docker сам выберет amd64 или arm64 под платформу. В офлайн-поставке архивы разделены по архитектуре; выбирайте архив под узлы кластера. Смешивать архитектуры в одном кластере можно, но каждый узел должен иметь образ своей архитектуры.

Проверить платформу узла:

uname -m
docker version --format '{{.Server.Arch}}'

Данные и обновление¶

Данные standalone-контейнера — в томе synth-data (/var/synth/data внутри).
Managed-развёртывание хранит данные на PVC (backend.persistence), по умолчанию 10Gi.
Обновление: загрузить новые образы, обновить тег в Compose/values, выполнить docker compose up -d или helm upgrade. Схему данных применяйте осознанно: synth migrate --yes в контейнере, предварительно сделав backup.
helm uninstall удаляет PVC, если в релизе не задано backend.persistence.keepOnUninstall: true. Проверьте это значение до удаления.

Порядок backup/restore/rollback — в разделе Эксплуатация.