Getting started
Runtime versions, upgrades, and recovery
Choose a full Runtime upgrade when the image or infrastructure changes. A compatible Controller-only update uses a separate verified artifact and restarts the Controller process. Review recovery readiness before either operation.
Worked example
The release boundary
Treat Bootstrap, the Runtime directory, container images, and your deployment data as related but distinct parts of an installation.
The Runtime repository contains the runnable Compose configuration, launchers, configuration templates, and release metadata for the controller and supporting services.
Bootstrap is the small installer/upgrader that selects and verifies a Runtime release; it is not the controller itself.
Downloaded executables and controller artifacts are accepted only when their checksums match the release index.
These are deployment state and configuration. An upgrade preserves the documented configuration files and retains the previous Runtime directory as a rollback backup.
Procedure
Follow the task in order
- 1Prepare for the interruptionReview the release notes and the Recovery workspace. Keep an independently stored, verified recovery point plus separate backups of service-owned data such as QuestDB. If microservices must continue running, arrange and verify their placement on another controller host before upgrading this host. The backup Runtime directory alone is not a database backup.
- 2Refresh BootstrapRe-run the public Bootstrap installer for your platform from the Runtime quickstart. This updates the Bootstrap executable, without replacing your existing Runtime.
- 3Run the Runtime upgradeRun the command below for a full Runtime change. The default public release needs no GitHub token. Review the proposed version and type it to confirm; use a token only for a deliberately configured private mirror. For a custom installation location, add --dir followed by its directory.macOS and Linux
"$HOME/.local/bin/uns-bootstrap" upgradeWindows PowerShell& "$HOME\.local\bin\uns-bootstrap.exe" upgrade - 4Wait for the managed upgrade to finishBootstrap verifies and stages the selected release and checks its managed images before it stops the current Compose stack. It preserves the selected engine and mode, .env, .secrets, configs, infisical-rotator.env, and volumes; then it starts the selected services and runs controller database migrations when a controller is included. It retains the old Runtime directory. Do not start a second upgrade while it is working.
- 5Check the application and servicesAfter the command succeeds, open the Controller, confirm its health and the installed VERSION, and inspect the services and data flow you use. Follow the Runtime README for status and log commands. Retain backups until verification is complete.
Expected result
What you should have
Boundaries
Important boundaries
- A full Runtime version change interrupts this host. Keep an independent database/volume backup until the new Runtime is verified; Bootstrap handles Compose stop and start.
- Do not put GitHub tokens in command history, Git remotes, .env files, tracked configuration, or support logs.
- A Controller-only update is available only for a published candidate compatible with the installed Runtime and image. Review the version-matched Runtime README before selecting it.
- Use the public quickstart for current platform commands, supported versions, private-mirror access when applicable, release notes, and exact offline asset names.
FAQ
Common questions
What is included in a Runtime release?
The generated Runtime contains the runnable Compose configuration, launchers, configuration templates, and release metadata. Release assets also carry platform executables and controller artifacts; the release factory verifies their checksums before publication.
Is image-registry access separate from Runtime access?
Yes, they are separate. The default public Runtime and controller/PostgreSQL images need no GitHub token or Docker Hub login. If you select a private mirror or restricted image registry, authenticate each one separately before upgrading.
When is a GitHub token required?
The default public Runtime download needs no token. A deliberately configured private Runtime mirror may require a fine-grained, expiring token with read-only Contents access to that repository. Bootstrap uses it for release requests and does not store it.
How do I check the installed Runtime version?
From the Runtime installation directory, read the VERSION file. The release tag, VERSION value, and release manifest are expected to agree. Do not infer the Runtime version only from a running container name.
What does uns-bootstrap upgrade do?
It downloads and verifies the selected release, preflights the managed images, then stops the current Compose project for a version change. It preserves deployment configuration and volumes, updates the managed image tag, starts only the selected mode, and applies controller database migrations when applicable. The prior directory is retained. Re-running the same version reconciles the image tag and schema without another directory backup or the version-change stop.
Does upgrade delete my database or other data?
It does not remove volumes, but migrations may change the database schema. Keep an independent database/volume backup and follow release-specific requirements. Preserving the old program directory does not undo database migrations.
Do I need to stop and start Compose manually?
Current Bootstrap handles both for a full Runtime version change. Refresh Bootstrap first. This is a cold upgrade: the local Controller and its hosted services are interrupted, so continuity requires separately prepared workloads and infrastructure on another host.
Can I update only the Controller?
Yes, when a published Controller-only candidate explicitly supports your installed Runtime, image tag, and Node major. From the Runtime directory, use bin/uns runtime hot-upgrade --controller and review the selected version before confirmation. It verifies the artifact, applies required database migrations, replaces Controller application files, and restarts its PM2 process without recreating the container or stopping RTT services. Use a full Runtime upgrade for image, OS, Node, infrastructure, or security-baseline changes.
How do I recover after an upgrade?
If schema migration fails, Bootstrap reports failure, stops the upgraded Runtime, and retains the prior directory. Do not assume renaming that directory rolls back the database. Preserve logs and backups, and follow the version-matched recovery instructions with the system maintainer before restarting an older version.
How do I install without Internet access?
Use the immutable offline Runtime archive and its accompanying SHA-256 file from the release. Bootstrap verifies the Runtime version, release manifest, offline marker, and matching versioned CLI before publishing it, and refuses an existing non-empty destination.
Where are release notes, checksums, and offline bundles?
They belong to the corresponding Runtime and Bootstrap GitHub Releases. Use the current public quickstart for the release links and access instructions; the local Runtime also carries the release metadata needed for verification.
What if Compose reports a container-name conflict?
Do not remove containers blindly. First inspect which existing container owns the name and whether it belongs to this Runtime installation. Stop the old stack or follow the Runtime recovery instructions, then retry; preserve data volumes unless the documented procedure explicitly says otherwise.
This versioned public guide is maintained with the UNS OpenHub website and linked directly from the controller where the task applies.