UNS OpenHubDocumentation

Getting started

Runtime versions, upgrades, and recovery

Use uns-bootstrap upgrade to update an existing Runtime. For a version change, Bootstrap stops the local Compose stack, installs the verified release, preserves configuration and volumes, starts the stack, and runs database migrations. Plan for downtime on this host.

Applies to
UNS OpenHub Runtime
Guide version
1.1

Worked example

The release boundary

Treat Bootstrap, the Runtime directory, container images, and your deployment data as related but distinct parts of an installation.

Runtime release VERSION + Compose files + launchers + release metadata

The Runtime repository contains the runnable Compose configuration, launchers, configuration templates, and release metadata for the controller and supporting services.

Bootstrap uns-bootstrap

Bootstrap is the small installer/upgrader that selects and verifies a Runtime release; it is not the controller itself.

Integrity SHA-256 release checks

Downloaded executables and controller artifacts are accepted only when their checksums match the release index.

Deployment data .env, .secrets, configs, infisical-rotator.env, database volumes

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

  1. 1
    Prepare for the interruptionReview the release notes and keep an independent database/volume backup. 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.
  2. 2
    Refresh BootstrapRe-run the public Bootstrap installer for your platform from the Runtime quickstart. This updates the Bootstrap executable, without replacing your existing Runtime.
  3. 3
    Run the Runtime upgradeRun the command below. Supply the read-only GitHub token if requested, review the proposed Runtime version, and type that version to confirm. For a custom installation location, add --dir followed by its directory.
    macOS and Linux
    "$HOME/.local/bin/uns-bootstrap" upgrade
    Windows PowerShell
    & "$HOME\.local\bin\uns-bootstrap.exe" upgrade
  4. 4
    Wait for the managed upgrade to finishBootstrap handles the stop, verified installation, managed image tag, startup, and database migrations. It preserves .env, .secrets, configs, infisical-rotator.env, and volumes, and retains the old Runtime directory. Do not start a second upgrade while it is working.
  5. 5
    Check 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

A selected, checksum-verified Runtime is installed or upgraded while deployment configuration and a rollback copy remain available.

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 hot update is a separate, compatibility-checked path documented in the installed README. It replaces controller application files and restarts the Controller process, not the container or RTT services. Use the full Runtime upgrade for image, Node, operating-system, or infrastructure changes.
  • Use the public quickstart for current platform commands, supported versions, private-release access, 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. Docker Hub authentication is needed for private container images even when the Runtime bundle has already been downloaded. Use docker login docker.io or podman login docker.io for the selected engine before upgrading.

When is a GitHub token required?

A token is needed when an otherwise anonymous download cannot access a private Runtime release or asset. Use a fine-grained, expiring token restricted to read-only Contents access for the relevant repository. Bootstrap sends it only as an Authorization header and does not write it into the Runtime checkout or cache.

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?

For a new version, it stops the current Compose project, verifies and installs the release, preserves deployment configuration and volumes, updates the managed image tag, starts the new Runtime, and applies database migrations. 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.

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 current-platform private CLI checksum 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.