Image publication and console updates
Publish a committed image, install the updater, check for updates, and recover with schema compatibility in mind.
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.
docker login
./deploy/publish-image.shChoose 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.
BOS_RELEASE_PLATFORMS=linux/amd64,linux/arm64 ./deploy/publish-image.shBOS_RELEASE_PLATFORMS=linux/arm64 ./deploy/publish-image.shInstall 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.
sudo python3 deploy/image-updater/install.py --user deploy-user
sudo systemctl status bosapi-image-updater.servicepython3 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.
python3 deploy/image-updater/agent.py check
python3 deploy/image-updater/agent.py statuspython3 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.
./deploy/stack.sh up --source
./deploy/stack.sh up --image xiaolinger/bosapi:mainTroubleshoot 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.
python3 deploy/image-updater/agent.py rollback --confirm-schema-compatible
python3 deploy/image-updater/agent.py statusMatch capabilities and procedures to your deployment version. Read the documentation scope