deploy/control is a command-line tool in the generated application. It builds Docker images, prepares environments, releases versions and maintains an already running project. The file is in the deploy folder, without a dot before the folder name.
In the commands below, ENV_NAME is a shell variable containing the profile name from Deployment environments, not the project name or preset. At the start of each block, replace production, local, or dev with your profile name, for example ENV_NAME=test. Commands use "$ENV_NAME" so --env and its confirmation receive the same value. Set the variable again when switching machines or opening a new terminal.
Run commands from the application root containing Makefile and the deploy folder:
bash ./deploy/control help
For Source, use the VPS terminal. For Archive and Registry, use the controlling computer's terminal or a CI runner. For prod-local, use your computer.
Three steps for the first server startup
ENV_NAME=production # replace with your exact profile name in Deployment environments
bash ./deploy/control build --env "$ENV_NAME" --output release-001.json
bash ./deploy/control provision --env "$ENV_NAME" --release release-001.json --confirm "$ENV_NAME"
bash ./deploy/control deploy --env "$ENV_NAME" --release release-001.json --confirm "$ENV_NAME"
Run one command at a time and proceed only after it succeeds.
- build builds a version without stopping the running application.
- provision prepares the server environment: configuration, secrets, database and certificates. This is preparation, not an application release.
- deploy applies migrations, starts the selected version and records it as current after checking it.
Subsequent versions need only build and deploy. Detailed first startup: Source, Archive, Registry. prod-local has its own sequence: provision without --release, then up.
Parameter meanings
| Parameter | What to supply |
|---|---|
--env "$ENV_NAME" |
The ENV_NAME value: the exact profile name from Generator UI. For example, ENV_NAME=test selects the test profile |
--output release-001.json |
Name of a new file that the build will create |
--release release-001.json |
For provision/deploy/check, the path to the build result |
--release RECORDED_ID |
For rollback only, the ID of a previously successful version, not a file |
--confirm "$ENV_NAME" |
The same environment name as --env; confirms acting on it |
--confirm-restore "$ENV_NAME" |
Separate confirmation of replacing data during restore |
--operation OPERATION_ID |
Interrupted operation ID from command output or status |
--recovery-point POINT_ID |
Completed backup ID returned by backup |
--json |
Machine-readable status/reconcile output |
Do not create or fill in release-001.json manually. It describes a version: references to exact Docker images and migration information. The environment JSON is a different file; Generate creates it from UI settings.
Building: build
ENV_NAME=production # replace with your exact profile name in Deployment environments
bash ./deploy/control build --env "$ENV_NAME" --output release-002.json
The command reads the delivery method from the profile. Source builds on one VPS. Archive saves images in an archive. Registry publishes images to the selected repositories. Source also creates an archive next to the release JSON; keep both files together in either case. The archive contains application and service-container images, not the database or user-uploaded images.
Docker reuses available build layers; existing service images may be marked source=local. Network access for image metadata and dependencies may still occur. A regular repeat build does not require cleaning Docker.
Additional parameters are needed when building outside a regular profile or overriding repositories:
| Build parameter | Purpose |
|---|---|
--source-sha SHA |
Full Git SHA:40 lowercase hexadecimal characters. Checks that checkout matches the commit and source files are unchanged |
--delivery archive |
Build an archive without an environment; with --env, the mode must match the profile |
--delivery registry |
Build for a registry; default mode when no environment is supplied |
--registry PREFIX |
Common repository prefix in the previous configuration format |
--backend-repository REF |
Full backend repository name |
--admin-repository REF |
Full admin repository name |
--ops-repository REF |
Full service-image repository name |
Supply the three separate repositories together; they take precedence over a common prefix. For Registry through --env, SHA is taken from HEAD unless specified. SHA is optional for Source/Archive; Source always requires --env. For prod-local, use only --env and --output.
Preparation, startup and observation
Prefix every command in the table with bash ./deploy/control.
| Command | When and what it does |
|---|---|
check --env "$ENV_NAME" [--release release-001.json] |
Check configuration, required tools and host availability. Does not replace deploy or confirm that the website works |
provision --env "$ENV_NAME" --release release-001.json --confirm "$ENV_NAME" |
Prepare the server for its first installation. Do not rerun for a regular update |
provision --env "$ENV_NAME" |
For prod-local, build local images and create isolated data and certificates |
deploy --env "$ENV_NAME" --release release-001.json --confirm "$ENV_NAME" |
Release the specified build; the application is temporarily unavailable during application |
up --env "$ENV_NAME" --confirm "$ENV_NAME" |
Start the recorded version. Does not build code from checkout |
down --env "$ENV_NAME" --confirm "$ENV_NAME" |
Stop the application while retaining data and history |
status --env "$ENV_NAME" [--json] |
Show current/previous versions, the operation, containers and observed readiness |
logs --env "$ENV_NAME" --service backend |
Show recent log lines; frontend and postgres are also available |
For prod-local, the profile may be named local; --confirm is optional for up/down in this mode. logs is not a continuous tail -f.
Cancellation and continuation
| Command | What it does |
|---|---|
reconcile --env "$ENV_NAME" [--json] |
Show recorded and observed state. Does not fix the operation or release its lock by itself |
resume --env "$ENV_NAME" --operation ID --confirm "$ENV_NAME" |
Continue the same operation with its recorded release after resolving the failure |
abandon --env "$ENV_NAME" --operation ID --confirm "$ENV_NAME" |
Close an operation without success. Does not undo changes already made or restore the previous version |
Resume supports provision, deploy, backup, down, certificates, rollback and restore. Reconfigure is continued by repeating the same command with --operation ID. Secret rotation may require separate diagnosis: generic resume does not perform it.
To abandon a build before deploy, simply do not deploy it: the current version has not changed. To restore code after a successful deploy, use rollback. If an operation has already started and failed, first read operation recovery.
Backups, rollback and maintenance
| Command | Result |
|---|---|
backup --env "$ENV_NAME" --confirm "$ENV_NAME" |
Create a consistent database/media backup; temporarily stop application writes |
restore --env "$ENV_NAME" --recovery-point ID --confirm-restore "$ENV_NAME" |
Restore data and its associated release from the selected backup; subsequent changes are absent from the restored set |
rollback --env "$ENV_NAME" --release RECORDED_ID --confirm "$ENV_NAME" |
Restore previously successful code while retaining data and applied migrations |
certificates --env "$ENV_NAME" --confirm "$ENV_NAME" |
Maintain public Nginx/Certbot HTTPS certificates |
rotate-secrets --env "$ENV_NAME" --kind KIND --confirm "$ENV_NAME" |
Change a specific secret or database certificate |
reconfigure --env "$ENV_NAME" --confirm "$ENV_NAME" |
Apply delivery or backup changes to an existing server environment |
Backup and restore are unavailable with Backup None. Rollback is available without backup, but the previous code must be compatible with the database. Backups and secret rotation are described separately.
For rotate-secrets, auth, postgres, db-leaf and db-ca create new values; media, backup and registry obtain prepared credentials from DEPLOY_SECRETS_FILE.
Reconfigure accepts --on-host to switch from Source to remote management from the running VPS and --operation ID to continue its interrupted change. It does not move data or change domains, servers or the media type. See application management.
Access files and timeout
| Environment variable | When needed |
|---|---|
DEPLOY_SSH_KEY_FILE |
SSH key path for Archive/Registry |
DEPLOY_KNOWN_HOSTS_FILE |
Path to known_hosts containing the saved servers |
DEPLOY_SECRETS_FILE |
Path to private JSON containing external credentials for the first provision, reconfigure or rotation |
DEPLOY_STAGE_TIMEOUT_SECONDS |
Limit for one stage: default1800 seconds, allowed1–86400 |
Do not pass passwords as command arguments. Source has no SSH connection to itself. Access file preparation is described in environment configuration.
Development mode
For dev-local, only check, up, down, status and logs are available. Up starts make dev; backend and Vite write to this terminal. Logs provides only postgres. Dev-local has no release, confirmations or JSON status output.
An environment name starts with a lowercase Latin letter; subsequent characters may be lowercase letters, digits, _ or -. Unknown, repeated and command-inappropriate parameters are rejected. Short built-in help: bash ./deploy/control help.