Установка на VM (Docker Compose)¶

Обзор¶

Развёртывание выполняется скриптом install.sh из дистрибутива Docker Compose. Скрипт поднимает четыре контейнера:

Сервис	Назначение
postgres	База данных PostgreSQL 15
seaweedfs	In-cluster S3-хранилище артефактов
registry	AppSec.Registry (core)
ui	Веб-интерфейс (nginx reverse proxy)

Конфигурация и секреты генерируются в каталоге установки (рядом с install.sh и docker-compose.yaml). Данные приложения хранятся в Docker volumes; имена зависят от каталога установки (проект compose). Для /opt/appsec-registry типичные имена: appsec-registry_postgres_data, appsec-registry_seaweedfs_data, appsec-registry_registry_data.

Структура каталога после установки¶

/opt/appsec-registry/
├── install.sh
├── docker-compose.yaml
├── .env                          # переменные для compose и сервисов
├── registry-repo-license.lic
├── registry.properties
├── registry-wait-and-start.sh
├── s3-config.json
├── credentials-summary.txt       # сводка паролей (права 600)
├── tls/                          # при включённом HTTPS
│   ├── cert.pem
│   └── key.pem
├── nginx/
│   └── default.conf
└── certs/                        # trust store (опционально)
    └── *.pem

Предварительные требования¶

См. системные требования и подготовку инфраструктуры: Docker Engine, плагин Docker Compose, curl, openssl, достаточные CPU/RAM и диск.

Получение дистрибутива¶

Скачайте архив с registry.appsec.global:
```
https://registry.appsec.global/repository/appsec.registry-maven-release/docker-compose/docker-compose/{VERSION}/docker-compose-{VERSION}.zip
```
Замените {VERSION} на номер версии релиза (например, 26.3.1). В install.sh внутри zip уже проставлены образы с этим тегом (RELEASE_VERSION — подставляется CI при сборке релиза).
Распакуйте архив на целевой VM (рекомендуется /opt/appsec-registry/):
```
sudo mkdir -p /opt/appsec-registry
cd /opt/appsec-registry
unzip docker-compose-{VERSION}.zip
```
В каталоге должны появиться файлы install.sh, docker-compose.yaml.

Интерактивная установка¶

Подключитесь к серверу:
```
ssh <user>@<server>
```
Перейдите в каталог с распакованным дистрибутивом и запустите мастер:
```
cd /opt/appsec-registry
chmod +x install.sh
./install.sh
```
Мастер последовательно запросит параметры:

Application (Registry + UI)
- Лицензия — файл .lic / .b64 или вставка base64 одной строкой;
- Registry — пароль admin, образ core (repository:tag), порт API на хосте (по умолчанию 8081);
- UI — образ UI, TLS/HTTPS (опционально): пути к PEM или .b64 для certificate и private key;
- Trust store (опционально) — CA-сертификаты в base64 PEM.
Infrastructure
- PostgreSQL — имя БД, пользователь, пароль (Enter = автогенерация), порт;
- SeaweedFS / S3 — access key, secret key, bucket, имя blob store, prefix, region.
После подтверждения скрипт выполняет:
1. Проверку окружения (docker, docker compose, curl, openssl);
2. Генерацию конфигов в каталоге установки (.env, nginx/, tls/ и др.);
3. Запуск PostgreSQL и SeaweedFS;
4. Проверку учётных данных PostgreSQL и создание S3 bucket;
5. Запуск Registry, ожидание API;
6. Настройку trust store (если задан);
7. Регистрацию S3 blob store через REST API;
8. Запуск UI.
По завершении выводится сводка с URL и учётными данными. Те же данные сохраняются в credentials-summary.txt (права 600). Сохраните файл в защищённом месте.

Генерируемые файлы¶

Файл / каталог	Назначение
`.env`	Переменные для `docker compose` и сервисов (образы, пароли, порты)
`registry-repo-license.lic`	Лицензия Registry
`registry.properties`	Стартовые свойства core
`registry-wait-and-start.sh`	Entrypoint-обёртка core (ожидание PostgreSQL)
`s3-config.json`	Учётные данные S3 для SeaweedFS
`nginx/default.conf`	Конфигурация UI (HTTP или HTTPS)
`tls/cert.pem`, `tls/key.pem`	TLS-сертификат и ключ (если HTTPS включён)
`certs/*.pem`	CA для trust store (опционально)
`credentials-summary.txt`	Сводка URL, паролей и параметров установки

TLS / HTTPS¶

При включении TLS UI слушает 443, без TLS — 80. Сертификат и ключ указываются путём к файлам (.pem или .b64), например:

    /opt/fullchain.pem
    /opt/privkey.pem

Вставка длинного base64 в терминал

Сертификат в base64 (~7 KB) не помещается в одну строку терминала (лимит ~4096 символов). Используйте пути к PEM-файлам на диске.

Образы по умолчанию (версия совпадает с релизом дистрибутива):

    registry.appsec.global/appsec-registry/core:{VERSION}
    registry.appsec.global/appsec-registry/ui:{VERSION}

Неинтерактивная установка¶

Для CI/CD или автоматизации:

./install.sh \
  --non-interactive \
  --license-file /path/to/registry-repo-license.lic \
  --enable-tls \
  --tls-cert-file /path/to/fullchain.pem \
  --tls-key-file /path/to/privkey.pem \
  --trust-cert-b64-file my-ca:/path/to/ca.b64

Поддерживаемые флаги:

Флаг	Описание
`--license-file PATH`	Файл лицензии `.lic` или base64 (`.b64`)
`--license-b64-file PATH`	То же, явно как base64-файл
`--license-b64 STRING`	Base64 лицензии одной строкой
`--enable-tls` / `--disable-tls`	HTTPS на UI (443) или HTTP (80)
`--tls-cert-file PATH`	TLS certificate (PEM)
`--tls-key-file PATH`	TLS private key (PEM)
`--tls-cert-b64-file PATH`	TLS certificate (base64 PEM в файле)
`--tls-key-b64-file PATH`	TLS private key (base64 PEM в файле)
`--tls-cert-b64 STRING`	TLS certificate (base64 PEM одной строкой)
`--tls-key-b64 STRING`	TLS private key (base64 PEM одной строкой)
`--trust-cert-b64-file ALIAS:PATH`	CA для trust store (можно повторять)
`--non-interactive`	Без интерактивных вопросов; пароли генерируются, если не заданы
`-h`, `--help`	Справка

В неинтерактивном режиме обязателен один из флагов лицензии. При --enable-tls — также certificate и key.

Подготовка base64:

base64 -w0 registry-repo-license.lic > license.b64
base64 -w0 ca.pem > ca.b64

Доступ после установки¶

Компонент	URL по умолчанию
UI (HTTP)	`http://<host>` (порт 80)
UI (HTTPS)	`https://<host>` (порт 443)
Registry API	`http://<host>:8081`

Логин admin и пароль — из сводки установки или credentials-summary.txt.

Типовые проблемы¶

PostgreSQL: volume с другими учётными данными

PostgreSQL инициализирует volume один раз. При смене POSTGRES_USER / POSTGRES_PASSWORD без удаления volume подключение не удастся. Решение:

cd /opt/appsec-registry
docker compose -f docker-compose.yaml --env-file .env down -v

Затем повторите ./install.sh (данные будут удалены).

Пароли и идентификаторы — только латиница

Скрипт отклоняет кириллицу и не-ASCII в паролях, именах БД, bucket и образах.

Ошибка декодирования лицензии

Убедитесь, что файл .lic не пуст и base64 — одной строкой без переносов (base64 -w0).

TLS: nginx не стартует

Проверьте синтаксис nginx/default.conf и наличие tls/cert.pem, tls/key.pem. После правок перезапустите UI:

docker compose -f docker-compose.yaml --env-file .env restart ui

UI: сообщение «can not modify default.conf (read-only file system?)»

Нормальное поведение: nginx/default.conf смонтирован в контейнер как read-only. Entrypoint UI не перезаписывает конфиг — используется файл из каталога установки.

Registry долго стартует

Первый запуск с PostgreSQL может занять до 30 минут (миграции). Healthcheck настроен с start_period: 1800s.