deploy/control — командный инструмент сгенерированного приложения. Он собирает Docker-образы, подготавливает окружение, выпускает версии и обслуживает уже запущенный проект. Файл находится в папке deploy, без точки перед её именем.
Запускайте команды из корня приложения, где находятся Makefile и папка deploy:
bash ./deploy/control help
Для Source это терминал VPS. Для Archive и Registry — терминал управляющего компьютера или CI runner. Для prod-local — ваш компьютер.
Три шага первого серверного запуска
bash ./deploy/control build --env production --output release-001.json
bash ./deploy/control provision --env production --release release-001.json --confirm production
bash ./deploy/control deploy --env production --release release-001.json --confirm production
Выполняйте по одной команде и переходите к следующей после успеха.
- build собирает версию; работающее приложение не останавливает.
- provision готовит серверное окружение: конфигурацию, секреты, БД и сертификаты. Это подготовка, а не выпуск приложения.
- deploy применяет миграции, запускает выбранную версию и после проверки записывает её как текущую.
Для следующих версий нужны только build и deploy. Подробный первый запуск: Source, Archive, Registry. У prod-local отдельная последовательность: provision без --release, затем up.
Что означают параметры
| Параметр | Что подставить |
|---|---|
--env production |
Имя профиля из Generator UI. Оно не обязано быть production: если профиль называется test, пишите test |
--output release-001.json |
Имя нового файла, который создаст сборка |
--release release-001.json |
Для provision/deploy/check — путь к результату build |
--release RECORDED_ID |
Только для rollback — ID ранее успешной версии, а не файл |
--confirm production |
То же имя окружения, что в --env; подтверждает действие над ним |
--confirm-restore production |
Отдельное подтверждение замены данных при restore |
--operation OPERATION_ID |
ID прерванной операции из вывода команды или status |
--recovery-point POINT_ID |
ID готовой резервной копии, выданный backup |
--json |
Машиночитаемый вывод status/reconcile |
release-001.json не нужно создавать или заполнять вручную. Это описание версии: ссылки на точные Docker-образы и сведения о миграциях. JSON окружения — другой файл; его создаёт Generate из настроек UI.
Сборка: build
bash ./deploy/control build --env production --output release-002.json
Команда читает способ доставки из профиля. Source собирает на одном VPS. Archive сохраняет образы в архив. Registry публикует образы в выбранных репозиториях. Source также создаёт архив рядом с JSON релиза; в обоих случаях сохраняйте пару файлов вместе. В архиве образы приложения и служебных контейнеров, не БД и не загруженные пользователями изображения.
Docker повторно использует доступные слои сборки; присутствующие сервисные образы могут отмечаться как source=local. При этом обращение к сети для метаданных образов и зависимостей всё ещё возможно. Обычный повтор build не требует очистки Docker.
Дополнительные параметры нужны, если вы запускаете сборку вне обычного профиля или переопределяете репозитории:
| Параметр build | Назначение |
|---|---|
--source-sha SHA |
Полный Git SHA: 40 строчных шестнадцатеричных символов. Проверяется соответствие checkout коммиту и отсутствие изменений исходников |
--delivery archive |
Собрать архив без окружения; при --env режим должен совпасть с профилем |
--delivery registry |
Собрать для registry; это режим по умолчанию при вызове без окружения |
--registry PREFIX |
Общий префикс репозиториев в прежнем формате конфигурации |
--backend-repository REF |
Полное имя репозитория backend |
--admin-repository REF |
Полное имя репозитория admin |
--ops-repository REF |
Полное имя репозитория служебного образа |
Три отдельных репозитория передавайте вместе; они имеют приоритет над общим префиксом. Для Registry через --env SHA берётся из HEAD, если не указан. Для Source/Archive SHA необязателен; Source всегда требует --env. Для prod-local используйте только --env и --output.
Подготовка, запуск и наблюдение
Перед каждой строкой в таблице подразумевается bash ./deploy/control.
| Команда | Когда и что делает |
|---|---|
check --env production [--release release-001.json] |
Проверяет конфигурацию, необходимые инструменты и доступность хостов. Не заменяет deploy и не подтверждает работоспособность сайта |
provision --env production --release release-001.json --confirm production |
Готовит сервер к первой установке. Не запускайте заново для обычного обновления |
provision --env local |
Для prod-local собирает локальные образы, создаёт изолированные данные и сертификаты |
deploy --env production --release release-001.json --confirm production |
Выпускает указанную сборку; во время применения приложение временно недоступно |
up --env production --confirm production |
Запускает уже записанную версию. Код из checkout не собирает |
down --env production --confirm production |
Останавливает приложение, сохраняя данные и историю |
status --env production [--json] |
Показывает текущую/предыдущую версии, операцию, контейнеры и наблюдаемую готовность |
logs --env production --service backend |
Показывает последние строки журнала; также доступны frontend и postgres |
Для prod-local имя профиля может быть local; у up/down в этом режиме --confirm необязателен. logs не является непрерывным tail -f.
Отмена и продолжение
| Команда | Что делает |
|---|---|
reconcile --env production [--json] |
Показывает сохранённое и наблюдаемое состояние. Самостоятельно не исправляет операцию и не снимает блокировку |
resume --env production --operation ID --confirm production |
Продолжает ту же операцию с сохранённым релизом после устранения причины сбоя |
abandon --env production --operation ID --confirm production |
Закрывает операцию без успеха. Не отменяет уже выполненные изменения и не возвращает прежнюю версию |
Resume поддерживает provision, deploy, backup, down, certificates, rollback и restore. Для reconfigure предусмотрен повтор той же команды с --operation ID. Ротация секретов может потребовать отдельного разбора: универсальное resume её не выполняет.
Чтобы отказаться от сборки до deploy, достаточно не запускать её: текущая версия не изменилась. Чтобы вернуть код после успешного deploy, используйте rollback. Если операция уже началась и упала, сначала прочитайте восстановление операций.
Копии, откат и обслуживание
| Команда | Результат |
|---|---|
backup --env production --confirm production |
Создаёт согласованную копию БД и медиа; на время останавливает запись приложения |
restore --env production --recovery-point ID --confirm-restore production |
Возвращает данные и связанный релиз из выбранной копии; последующие изменения отсутствуют в восстановленном наборе |
rollback --env production --release RECORDED_ID --confirm production |
Возвращает ранее успешный код, оставляя данные и применённые миграции |
certificates --env production --confirm production |
Обслуживает публичные HTTPS-сертификаты Nginx/Certbot |
rotate-secrets --env production --kind KIND --confirm production |
Меняет конкретный секрет или сертификат БД |
reconfigure --env production --confirm production |
Применяет изменение доставки или backup существующего серверного окружения |
Backup и restore недоступны при Backup None. Rollback доступен и без backup, но прежний код должен быть совместим с БД. Резервные копии и смена секретов описаны отдельно.
Для rotate-secrets: auth, postgres, db-leaf, db-ca создают новые значения; media, backup, registry получают подготовленные credentials из DEPLOY_SECRETS_FILE.
Reconfigure принимает --on-host для перехода с Source на удалённое управление с действующего VPS и --operation ID для продолжения своего прерванного изменения. Он не переносит данные и не меняет домены, серверы или тип media. Порядок — в управлении приложением.
Файлы доступа и таймаут
| Переменная окружения | Когда нужна |
|---|---|
DEPLOY_SSH_KEY_FILE |
Путь к SSH-ключу при Archive/Registry |
DEPLOY_KNOWN_HOSTS_FILE |
Путь к known_hosts с сохранёнными серверами |
DEPLOY_SECRETS_FILE |
Путь к приватному JSON с внешними credentials при первом provision, reconfigure или ротации |
DEPLOY_STAGE_TIMEOUT_SECONDS |
Лимит одного этапа: по умолчанию 1800 секунд, допускается 1–86400 |
Значения паролей не передавайте аргументами команд. У Source нет SSH-подключения к самому себе. Подготовка файлов доступа описана в настройке окружения.
Режим разработки
Для dev-local доступны только check, up, down, status и logs. Up запускает make dev; backend и Vite пишут в этот терминал. Через logs доступен только postgres. У dev-local нет release, подтверждений и JSON-вывода status.
Имя окружения начинается со строчной латинской буквы; далее допустимы строчные буквы, цифры, _, -. Неизвестные, повторяющиеся и неподходящие команде параметры отклоняются. Краткая встроенная справка: bash ./deploy/control help.