Upgrade Oore

Move an Oore installation to a newer release. Most upgrades are one command on the backend Mac. Use the longer procedures below only to change the release channel, to move to an older release or another profile, or to leave v0.1.41.

Every option of the update commands is in the oore update reference.

What you need

• Terminal access to the backend Mac, and to the Web node if it runs on another host.
• A record of the installation’s profile, release channel, install root, and release repository. The procedures below reuse them.
• Administrator access on the Mac. The update restarts launchd services.
• The target release’s notes.
• Free disk space for the download and the rollback files.

Update in place

For a Ready Complete or Control plane installation, stay on the current channel and update in place:

1. Check for a release:

   oore update --check

   The check verifies the signed channel index and checksum manifest. It does not download or run the release.

2. Update:

   oore update

   Oore drains active runner work, creates a backup, restarts the managed services, and verifies the new release. If verification fails, it restores the previous release.

3. On a separate Web node, run oore-web update. For a Web node on Linux, see Update the Web node.

You can also update from the web UI. When a release is available, the sidebar shows Updates available, which opens Update Oore.

Switch the release channel

To move a Ready Complete or Control plane installation to another channel in place, name the channel and confirm the switch:

oore update --check --channel alpha
oore update --channel alpha --switch-channel

On a separate Web node, run oore-web update --channel alpha --switch-channel so that both halves follow the same channel. Later updates, including those from the web UI, stay on the new channel.

A switch never downgrades. If the target channel’s latest release is older than the installed version, the update stops without changes. See Choose a release channel.

Move to an older release or another profile

oore update never downgrades, and oore install does not replace live profile components across release streams. To move to an older release, keep the data and reinstall the same profile from the target stream. This procedure covers macOS release installations only. For a source-built installation, use its own deployment procedure.

1. For a Complete or Control plane installation, create a verified backup.

2. Check the target channel:

   oore update --check --channel beta

3. Remove the current components. Do not add --purge. A normal uninstall keeps the database, configuration, logs, and runner registration.

   oore uninstall

4. Install the bootstrap CLI for the target stream, with the same install root and release repository as before. For the default stable installation, run:

   curl -fsSL https://oore.build/install | bash

   For a custom installation, pass its recorded values:

   oore_install_root=/Users/example/.oore-beta
   oore_channel=beta
   oore_repository=oore-ci/oore.build
   
   curl -fsSL https://oore.build/install | \
     env OORE_CHANNEL="$oore_channel" \
         OORE_INSTALL_ROOT="$oore_install_root" \
         OORE_GITHUB_REPO="$oore_repository" \
     bash

   The bootstrap verifies the signed release metadata and the new CLI’s SHA-256 checksum. If publication fails, it restores the previous files.

5. Install the profile that the installation already records. Replace the path and complete with your recorded values. Valid profiles are complete, control-plane, runner, web-node, and cli-only.

   /Users/example/.oore-beta/bin/oore install --profile complete

   An interactive install continues through setup and service repair. After a non-interactive install, run setup with the existing values. A CLI only profile does not need sudo -v.

   chmod 600 ./oore-setup.yaml
   sudo -v
   /Users/example/.oore-beta/bin/oore setup --config ./oore-setup.yaml

To change the profile itself, follow the same steps and select the new profile in step 5.

Upgrade from v0.1.41

v0.1.42 replaced install modes with profiles. Leave v0.1.41 with the bootstrap, which removes the old payload and keeps your data.

1. Record the topology. Map the old mode to a new profile:

   v0.1.41 mode	v0.1.42 profile
   all	complete
   frontend	web-node

   The old backend mode included both a control plane and a runner, and v0.1.42 has no identical profile. Decide which roles that Mac keeps before you start. Do not guess.

2. Start the v0.1.42 bootstrap with the same install root, channel, and repository. It detects an exact v0.1.41 installation, downloads and verifies the v0.1.42 candidate, and shows a removal plan that keeps your data.

3. Approve oore uninstall --legacy-v0-1-41 when the bootstrap offers it. Oore verifies the old payload and services before it removes anything, and asks for administrator access for protected launchd definitions. The database, configuration, logs, and runner registration stay.

4. Run oore install and select the profile from step 1.

For a non-interactive bootstrap, run sudo -v first, then set OORE_LEGACY_UPGRADE=true to approve the displayed plan. Do not use --purge. The legacy path rejects it.

Verify the result

1. Check the version. Replace the path with your install root:

   /Users/example/.oore-beta/bin/oore version

   The version matches the target release.

2. For a procedure that ran setup, confirm that it ended with <Profile> setup is ready. Oore prints this only after it verifies the services.

3. Run oore status. For a remote role, add --daemon-url <URL>.

4. For a Runner or Complete profile, run a small build from an approved repository.

Troubleshooting

An in-place update fails

oore update prints why it rejected the new release, then restores the previous one. If oore status still reports a refused connection afterwards, check the daemon service and its binary:

sudo launchctl print system/build.oore.oored | grep -E 'state|last exit'
ls -l ~/.oore/bin/oored

A last exit code = 78 together with a missing bin/oored means launchd has nothing to start. Download the oore_<version>_darwin_<arch>.tar.gz archive for the version that oore version reports, verify it against the release’s signed checksums, and put the daemon back:

tar -xzf oore_<version>_darwin_<arch>.tar.gz
install -m 0755 bin/oored ~/.oore/bin/oored
sudo launchctl kickstart -k system/build.oore.oored
oore status

This touches only the daemon binary. The database, configuration, and runner registration stay as they were.

The web UI stays down after an update from the web UI

An update started from the web UI moves bin/oored aside while it backs up the database. If the Mac restarts or the update supervisor is killed during that window, launchd has no daemon to start.

Run any lifecycle command from Terminal on the backend Mac, for example:

oore doctor --update

Oore puts the held daemon back, restores the previous CLI if the update had already replaced it, marks the update as failed, and restarts the daemon. If the restart needs administrator access that oore setup did not grant, Oore prints the sudo launchctl kickstart command to run. oore update and the next web UI update run the same recovery first.

If the update was interrupted while it rolled back a failed release, Oore restores the new daemon so that the service can start, and keeps the previous release in the .supervised-update-* directory it names. Check logs/update-supervisor.log before you try again.

The web UI shows an update that never finishes

When Oore cannot ask launchd whether the update supervisor still runs, the web UI marks an update with no progress for 45 minutes as failed. Start a new attempt after that.

Installation fails after oore uninstall

The preserved data stays in place. The bootstrap and installer tie every download to the signed release manifest and restore the previous component files when it is safe. Fix the reported error, then repeat the bootstrap and the profile installation. Do not use hidden staged-archive or supervisor options.

The update says the channel’s release is older

A channel switch never downgrades. To move to an older release, follow Move to an older release or another profile.

Next step

Monitor Oore through the next normal build.