Updating the application

Updates through GitLab Source CI

For GitLab + Build on server, routine releases follow this sequence:

1. Change the model and custom code locally. Save → Generate and apply required local migrations with make migrate.
2. Commit and merge into Release branch, configured in Deployment → Defaults.
3. Run admingen-deploy in that pipeline. Source has no separate Build job: build and installation run on the VPS inside Deploy.
4. Wait for readiness verification. The previous release remains recorded for explicit rollback.

Do not repeat Provision. Reconfigure applies supported environment configuration changes, not each new commit. Routine Deploy does not replace server records with local data; an initial dump transfer is separate.

CI builds the exact commit in a separate checkout; uncommitted server edits are excluded. Projects using the same Unix user share a host build queue. The old release runs during build; installation has a short interruption. If installation has already started and fails, inspect operation state before retrying.

See GitLab CI. Manual commands and other modes follow below.

Content changes do not require a new release: save them in the admin interface. A new release is needed when application code changes.

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.

1. Prepare the code

Change fields, relationships, forms, and access in Generator UI, then run Generate. Change your own Go/React code in custom zones. You can combine these approaches for each update.

Generate preserves existing custom files, but model changes may require your code to handle new fields and types. Generation itself does not update the running application.

2. Build a new version

Choose the instructions for your mode:

For prod-local:

ENV_NAME=local # replace with your exact profile name in Deployment environments
bash ./deploy/control build --env "$ENV_NAME" --output local-release-02.json

For a server environment (Source — after git pull --ff-only on the VPS):

ENV_NAME=production # replace with your exact profile name in Deployment environments
bash ./deploy/control build --env "$ENV_NAME" --output release-02.json

--output names the new file build creates. Do not edit release JSON or overwrite a previous build with it. The current application keeps running during the build.

Another provision is unnecessary. If only delivery/backup settings changed, use reconfigure rather than releasing new code.

With CI, the build job performs this step after a push to main.

3. Install the release

For prod-local:

ENV_NAME=local # replace with your exact profile name in Deployment environments
bash ./deploy/control deploy --env "$ENV_NAME" --release local-release-02.json --confirm "$ENV_NAME"
bash ./deploy/control status --env "$ENV_NAME" --json

For a server:

ENV_NAME=production # replace with your exact profile name in Deployment environments
bash ./deploy/control deploy --env "$ENV_NAME" --release release-02.json --confirm "$ENV_NAME"
bash ./deploy/control status --env "$ENV_NAME" --json

Run Source commands on the VPS and Archive/Registry commands from the controlling computer. In CI, run the deploy job for the desired build instead.

The application is temporarily unavailable during deploy. The controller stops writes, backs up the current successful release if backup is enabled, applies migrations, and starts the new code. With backup.kind: none, no backup is created. The new release is recorded as current only after readiness checks.

After successful completion, open the application. up is not an update command: it starts the previously recorded release.

If you decide not to release a built version

If build finished but deploy has not started, the server has not changed. Simply do not release that build. Abandon is unnecessary for build output: no server operation has been created yet.

If an update is interrupted

Do not start another deploy over an unfinished operation. Check status first and follow operation recovery. This is especially important on first installation: tables may already exist even though there is no successful release yet.

Return to previous code

Take the ID of a previously successful release from environment history:

ENV_NAME=production # replace with your exact profile name in Deployment environments
bash ./deploy/control rollback --env "$ENV_NAME" --release RECORDED_RELEASE_ID --confirm "$ENV_NAME"

Here --release accepts an ID, not a JSON path. Rollback restores code but does not undo SQL migrations or data changes. The controller checks whether the old code is compatible with migrations. To restore data, use restore from backup.

Change delivery or backup through reconfigure, separately from code releases.

After a successful release

Backend and frontend are replaced with the new release's containers. PostgreSQL and its persistent data are preserved. Old images and archives are not cleaned up automatically. If disk fills up, follow disk cleanup: retain the current release and one previous release for rollback. This also applies to ops, alongside backend and admin.