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.
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
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
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 production |
Profile name from Generator UI. It need not be production: if the profile is named test, write test |
--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 production |
The same environment name as --env; confirms acting on it |
--confirm-restore production |
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
bash ./deploy/control build --env production --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 production [--release release-001.json] |
Check configuration, required tools and host availability. Does not replace deploy or confirm that the website works |
provision --env production --release release-001.json --confirm production |
Prepare the server for its first installation. Do not rerun for a regular update |
provision --env local |
For prod-local, build local images and create isolated data and certificates |
deploy --env production --release release-001.json --confirm production |
Release the specified build; the application is temporarily unavailable during application |
up --env production --confirm production |
Start the recorded version. Does not build code from checkout |
down --env production --confirm production |
Stop the application while retaining data and history |
status --env production [--json] |
Show current/previous versions, the operation, containers and observed readiness |
logs --env production --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 production [--json] |
Show recorded and observed state. Does not fix the operation or release its lock by itself |
resume --env production --operation ID --confirm production |
Continue the same operation with its recorded release after resolving the failure |
abandon --env production --operation ID --confirm production |
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 production --confirm production |
Create a consistent database/media backup; temporarily stop application writes |
restore --env production --recovery-point ID --confirm-restore production |
Restore data and its associated release from the selected backup; subsequent changes are absent from the restored set |
rollback --env production --release RECORDED_ID --confirm production |
Restore previously successful code while retaining data and applied migrations |
certificates --env production --confirm production |
Maintain public Nginx/Certbot HTTPS certificates |
rotate-secrets --env production --kind KIND --confirm production |
Change a specific secret or database certificate |
reconfigure --env production --confirm production |
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.