Справочник CLI

versola — консольная утилита, которая разворачивает и запускает выпущенную версию Versola через Docker на одной машине. Эта страница описывает каждую команду и флаг versola-cli 0.2.10; пошаговый деплой на сервер — в разделе Деплой на VPS.

CLI намеренно тонкий. Он проверяет машину, работает с Docker и запускает версионированный образ ghcr.io/versolauth/versola-tools:<version>, который генерирует всё, что зависит от устройства конкретного релиза Versola: конфигурацию, Compose-файлы, админ-консоль, миграции. Поэтому у versola-cli и у Versola разные номера версий: версия CLI — то, что печатает versola version, а версия Versola — <version>, которую вы передаёте в configure/bootstrap.

Установка и обновление

macOS и Linux:

curl -fsSL https://raw.githubusercontent.com/versolauth/versola-cli/main/install.sh | sh

Скрипт ставит CLI в ~/.local/bin/versola без sudo. В Windows (PowerShell) скрипт ставит CLI в %LOCALAPPDATA%\versola:

iwr https://raw.githubusercontent.com/versolauth/versola-cli/main/install.ps1 -useb | iex

Чтобы позже перейти на новую версию CLI, выполните versola upgrade (см. ниже).

У тегов релизов CLI нет префикса v (у релизов до v0.2.5 он был). Каждый релиз публикует эти файлы и ничего больше:

Сборки для Linux ARM64 нет: на этой платформе установщик завершится ошибкой, потому что файла не существует.

Проверка контрольной суммы. Релизный workflow пишет checksums.txt (формат sha256sum) рядом с бинарниками. Установщики и versola upgrade скачивают его и сравнивают SHA-256 бинарника; при несовпадении установка прерывается. Если checksums.txt отсутствует, недоступен или не содержит записи для нужного файла, они печатают предупреждение и продолжают без проверки. Чтобы проверить вручную, скачайте файл и checksums.txt со страницы релиза и выполните sha256sum -c --ignore-missing checksums.txt.

Чтобы обновить установленный CLI, выполните versola upgrade. Он заменяет бинарник на месте и не трогает dev-сборки.

Таргеты

Таргет — это место, где работает деплой. Он идёт первым аргументом configure и bootstrap.

На машине одновременно активен только один деплой: повторный configure заменяет запись о предыдущем. Команды на vps, которые что-то меняют, спрашивают Continue? [y/N] на стандартном вводе. Флага --yes для этих вопросов нет; пустой ответ или конец ввода прерывает команду с ненулевым кодом выхода.

Каталог состояния

Всё, что хранит CLI, лежит в ~/.versola:

versola uninstall удаляет ~/.versola/active, но не трогает ~/.versola/openbao.

Реверс-прокси на vps

CLI генерирует конфигурацию nginx для реверс-прокси Versola. На vps важны три детали.

• Поколения конфигурации. Прокси не монтирует файлы из бандла. Каждое изменение (configure, добавление или удаление реплики) собирает полную новую конфигурацию в ~/.versola/active/proxy-vps/gen-<n>/, nginx проверяет её в одноразовом контейнере, затем переключается ссылка current и nginx перезагружается. Если перезагрузку отклонили, ссылка возвращается. Контейнер прокси для нового бандла не пересоздаётся, поэтому запросы не теряются.
• Внутренние listener’ы auth идут через прокси. На vps прокси слушает 127.0.0.1:8082 (listener Account Settings, APORT) и 127.0.0.1:8083 (mutual-TLS listener, MPORT) и балансирует их между всеми репликами auth. Собственные listener’ы реплик сдвинуты на 1000 портов вверх (и ещё на 100 на каждый слот). central и edge сохраняют адреса из своей конфигурации. Mutual-TLS-соединение проходит как TCP, поэтому TLS по-прежнему завершает сам auth своим сертификатом.
• Клиентский сертификат от вызывающего не принимается. Прокси ставит заголовку ssl-client-cert пустое значение в каждом пересылаемом запросе, так что вызывающий не может подставить клиентский сертификат этим заголовком. Сертификат принимается только там, где его проверили: на собственном mutual-TLS listener’е auth или через TLS-терминатор, который вы сами настроили выставлять этот заголовок.

Проверка

versola doctor

versola doctor [--target local|vps]

Проверяет, есть ли на машине всё, что нужно Versola. Ничего не устанавливает. Если Docker отсутствует, предлагает открыть страницу установки в браузере и делает это только после вашего подтверждения.

Проверки печатаются строками [ok] или [!!]:

Код выхода ненулевой, если хоть одна проверка не прошла. Для сервера всегда указывайте --target vps: значение по умолчанию применяет не то правило для памяти.

Деплой

Три шага деплоя можно выполнить вместе (bootstrap) или по одному. Запускайте их отдельно, когда миграции должны быть самостоятельным шагом, который можно проверить.

versola bootstrap

versola bootstrap <local|vps> <version> [flags]

Выполняет configure, migrate и up по порядку; на vps подтверждение запрашивается один раз в начале. <version> — тег релиза Versola без префикса v.

--proxy, --acme-staging, --postgres-db и --postgres-ca для local отклоняются.

На vps первый запуск с пустым OpenBao генерирует пароль роли Postgres. Тогда bootstrap останавливается перед migrate с ненулевым кодом выхода, потому что у роли ещё нет этого пароля: выполните SQL, который напечатал configure, затем versola migrate и versola up.

versola bootstrap vps 0.7.1 --auth-url https://id.example.com --postgres-host 127.0.0.1:5432

versola configure

versola configure <local|vps> <version> [flags]

Готовит деплой, не запуская его. Проверяет машину, тянет versola-tools:<version>, генерирует бандл (конфигурацию, Compose-файлы, админ-консоль, конфигурацию прокси), при необходимости запускает OpenBao и разрешает все секреты через него. Ни один сервис Versola не запускается, база не затрагивается, поэтому команду безопасно повторять. На vps она просит подтверждение, потому что заменяет запись этой машины об активном деплое.

Флаги те же, что у bootstrap, кроме --no-browser. configure не запоминает --auth-url, --postgres-host и --proxy: передавайте одни и те же значения при каждом запуске, включая --proxy external, иначе режим прокси вернётся к nginx. --postgres-db и --postgres-ca — исключение: они записываются (файл CA копируется рядом с state.json), следующий configure без флага сохраняет записанное значение, а повторно переданный флаг его переопределяет. Им нужен релиз versola-tools, который читает POSTGRES_DB и POSTGRES_CA_FILE (0.7.1 и новее); более старый их игнорирует.

Прежде чем записать любой секрет, configure вычисляет, что можно сделать с каждым (тот же план печатает secrets plan), и останавливается, ничего не записав, если какой-то секрет выглядит потерянным. См. Секреты.

versola configure vps 0.7.1 --auth-url https://id.example.com --postgres-host db.example.com:5432 --postgres-db versola --postgres-ca /etc/ssl/db-ca.pem

Генерация секретов, которые план отклоняет

--generate-missing NAME[,NAME...] подтверждает, что указанные секреты можно сгенерировать, даже если план остановился бы на них (секрет выглядит потерянным или установка неизвестного происхождения). Имена, которых нет в схеме релиза, считаются проблемой — скорее всего, это опечатки. Пара ключей генерируется, только если названы все члены её группы: половина пары бесполезна. Генерация замены для секрета, к которому привязаны данные, делает эти данные нечитаемыми; используйте флаг, только чтобы восстановиться после потери значения, от которого точно ничего не зависит.

--allow-legacy-secrets относится к релизу, чей versola-tools не пишет secrets.schema.json. Без схемы CLI не отличает новый секрет от потерянного, поэтому на vps отказывается работать, если в OpenBao уже есть секреты или записан деплой. С флагом применяется старое правило: всё, чего нет в OpenBao, генерируется, потеряно оно или нет. При пустом OpenBao и отсутствии записи терять нечего, и флаг не нужен. local не отклоняется никогда.

versola migrate

versola migrate [--dry-run] [--service auth|central|edge]

Выполняет миграции базы каждого сервиса для того, что configure подготовил последним, в одном одноразовом контейнере versola-tools. Ни один сервер не запускается. На vps сначала просит подтверждение и напоминает, что миграции нельзя откатить (down-миграций нет): перед ответом «да» сделайте бэкап базы.

Код выхода ненулевой, если миграция упала, так что скрипт или шаг пайплайна могут на него полагаться. С --dry-run релизы до 0.6.2 включительно сообщают о миграциях, которые просто ещё не применены, как об ошибке проверки; это баг образа versola-tools тех релизов, в 0.7.0 он исправлен.

Сервисы сами не мигрируют: они стартуют с RUN_MIGRATIONS=false, проверяют схему и отказываются стартовать на устаревшей.

versola up

versola up [--no-browser]

Запускает стек, подготовленный configure, и ждёт, пока он начнёт обслуживать трафик: сначала central (auth и edge синхронизируют с ним конфигурацию), затем auth и edge, затем реверс-прокси; в конце — запрос через прокси к auth. Предполагается, что migrate уже выполнен. На vps просит подтверждение, потому что заменяет то, что сейчас обслуживает трафик. central стартует только после того, как step-ca и одноразовый контейнер mtls-init выпустят сертификаты, которые он читает (бандлы 0.7.1 и новее); это часть первого шага.

На vps печатает адрес и файл с ADMIN_BOOTSTRAP_PASSWORD. Этот пароль временный, действует 24 часа, а первый вход с ним требует задать новый.

Эксплуатация

versola status

versola status

Печатает версию и таргет деплоя, время последних миграций, реплики и вывод docker compose ps для проекта. Если ничего не развёрнуто, сообщает об этом и завершается с кодом 0.

Deployed version: 0.7.1 (target: vps)
Migrations applied: 2026-10-14 17:11:51
Replicas: auth x1 (slot 1), edge x1 (slot 1)

versola down

versola down [--volumes]

Останавливает контейнеры деплоя, включая OpenBao и прокси, сохраняя данные и образы. Том Postgres таргета local сохраняется, если не передать --volumes, — этот флаг удаляет и тома стека. На vps Postgres ваш, и команда его никогда не трогает.

versola uninstall

versola uninstall [-y|--yes]

Останавливает стек с --volumes, удаляет Docker-образы, которые скачал Versola, и очищает ~/.versola/active. Перечисляет, что удалит, и просит подтверждение, если не указан -y. На vps оставляет том OpenBao (versola-openbao-file-vps) и том сертификатов (versola-acme-vps) и печатает команды docker volume rm. Если Docker недоступен, сохраняет ~/.versola/active, чтобы деплой потом всё же можно было остановить. Бинарник versola не удаляет, а печатает его путь.

versola replica

versola replica add <auth|edge> [count]
versola replica remove <auth|edge> [count]

Запускает больше одной копии auth или edge за реверс-прокси Versola, который распределяет запросы между ними. central не реплицируется. Реплики записываются, поэтому versola up их восстанавливает, а versola status их показывает. Флагов нет; count по умолчанию 1.

add запускает count новых реплик по одной в наименьших свободных слотах (всего не больше 9). Каждую дожидается готовности и только потом добавляет в upstream’ы прокси. Реплика, которая не поднялась, удаляется; запущенные до неё остаются. У каждого слота своё имя контейнера (versola-auth-2), порты сдвинуты на 100 на слот.

remove останавливает слоты с наибольшими номерами по одному: сначала прокси перестаёт слать реплике запросы и ждёт завершения текущих, затем реплика останавливается. Последнюю реплику сервиса удалить нельзя.

Деплой должен быть запущен (versola up) из последнего configure. На vps обе команды просят подтверждение.

versola replica add edge 2

versola version

versola version

Печатает versola-cli <version> (<go version>, <os>/<arch>). versola --version печатает то же самое.

versola upgrade

versola upgrade [-y|--yes]

Проверяет последний релиз versola-cli на GitHub; если он отличается от версии этого бинарника, скачивает файл для вашей платформы, сверяет его с checksums.txt и заменяет запущенный исполняемый файл на месте. Просит подтверждение, если не указан -y. Версию Versola в деплое не меняет: для этого — configure с новой <version>. dev-сборки не трогает никогда.

Секреты

Эти команды управляют доступом машины к OpenBao и показывают, что сделал бы configure. Что такое секреты и как их ротировать — в разделе Секреты.

versola secrets login

versola secrets login <target> <address> <role-id>

Сохраняет учётные данные AppRole для таргета в ~/.versola/openbao/<target>.json после проверки входом. Secret ID запрашивается отдельным скрытым вводом (или читается из стандартного ввода, если это не терминал), поэтому не попадает ни в историю shell, ни в список процессов. Нужна с --setup-openbao или когда машина потеряла файл с учётными данными.

versola secrets login vps http://127.0.0.1:8200 <role-id>

versola secrets test

versola secrets test <target>

Входит с сохранёнными учётными данными, записывает тестовое значение в versola/<target>/_secrets-test, читает его обратно и сообщает, работают ли учётные данные и движок KV v2. Секретов сервисов не касается. При любой ошибке завершается с ненулевым кодом.

versola secrets plan

versola secrets plan <target> <version> [--json] [--generate-missing NAME[,NAME...]]

Печатает, что configure сделал бы с каждым секретом, ничего не делая. Читает, что хранится в OpenBao, запускает versola-tools:<version> во временном каталоге, чтобы узнать секреты релиза и значения-кандидаты, и для каждого секрета печатает: сохранить, создать или остановить запуск. Нужны сохранённые учётные данные (secrets login), запущенный OpenBao и Docker. В OpenBao и в деплой ничего не пишется. Значения секретов не печатаются никогда.

Код выхода ненулевой, если в плане есть проблемы. В JSON-отчёте поля version, ok, target, state, schemaRevision, deployedRevision (когда есть запись), actions и problems. Формат описан вместе с правилами плана в разделе Секреты.

Обслуживание

Типовые задачи сводятся к командам выше:

Дальше

• Деплой на VPS: те же команды по порядку на настоящем сервере.
• Секреты: что configure делает с каждым секретом и как ротировать один из них.
• Конфигурация: что находится в сгенерированных файлах конфигурации.