Image publication and console updates

Publish a committed image, install the updater, check for updates, and recover with schema compatibility in mind.

Operations task guideUpdated Oct 28, 2026

Publish an image on the development machine

Commit and merge changes into local main, then run the publication script from the application repository root. It builds from git archive main, excludes uncommitted changes, and does not fetch remote changes. By default it publishes main and a commit-prefixed tag, not latest. Docker, Buildx, Git, Bash, tar, and registry push access are required.

Publish the image
docker login
./deploy/publish-image.sh

Choose image architectures and retain build caches

The publication script defaults to linux/amd64 for Intel / AMD 64-bit Linux servers. Native use on ARM servers or Apple silicon Macs requires linux/arm64; explicitly set the following variable to publish both architectures. Cross-architecture builds on Linux require QEMU / binfmt support or matching native build nodes.

Reuse the bosapi-release builder and retain dependency and compilation caches. Frontend-only changes can reuse backend compilation; version-only changes no longer reinstall runtime system dependencies. Initial builds, dependency changes, networking, and uploads still affect duration. Commit Dockerfile optimizations to local main for inclusion in release builds.

Explicitly publish both architectures
BOS_RELEASE_PLATFORMS=linux/amd64,linux/arm64 ./deploy/publish-image.sh
Publish an ARM-only image
BOS_RELEASE_PLATFORMS=linux/arm64 ./deploy/publish-image.sh

Install the updater on the deployment host

Complete initial deployment first and preserve the original configuration, data mounts, database password, and encryption key. The deployment host needs the matching scripts, Docker Compose v2, Buildx, and Python 3.9+. On Linux use an existing non-root deployment user with Docker access; on macOS run as the current Docker Desktop user without sudo.

Linux / systemd
sudo python3 deploy/image-updater/install.py --user deploy-user
sudo systemctl status bosapi-image-updater.service
macOS / Docker Desktop
python3 deploy/image-updater/install.py
launchctl print gui/$(id -u)/com.bosapi.image-updater
  • Replace deploy-user. The generated deploy/image-updater.env and deploy/image-updater.enabled are private host-local configuration; do not commit or copy them to another machine.

First switch and later updates

Back up the database before the first switch; the new image may run SQL migrations. From the application repository root, as the service deployment user, check and wait for available or up_to_date. Submit apply only when available, then continue checking status.

Check and inspect status
python3 deploy/image-updater/agent.py check
python3 deploy/image-updater/agent.py status
Run only when available
python3 deploy/image-updater/agent.py apply
python3 deploy/image-updater/agent.py status
  • After completion, a super administrator can use System settings → System update, then Check for updates and Update now. A single instance has brief downtime; closing the page does not stop the host task.
  • The updater pins the checked image digest, recreates the application, and retains data. It does not update host Compose files, the updater, or installer scripts. Synchronize required files according to release notes and do not run manual deployment concurrently.

Select a deployment mode manually

Explicitly select source or image mode from the application repository root on the deployment host. Source mode uses the current checkout; image mode requires an image reference. Neither runs git pull.

Choose source or image
./deploy/stack.sh up --source
./deploy/stack.sh up --image xiaolinger/bosapi:main

Troubleshoot and recover

On Linux inspect journalctl -u bosapi-image-updater.service; on macOS inspect ~/.local/share/bosapi-updater/private/service.stderr.log. After startup or frontend publication failure, the application may have changed and the database may have migrated; inspect the running image and health first.

The previous image is retained as bosapi-image-updater:previous. Use the following recovery command only after confirming schema compatibility with the previous version; it does not reverse SQL migrations. If incompatible, first restore the database according to the backup and migration plan.

Recover after confirming schema compatibility
python3 deploy/image-updater/agent.py rollback --confirm-schema-compatible
python3 deploy/image-updater/agent.py status

Match capabilities and procedures to your deployment version. Read the documentation scope

BOS API · TYPEX

Sales consultation is unavailable

Sales reception could not be initialized. Please try again later. Documentation and free self-hosting remain available.

Read the docsSelf-host for free