Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Updating the Test Datastore Server

This procedure updates an existing MinisForum Test Datastore without recreating the Datastore. For an empty host, use Installing the Test Datastore Server. Every release-specific command comes from one immutable Test Datastore Deployment Kit. Do not combine the server directory from one kit with the site directory or validator image from another.

The worked example below updates the confirmed MinisForum svrltreapcc02 (192.168.31.75) to:

  • AHRI TRE server v0.10.8;
  • PostgreSQL ORCID validator v0.10.8; and
  • MinisForum site kit 0.3.14.

Publication gate: do not start this update until the GitHub v0.10.8 release actually lists both the 0.3.14 archive and its .sha256 asset. The source implementation alone is not an installable release.

There are two command locations:

  • WSL2 is the Ubuntu terminal on the Windows 11 desktop.
  • MinisForum is the remote Ubuntu shell whose prompt starts with sysadmin@svrltreapcc02.

Copy each command as one complete line. Do not copy the displayed prompt. If less opens a file, press q to return to the command prompt.

When this repository is available in WSL2, the interactive equivalent of Sections 1 through 12 is run from the repository root with:

./scripts/minisforum-update-wizard.sh

The wizard uses these same guarded kit operations and prints the password location before every remote sudo stage. This chapter remains the authoritative explanation and recovery reference.

Before starting

The supported predecessor is the current site lifecycle at kit 0.3.13, the v0.10.6 server package first shipped in kit 0.3.12, and the healthy v0.10.6 validator. The update briefly restarts PostgreSQL and the Trusted runtime. Sections 6 through 8 include exact restart checks in case an earlier attempt completed one component before stopping. Do not start if an ingest, export, Session, or other Datastore operation is active.

The update preserves Application configuration, Secret material, Managed secrets, Lake files, PostgreSQL data, and the Datastore identity. It does not ask for or transfer passwords, private keys, ORCID tokens, or the ORCID client secret.

1. WSL2: download the published update kit

Open the WSL2 Ubuntu terminal and create a version-specific download directory:

mkdir -p ~/ahri-tre-updates/v0.10.8

Download the kit and its checksum directly from the GitHub release:

gh release download v0.10.8 --repo AHRIORG/ahri-tre-rs --pattern 'ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz' --pattern 'ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz.sha256' --dir ~/ahri-tre-updates/v0.10.8

Verify the download:

cd ~/ahri-tre-updates/v0.10.8

sha256sum --check ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz.sha256

Stop unless the result is exactly:

ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz: OK

2. WSL2: transfer the verified kit

Create a version-specific transfer directory on the MinisForum:

ssh sysadmin@192.168.31.75 'umask 077; mkdir -p ~/ahri-tre-transfer/v0.10.8'

Copy both files:

scp ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz.sha256 sysadmin@192.168.31.75:ahri-tre-transfer/v0.10.8/

Connect to the MinisForum:

ssh sysadmin@192.168.31.75

All remaining commands run on the MinisForum.

3. MinisForum: verify and extract the kit

Verify the transferred bytes again:

cd ~/ahri-tre-transfer/v0.10.8

sha256sum --check ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz.sha256

Stop unless the result says OK. Extract the kit beside earlier versions:

tar -xzf ahri-tre-test-datastore-deployment-kit-0.3.14.tar.gz

Enter the new kit directory:

cd ~/ahri-tre-transfer/v0.10.8/ahri-tre-test-datastore-deployment-kit-0.3.14

Do not copy files into an older kit directory. The scripts, manifests, server binaries, and validator image in this directory are one release-bound unit.

4. MinisForum: prove the current installation is healthy

Check PostgreSQL:

docker inspect --format '{{.Config.Image}} {{.State.Health.Status}}' ahri-tre-postgresql

The current image version may be older, but its status must be healthy.

Check the Trusted runtime:

sudo systemctl is-active ahri-tre-runtime.service

Expected: active.

Check the existing Datastore binding:

D=ahri-tre-test; R=/usr/libexec/ahri-tre/ahri-tre-runtime; sudo -u ahri-tre-runtime env LD_LIBRARY_PATH=/usr/lib/ahri-tre "$R" datastore reconcile "$D"

Expected: JSON containing "status":"ready".

Do not use an update to repair an installation that fails these checks. Record the failing output and diagnose the current installation first.

5. MinisForum: create a pre-update backup

Run the new kit’s bounded backup procedure before changing either component:

sudo install -d -o root -g root -m 0700 /var/backups/ahri-tre/manual

sudo site/backup.sh /var/backups/ahri-tre/manual/pre-kit-0.3.14.dump

Confirm that new backup files exist:

sudo find /var/backups/ahri-tre -maxdepth 2 -type f -printf '%TY-%Tm-%Td %TH:%TM %p\n' | sort

The backup wrapper refuses to overwrite an existing output. If that exact path already exists, choose a new absolute filename containing the maintenance date; do not remove an older backup. Stop if the backup command fails or no new file appears. Keep this backup through live qualification and the later admitted and unadmitted client qualification.

6. MinisForum: upgrade the PostgreSQL validator

First inspect the running image:

docker inspect --format '{{.Config.Image}} {{.State.Health.Status}}' ahri-tre-postgresql

If this prints ahri-tre/postgresql-orcid-validator:0.10.8 healthy, the validator is already current: skip the upgrade command below and continue to Section 7. If it prints the healthy v0.10.6 image, run the upgrade. Any other image or a non-healthy state is a stop condition.

The upgrade verifies the exact healthy v0.10.6 predecessor, release OCI checksum, image labels, Docker bridge, ownership, Secret projections, and configuration. It briefly stops PostgreSQL and the Runtime, creates the v0.10.8 container over the preserved data, and retains the stopped predecessor as ahri-tre-postgresql-v0.10.6-rollback. A failed start restores v0.10.6.

sudo site/postgresql/upgrade-postgresql.sh --confirm-host svrltreapcc02 --confirm-address 192.168.31.75

Expected:

PostgreSQL validator upgraded to v0.10.8; rollback container retained as ahri-tre-postgresql-v0.10.6-rollback

Confirm the running image and health:

docker inspect --format '{{.Config.Image}} {{.State.Health.Status}}' ahri-tre-postgresql

Expected: ahri-tre/postgresql-orcid-validator:0.10.8 healthy.

7. MinisForum: upgrade the AHRI TRE server

Inspect the installed server manifest before changing it:

sudo jq -r '.base_release + " kit=" + .kit_version' /usr/share/ahri-tre/server/component-versions.json

If this prints v0.10.8 kit=0.3.14, the server is already the exact package required by kit 0.3.14: skip the upgrade command below and continue to Section 8. Otherwise, the expected predecessor is v0.10.6 kit=0.3.12.

The bundled server directory is the new release-bound v0.10.8/0.3.14 server package. Its upgrader retains the previous server files under /var/backups/ahri-tre/server-previous and restarts the Runtime against the upgraded PostgreSQL service.

sudo server/upgrade.sh

sudo systemctl is-active ahri-tre-runtime.service

Expected: active.

8. MinisForum: activate kit 0.3.14 metadata

The persistent Secret authority and reboot-qualified 0.3.6 lifecycle already exist. Before running the command, inspect the installed plan:

sudo jq -r '.kit_version' /etc/ahri-tre/secret-projection-plan.json

If it prints 0.3.14, skip the upgrade command and continue with verification. Otherwise it must print 0.3.13. The guarded operation admits only that exact predecessor plan, the installed v0.10.8/0.3.14 server package, the v0.10.8 container, and three active services. It replaces only the plan and rolls it back on failure.

sudo site/upgrade-secret-projector.sh --confirm-host svrltreapcc02 --confirm-address 192.168.31.75

Expected:

site lifecycle metadata upgraded to kit 0.3.14; v0.10.8 authorization mapping is ready

Verify the projector and ordered services immediately:

sudo /usr/libexec/ahri-tre/secret-projector.sh verify

sudo systemctl is-active ahri-tre-secret-projector.service ahri-tre-postgresql.service

Expected: verification succeeds and both services are active. Stop if it does not. Never inspect files below /var/lib/ahri-tre/injected-secret-authority with a content-printing command. Exclude that authority from broad file backups; it is Secret material.

Confirm the Runtime remained active:

sudo systemctl is-active ahri-tre-runtime.service

If the update reports a failure, it restores the prior installed projector and plan. Confirm that the container and Runtime remain healthy, then stop and diagnose. Do not reboot, delete, or recreate the container.

9. MinisForum: confirm admitted ORCID authority

Rerun admission for each intended ORCID identity. The operation is repeat-safe and confirms its canonical role, identity-map entry, bounded group membership, and Datastore privileges after the validator replacement.

For the confirmed admitted test identity, run:

sudo site/admit-user.sh 0009-0005-0445-6675

Expected:

admitted 0009-0005-0445-6675 as orcid_0009-0005-0445-6675

The ORCID identifier passed to admit-user.sh retains its hyphens. Do not manually create or rename a PostgreSQL role. Repeat this command with the hyphenated ORCID identifier of every other identity that should remain admitted.

10. MinisForum: verify the complete installation

Run the kit’s full readiness check:

sudo site/verify-readiness.sh

Expected: MinisForum v3 site is ready. Confirm its exit status immediately:

echo $?

Expected: 0.

If readiness instead reports that the PostgreSQL OAuth deployment is not ready, run the detailed check for the admitted identity:

sudo env PATH="$PWD/site/postgresql/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" site/postgresql/contract/operator.sh site/postgresql/deployment-contract.json ready 0009-0005-0445-6675

Positive validation is JSON containing "ready":true with the transport, issuer, validator, audience, hba, and admission checks all marked "status":"ready". An admission check with class missing_admission means the role or identity-map entry is absent. Class incomplete_admission means Section 9 must be repeated to repair bounded authority. Stop and diagnose any other failed check rather than continuing to client qualification.

Reconcile the preserved Datastore once more:

D=ahri-tre-test; R=/usr/libexec/ahri-tre/ahri-tre-runtime; sudo -u ahri-tre-runtime env LD_LIBRARY_PATH=/usr/lib/ahri-tre "$R" datastore reconcile "$D"

Expected: JSON containing "status":"ready" and the same Datastore identity as before the update.

11. Confirm the existing reboot qualification remains intact

Kit 0.3.14 replaces the application and validator with v0.10.8 but does not change the projector implementation, readiness waiter, or systemd ordering. Kit 0.3.6 already passed that boot-lifecycle gate. Do not reboot merely to activate this patch update. Positive server validation is the active services, exact Secret projection, site readiness, and preserved Datastore identity confirmed in Sections 6 through 10.

12. Complete release qualification

For this authentication correction, repeat the release kit’s real admitted and valid-but-unadmitted ORCID checks. For kit 0.3.14 these are in site/HITL.md, Section 11. Never save an ORCID token or Secret value in a command transcript or ticket. The unadmitted account is 0009-0007-0768-5937; never pass it to site/admit-user.sh.

Keep the pre-update Datastore backup until both qualification checks pass. Removing older rollback material is a separate, explicitly approved maintenance action.

Applying this procedure to a future release

Do not mechanically replace version numbers in this page. For each future update:

  1. read the release notes and identify the exact server version, validator version, and site-kit version;
  2. download that release’s site-kit archive and checksum together;
  3. verify the checksum in WSL2 and again after transfer;
  4. follow the site/HITL.md inside that exact kit for release-specific prerequisites and commands; and
  5. retain rollback material until readiness and any required live qualification and reboot-persistence gates pass.

If a release does not publish a site kit for this MinisForum profile, it is not an authorized MinisForum update.