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

MinisForum Test Datastore Server Installation

This guide records the confirmed MinisForum installation and its original deployment path. The server is now maintained with the separate server update procedure, whose current worked example uses server/validator v0.10.8 and site kit 0.3.14. A blank MinisForum uses the fresh server installation procedure. Sections 1–12 preserve the superseded v0.10.3-based server and 0.2.0 site-bundle procedure as historical evidence; do not execute them for a new or resumed installation. Resume only with the release-bound v3 generated runbook described in Section 13.

Do not apply or edit the original fixed-site bundle for svrlducklakedev01. Ticket 12 must generate a new bundle for the MinisForum profile before site provisioning can continue.

Confirmed profile

SettingConfirmed value
ServerMinisForum, Ubuntu 26.04 LTS, x86_64
Hostnamesvrltreapcc02
Reserved IPv4 address192.168.31.75
LAN and approved client range192.168.31.0/24
Runtime HTTPS authorityruntime.svrltreapcc02.home.arpa:443
Name resolutionMatching hosts-file entries on the server, Windows, WSL2, and macOS
Datastoreahri-tre-test
Lake/data/ahri-tre/lake on the /data mount
Trusted scratch/data/ahri-tre/scratch on the /data mount
Initial service choiceCLI only; Web remains disabled

The Runtime certificate must contain runtime.svrltreapcc02.home.arpa as a DNS Subject Alternative Name. The port is not part of the certificate name. Never replace name resolution and certificate validation with an insecure exception.

The generated server package contains no deployment Secret values. Never add TLS private keys, OIDC client secrets, passwords, tokens, or managed-store keys to the repository, transfer archive, or retained command output.

The earlier v0.10.3-based server and 0.2.0 site bundle are not an upgrade baseline. Release v0.10.4 cleanly replaces them. Do not install directly from deployment/test-datastore-kit/server-package; that directory contains templates, not a compiled server package.

Historical record: Sections 1–12 describe work already performed for the superseded artifacts. Keep them for provenance only. The runnable source of truth for the replacement is the v3 runbook generated by Ticket 12.

1. Prepare the WSL2 builder

Run the builder commands in the main checkout:

cd /home/kobus/repos/ahri-tre-rs
./dev-env doctor

Temporary inputs go below tmp/kit-build and the generated kit goes below dist. Both locations are ignored by Git.

2. Download and verify the release

mkdir -p tmp/kit-build/downloads

gh release download v0.10.3 \
  --repo AHRIORG/ahri-tre-rs \
  --pattern 'ahri-tre-0.10.3-x86_64-unknown-linux-gnu.tar' \
  --pattern 'ahri-tre-0.10.3-x86_64-unknown-linux-gnu.tar.sha256' \
  --dir tmp/kit-build/downloads

cd tmp/kit-build/downloads
sha256sum --check \
  ahri-tre-0.10.3-x86_64-unknown-linux-gnu.tar.sha256
cd /home/kobus/repos/ahri-tre-rs

The checksum must report OK. The frozen expected SHA-256 is cad4efb729b09f5c6371639a758ee6b872e22315f52cb5550caad331ca75b5c2.

3. Create the pinned source checkout

git clone --no-checkout . tmp/kit-build/source-v0.10.3

git -C tmp/kit-build/source-v0.10.3 checkout --detach \
  56cbd62b900f7bfb36544eb1ac9b6a4a69bdf565

git -C tmp/kit-build/source-v0.10.3 rev-parse HEAD
git -C tmp/kit-build/source-v0.10.3 status --porcelain

The revision command must print 56cbd62b900f7bfb36544eb1ac9b6a4a69bdf565. The status command must print nothing.

4. Build the maintainer image

Run this from /home/kobus/repos/ahri-tre-rs, not from the pinned source checkout:

docker build \
  --file .devcontainer/Dockerfile \
  --target maintainer \
  --tag ahri-tre-maintainer:local \
  .

docker run --rm ahri-tre-maintainer:local bash -lc \
  'zig version && cargo-zigbuild --version'

Both probe commands must print version information.

5. Build the server programs

The explicit CARGO_TARGET_DIR keeps the completed programs outside the container-private /tmp directory.

docker run --rm \
  --env CARGO_TARGET_DIR=/workspaces/ahri-tre-rs/tmp/kit-build/source-v0.10.3/target \
  --volume "$PWD:/workspaces/ahri-tre-rs" \
  --workdir /workspaces/ahri-tre-rs/tmp/kit-build/source-v0.10.3 \
  ahri-tre-maintainer:local \
  bash -lc '
    test "$(git rev-parse HEAD)" = \
      56cbd62b900f7bfb36544eb1ac9b6a4a69bdf565
    test -z "$(git status --porcelain)"
    RUSTFLAGS="-C link-arg=-Wl,--build-id=0x56cbd62b900f7bfb36544eb1ac9b6a4a69bdf565" \
      cargo zigbuild --locked --release \
        --target x86_64-unknown-linux-gnu \
        -p ahri_tre_trusted_runtime \
        -p ahri_tre_web
  '

test -x tmp/kit-build/source-v0.10.3/target/x86_64-unknown-linux-gnu/release/ahri-tre-runtime
test -x tmp/kit-build/source-v0.10.3/target/x86_64-unknown-linux-gnu/release/ahri-tre-web

6. Generate and verify the server package

docker run --rm \
  --env CARGO_TARGET_DIR=/workspaces/ahri-tre-rs/tmp/kit-build/packager-target \
  --volume "$PWD:/workspaces/ahri-tre-rs" \
  --workdir /workspaces/ahri-tre-rs \
  ahri-tre-maintainer:local \
  bash -lc '
    cargo run --locked -p xtask -- \
      test-datastore-kit package-server \
      --release-archive \
        tmp/kit-build/downloads/ahri-tre-0.10.3-x86_64-unknown-linux-gnu.tar \
      --release-checksum \
        tmp/kit-build/downloads/ahri-tre-0.10.3-x86_64-unknown-linux-gnu.tar.sha256 \
      --runtime-binary \
        tmp/kit-build/source-v0.10.3/target/x86_64-unknown-linux-gnu/release/ahri-tre-runtime \
      --web-binary \
        tmp/kit-build/source-v0.10.3/target/x86_64-unknown-linux-gnu/release/ahri-tre-web \
      --artifact-root \
        dist/ahri-tre-test-datastore-deployment-kit-0.1.0 \
      --source-revision \
        56cbd62b900f7bfb36544eb1ac9b6a4a69bdf565
  '

The packager validates the release checksum, source revision, architecture, embedded build identity, dependencies, launch behaviour, and public schemas.

KIT_ARTIFACT_ROOT="$PWD/dist/ahri-tre-test-datastore-deployment-kit-0.1.0"

test -x "$KIT_ARTIFACT_ROOT/server/install.sh"
test -x "$KIT_ARTIFACT_ROOT/server/bin/ahri-tre-runtime"
test -x "$KIT_ARTIFACT_ROOT/server/bin/ahri-tre-web"
test "$(find "$KIT_ARTIFACT_ROOT/server" -type f | wc -l)" -eq 28

7. Archive and copy the package

cd "$KIT_ARTIFACT_ROOT"
tar -czf ahri-tre-server-0.1.0.tar.gz server
sha256sum ahri-tre-server-0.1.0.tar.gz \
  > ahri-tre-server-0.1.0.tar.gz.sha256

Replace with the ordinary Ubuntu login name. First confirm the destination:

ssh <minisforum-user>@192.168.31.75

grep '^PRETTY_NAME=' /etc/os-release
uname -m
hostnamectl --static
ip -4 -brief address
exit

The relevant values must be Ubuntu 26.04 LTS, x86_64, svrltreapcc02, and 192.168.31.75. Transfer the archive from WSL2:

The repeated SSH and SCP commands can use public-key authentication instead of asking for the MinisForum account password each time. In WSL2, first check for an existing Ed25519 key:

ls -l ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.pub

If both files exist, reuse them. If they do not exist, create a key and choose whether to protect it with a passphrase when prompted:

ssh-keygen -t ed25519 -a 100 -C "wsl2-to-minisforum"

Copy only the public key to the MinisForum, then verify that a new SSH connection succeeds:

ssh-copy-id <minisforum-user>@192.168.31.75
ssh <minisforum-user>@192.168.31.75
exit

Never copy ~/.ssh/id_ed25519, the private key, to another computer. If the key has a passphrase, cache it for the current WSL2 session:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

ssh <minisforum-user>@192.168.31.75 \
  'umask 077; mkdir -p ahri-tre-transfer'

scp ahri-tre-server-0.1.0.tar.gz \
    ahri-tre-server-0.1.0.tar.gz.sha256 \
    <minisforum-user>@192.168.31.75:ahri-tre-transfer/

Using the reserved IP address for this SSH transfer does not weaken the later HTTPS hostname validation.

8. Verify, extract, and install on the MinisForum

ssh <minisforum-user>@192.168.31.75
cd ~/ahri-tre-transfer

sha256sum --check ahri-tre-server-0.1.0.tar.gz.sha256
tar -xzf ahri-tre-server-0.1.0.tar.gz

test -x server/install.sh
test "$(find server -type f | wc -l)" -eq 28

Stop if the checksum fails or the folder does not contain all 28 files. Check for an unexpected earlier installation:

systemctl list-unit-files 'ahri-tre*' --no-legend
sudo test ! -e /usr/libexec/ahri-tre

Stop rather than overwrite or adopt unexpected AHRI TRE files or units. On a clean host, install and diagnose the package:

cd ~/ahri-tre-transfer/server
sudo ./install.sh

sudo /usr/libexec/ahri-tre/diagnose.sh dependencies
sudo /usr/libexec/ahri-tre/diagnose.sh verify-web-binary

Each diagnostic must return JSON containing “status”:“ok”. Run the Web-binary check even for this CLI-only installation: the package includes the Web program, but its service remains disabled.

systemctl show ahri-tre-runtime.service \
  --property=ActiveState,UnitFileState

systemctl show ahri-tre-web.service \
  --property=ActiveState,UnitFileState

Do not enable or start either service yet.

9. Prepare the Runtime certificate inputs

For the current 0.3.14 installed-conformance candidate, follow Recovering a Conformance Candidate After Runtime Key Loss. That self-contained procedure gives every WSL2 and development-container command needed to create the protected Runtime key, issue its certificate, regenerate the site, and compose the checksum-bound replacement candidate.

The server software is installed, but the MinisForum is not provisioned yet. Ticket 12 supplies the v2 profile and packager; Kobus still owns the external certificate and Secret work.

Prepare these two public files on the WSL2 build machine:

  • pki/runtime-certificate-chain.pem, whose leaf certificate SAN contains runtime.svrltreapcc02.home.arpa; and
  • pki/deployment-ca-chain.pem, containing the public issuing CA chain.

Keep the Runtime private key on the MinisForum and provision it only at the path named by the generated injected-secrets.json. Do not copy a private key, CA signing key, password, OAuth secret, token, or Runtime credential into the repository or site bundle.

10. Generate the MinisForum site bundle

In WSL2, open the current Ticket 12 repository root, not the detached v0.10.3 source checkout used to build the server binaries. Cargo is supplied by the maintainer image built in step 4; it is not expected to be installed directly in WSL2. Do not install an unpinned Ubuntu, Snap, or Rustup Cargo merely to run this step.

cd ~/repos/ahri-tre-rs

test -f pki/runtime-certificate-chain.pem
test -f pki/deployment-ca-chain.pem
docker image inspect ahri-tre-maintainer:local >/dev/null

docker run --rm \
  --env CARGO_TARGET_DIR=/workspaces/ahri-tre-rs/tmp/kit-build/packager-target \
  --volume "$PWD:/workspaces/ahri-tre-rs" \
  --workdir /workspaces/ahri-tre-rs \
  ahri-tre-maintainer:local \
  bash -lc '
    cargo run --locked -p xtask -- test-datastore-kit package-site \
      --inputs deployment/test-datastore-kit/site-package/site-inputs.minisforum.json \
      --runtime-certificate-chain pki/runtime-certificate-chain.pem \
      --public-ca-chain pki/deployment-ca-chain.pem \
      --server-component-manifest \
        dist/ahri-tre-test-datastore-deployment-kit-0.1.0/server/component-versions.json \
      --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.2.0
  '

This CLI-only profile deliberately has no --web-certificate-chain. A successful command reports the v2 schema, host=svrltreapcc02, datastore=ahri-tre-test, and artifacts=21.

Before copying anything, confirm the generated identity:

KIT_ARTIFACT_ROOT="$PWD/dist/ahri-tre-test-datastore-deployment-kit-0.2.0"

grep -F 'f2ef37c5-7430-468a-a439-b3ba1b0527c1' \
  "$KIT_ARTIFACT_ROOT/site/site-inputs.json"
grep -F 'runtime.svrltreapcc02.home.arpa' \
  "$KIT_ARTIFACT_ROOT/site/client.toml"
grep -F '"enabled": false' \
  "$KIT_ARTIFACT_ROOT/site/web-ingress-requirements.json"

Review site/firewall-plan.json, site/filesystem-plan.json, and both site/client-publication/ files. Stop if any name, address, mount, client network, or Deployment UUID differs from the confirmed site record. Regenerate from corrected reviewed inputs; do not edit generated files.

11. Publish the hosts-file entry

Open site/name-resolution.md and apply its instructions to the MinisForum, Windows, WSL2, and macOS. Each hosts file must contain the same mapping:

192.168.31.75 runtime.svrltreapcc02.home.arpa

First check for an existing entry before appending. If the name already exists with another address, stop and correct that line instead of creating conflicting entries.

On the MinisForum, run:

grep -n 'runtime.svrltreapcc02.home.arpa' /etc/hosts
grep -Eq \
  '^[[:space:]]*192\.168\.31\.75[[:space:]]+runtime\.svrltreapcc02\.home\.arpa([[:space:]]|$)' \
  /etc/hosts || \
  printf '%s\n' '192.168.31.75 runtime.svrltreapcc02.home.arpa' | \
  sudo tee -a /etc/hosts >/dev/null
getent ahostsv4 runtime.svrltreapcc02.home.arpa

getent must return 192.168.31.75.

On Windows, open PowerShell as Administrator. Check for an existing entry, append the mapping only when the name is absent, flush the cache, and use the normal Windows resolver to verify it:

$hostsPath = "$env:SystemRoot\System32\drivers\etc\hosts"
$existing = Select-String -LiteralPath $hostsPath -Pattern `
  '^\s*[^#\s]+\s+runtime\.svrltreapcc02\.home\.arpa(?:\s|$)'
$existing

if (-not $existing) {
    Add-Content -LiteralPath $hostsPath `
      -Value "`r`n192.168.31.75`t runtime.svrltreapcc02.home.arpa" `
      -Encoding ascii
}

Clear-DnsClientCache
[System.Net.Dns]::GetHostAddresses(
  'runtime.svrltreapcc02.home.arpa'
).IPAddressToString

If $existing shows another address, correct that line instead of running Add-Content. The final command must include 192.168.31.75.

Windows and WSL2 have separate hosts files. In the WSL2 Ubuntu terminal, run:

grep -n 'runtime.svrltreapcc02.home.arpa' /etc/hosts
grep -Eq \
  '^[[:space:]]*192\.168\.31\.75[[:space:]]+runtime\.svrltreapcc02\.home\.arpa([[:space:]]|$)' \
  /etc/hosts || \
  printf '%s\n' '192.168.31.75 runtime.svrltreapcc02.home.arpa' | \
  sudo tee -a /etc/hosts >/dev/null
getent ahostsv4 runtime.svrltreapcc02.home.arpa

To keep this entry when WSL2 would otherwise regenerate /etc/hosts, edit /etc/wsl.conf without replacing any existing settings:

sudo nano /etc/wsl.conf

Add this section if it is absent, or add the setting to its existing [network] section:

[network]
generateHosts = false

From Windows PowerShell, run wsl --shutdown, reopen Ubuntu, and repeat the grep and getent checks. Do not run wsl --shutdown while other important WSL2 work is still running.

On macOS, run:

grep -n 'runtime.svrltreapcc02.home.arpa' /etc/hosts
grep -Eq \
  '^[[:space:]]*192\.168\.31\.75[[:space:]]+runtime\.svrltreapcc02\.home\.arpa([[:space:]]|$)' \
  /etc/hosts || \
  printf '%s\n' '192.168.31.75 runtime.svrltreapcc02.home.arpa' | \
  sudo tee -a /etc/hosts >/dev/null
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
dscacheutil -q host -a name runtime.svrltreapcc02.home.arpa

The final command must report 192.168.31.75. A failed ping does not by itself mean that name resolution failed; use the resolver checks above. Do not use the IP address in HTTPS commands or accept an insecure certificate exception.

12. Archive and copy the generated site folder

From WSL2:

cd ~/repos/ahri-tre-rs
KIT_ARTIFACT_ROOT="$PWD/dist/ahri-tre-test-datastore-deployment-kit-0.2.0"

printf 'Using site artifact root: %s\n' "$KIT_ARTIFACT_ROOT"
test -d "$KIT_ARTIFACT_ROOT/site"
test -x "$KIT_ARTIFACT_ROOT/site/provision.sh"

cd "$KIT_ARTIFACT_ROOT"
test "$PWD" = \
  "$HOME/repos/ahri-tre-rs/dist/ahri-tre-test-datastore-deployment-kit-0.2.0"

tar -czf ahri-tre-site-0.2.0.tar.gz site &&
  sha256sum ahri-tre-site-0.2.0.tar.gz \
    > ahri-tre-site-0.2.0.tar.gz.sha256 &&
  sha256sum --check ahri-tre-site-0.2.0.tar.gz.sha256

scp ahri-tre-site-0.2.0.tar.gz \
    ahri-tre-site-0.2.0.tar.gz.sha256 \
    <minisforum-user>@192.168.31.75:ahri-tre-transfer/

The checksum command must report ahri-tre-site-0.2.0.tar.gz: OK before the transfer. The older 0.1.0 artifact root contains server/, not site/. If tar reports site: Cannot stat, stop: do not create a checksum or transfer that archive. Return to the repository root, reset KIT_ARTIFACT_ROOT exactly as above, and repeat the two test commands.

On the MinisForum:

cd ~/ahri-tre-transfer
sha256sum --check ahri-tre-site-0.2.0.tar.gz.sha256
tar -xzf ahri-tre-site-0.2.0.tar.gz

test -x site/provision.sh
test -f site/site-inputs.json
test -f site/name-resolution.md

Stop if the checksum or any file check fails.

13. Replace with the v0.10.4 server and v3 site bundle

Do not run the copied 0.2.0 bundle’s site/provision.sh. Do not install PostgreSQL directly on Ubuntu. Preserve the existing server package and Runtime certificate work as evidence until the v0.10.4 runbook validates and replaces the package; do not assume either is reusable. The current site bundle is superseded for provisioning.

The default design is PostgreSQL 18 in a managed container on the MinisForum. This is the first live-site and real-identity qualification target for the production validator. Only after it passes does the separate svrlducklakedev01 rollout begin.

13.1 Understand why this step has stopped

Preparing the original Step 13 exposed three problems that an operator should not work around manually:

  1. PostgreSQL 18 provides the OAuth protocol hook but does not include a production ORCID token validator.
  2. The current repository validator under .devcontainer/local/ trusts the deterministic Local OIDC fixture. It cannot validate real ORCID tokens.
  3. The 0.2.0 bundle uses host=127.0.0.1 sslmode=verify-full with a DNS-only certificate and runs administrator commands through the host postgres account. Those assumptions do not work safely for both a container and an external PostgreSQL server.

The shared correction is specified in the Production PostgreSQL ORCID OAuth Validator PRD. Its first three implementation issues are complete and provide:

  • the hardened production ORCID validator;
  • a pinned PostgreSQL 18 image and compatible standalone artifact; and
  • one portable managed-container/external deployment interface.

Ticket 12 packages those artifacts into v0.10.4, delivers the image as a checksummed OCI archive, and consumes them for this MinisForum. A later issue adopts the qualified release on svrlducklakedev01.

13.2 Record the MinisForum PostgreSQL choice

Use this installation record when Ticket 12’s corrected site-input contract is implemented:

Deployment mode: managed-container
PostgreSQL logical TLS name: postgres.svrltreapcc02.home.arpa
PostgreSQL routing address: 127.0.0.1
PostgreSQL port: 5432
Persistent data path: /data/ahri-tre/postgresql
Direct workstation PostgreSQL access: no
ORCID environment: Sandbox only for the first live qualification
ORCID Sandbox issuer: exact confirmed HTTPS issuer
ORCID Sandbox audience: exact Sandbox-issued client ID

The logical TLS name is the name checked against the PostgreSQL certificate. The routing address tells the local Runtime where to send the connection. They are deliberately separate:

host=postgres.svrltreapcc02.home.arpa
hostaddr=127.0.0.1
sslmode=verify-full

Do not reuse runtime.svrltreapcc02.home.arpa for PostgreSQL. Runtime HTTPS and PostgreSQL are different authorities and should have separate private keys and certificates.

For a future separate database server, select external instead. Its certificate must contain that server’s PostgreSQL logical name, and Runtime must route to its recorded address. The server must permit installation of the released PostgreSQL 18 validator artifact. Moving an existing database also requires a tested backup, restore, and cutover; changing the address alone does not move the data.

13.3 Preserve the current MinisForum state

Do not mutate the completed server installation or Runtime key work before the v0.10.4 replacement runbook has validated it. On the MinisForum, run these read-only checks:

hostname -s
findmnt /data
df -h /data
sudo systemctl is-enabled ahri-tre-runtime.service || true
sudo systemctl is-active ahri-tre-runtime.service || true
sudo systemctl is-active ahri-tre-web.service || true
dpkg-query -W -f='${binary:Package} ${Version}\n' 'postgresql*' 2>/dev/null || true
docker --version 2>/dev/null || true
docker compose version 2>/dev/null || true

Expected results:

  • the hostname is svrltreapcc02;
  • /data is the separate approximately 1 TB filesystem;
  • Runtime and Web are not active;
  • it is acceptable for PostgreSQL and Docker to be absent.

If PostgreSQL is already installed, do not remove or reconfigure it from this guide. Record the package output for the corrected installer to inspect. If an AHRI TRE service is active, stop and investigate why before doing anything else.

Keep the installed v0.10.3-based package and copied 0.2.0 archive/checksum as superseded evidence until the v0.10.4 runbook performs its clean replacement. Do not patch generated files inside the bundle. Do not create the PostgreSQL data directory yet; the released image must declare the numeric account and exact permissions that own it.

13.4 Prepare the ORCID Sandbox registration information

The Runtime login callback for this CLI-only site is:

https://runtime.svrltreapcc02.home.arpa/v1/runtime-login/callback

In the ORCID Sandbox developer registration:

  1. confirm that exact callback is allowed;
  2. record the exact Sandbox issuer, JWKS URI, and Sandbox-issued client ID;
  3. keep the client secret in a password manager or root-only Secret file; and
  4. record Kobus as the registration and callback owner.

The client ID in the current bundle is ahri-tre-test. It is an invalid placeholder until it exactly matches the value issued by ORCID Sandbox. The v3 validator configuration requires that client ID as the token audience and one exact Sandbox issuer. If either differs, correct the non-secret site record and regenerate the entire bundle. Never configure Sandbox and production ORCID as simultaneously trusted issuers.

Do not paste the client secret into this repository, this guide, a shell command, a generated archive, or retained terminal output. Do not guess or add scopes by hand; use only the scope emitted by the corrected, ORCID-qualified bundle.

13.5 Prepare the two remaining external inputs

Validator issues 01–03, P2.11c, the v0.10.4 release, and the v3 packager are complete. Before final site generation, the operator must provide:

  1. the actual ORCID Sandbox-issued client ID for the registered Runtime callback; and
  2. a separate PostgreSQL public CA chain after securely retaining its signing key outside the repository.

Copy site-inputs.minisforum.v3.template.json to a private working path, replace its two REPLACE_... values, and change nothing else. The corrected kit provides all of the following:

  • a checksummed PostgreSQL 18 OCI archive pinned by image digest;
  • validator source revision, dependency provenance, and artifact checksums;
  • a managed-container installation and lifecycle runbook;
  • the exact persistent-data owner and permissions;
  • a PostgreSQL-specific DNS name and certificate requirements;
  • logical host plus optional hostaddr connection rendering;
  • hostssl ... oauth and explicit non-TLS reject rules;
  • portable administrator, admission, and removal commands that do not call runuser -u postgres;
  • validator configuration for the exact ORCID Sandbox issuer, JWKS/trust inputs, bounded policy, and mandatory Sandbox-issued audience;
  • safe readiness checks for TLS, HBA ordering, validator loading, and routing; and
  • positive and negative OAuth qualification checks that retain no token or Secret value.

The Local fixture validator, a source file copied manually to the MinisForum, or an unpinned generic PostgreSQL image does not satisfy this checkpoint.

13.6 Regenerate and replace the site bundle

After those two inputs are ready, return to the repository root in WSL2 and follow the package command in the Developer Installation Package Guide. Generate the new 0.3.0 artifact root; do not overwrite dist/ahri-tre-test-datastore-deployment-kit-0.2.0.

Before copying the replacement bundle, verify that its generated manifests record all of these values:

Runtime: runtime.svrltreapcc02.home.arpa:443
PostgreSQL mode: managed-container
PostgreSQL TLS name: postgres.svrltreapcc02.home.arpa
PostgreSQL route: 127.0.0.1:5432
PostgreSQL data: /data/ahri-tre/postgresql
Web: disabled
ORCID environment: Sandbox
ORCID issuer: the exact confirmed Sandbox issuer
ORCID client ID: the actual Sandbox-issued value
Validator artifact: released revision and digest/checksum

Use the archive and checksum commands emitted by the corrected guide. Verify the checksum before copying it to ~/ahri-tre-transfer/. Keep versioned bundles side by side; never merge files from 0.2.0 into the replacement.

13.7 Resume installation from the generated runbook

The corrected generated runbook, not this provisional guide, owns the exact commands. Its expected sequence is:

  1. install the supported container engine only if its prerequisite check says it is absent;
  2. run server/upgrade.sh to replace the superseded server package, verify its component manifest, then verify the OCI archive checksum, load it locally, and confirm that the loaded image digest and recorded provenance match the v0.10.4 manifest;
  3. create a PostgreSQL private key on the MinisForum and have only its public signing request signed by the deployment CA;
  4. verify that the certificate matches postgres.svrltreapcc02.home.arpa and its local private key;
  5. create /data/ahri-tre/postgresql with the generated ownership and permissions;
  6. deploy the PostgreSQL container with port 5432 published only on 127.0.0.1, persistent data under /data, and Secrets mounted read-only;
  7. prove PostgreSQL TLS, validator loading, HBA ordering, health, restart, and persistent-data behavior;
  8. project the ORCID Sandbox client secret and PostgreSQL administrator Secret at the exact generated paths;
  9. run the corrected provision.sh and verify-readiness.sh;
  10. admit the intended canonical orcid_... role; and
  11. prove that a real admitted ORCID Sandbox identity succeeds while a real valid but unadmitted Sandbox identity fails. Cite the release-bound deterministic rejection matrix for invalid-token classes; do not mint or retain synthetic tokens on the MinisForum.

Only after server readiness succeeds should you publish the corrected client.toml and public CA through the WSL2 and macOS packages.

13.8 Do not use these shortcuts

Do not:

  • run the copied 0.2.0/site/provision.sh;
  • install the Local fixture validator on the MinisForum;
  • install PostgreSQL directly merely to satisfy runuser -u postgres;
  • change sslmode=verify-full to require, prefer, or disable;
  • add an insecure certificate exception;
  • use a PostgreSQL password as a substitute for ORCID Session authentication;
  • publish port 5432 on 0.0.0.0 or the LAN address;
  • expose PostgreSQL or Lake storage to Windows, WSL2, or macOS clients; or
  • hand-edit generated configuration to make readiness pass.

Your current operator action is to complete Section 13.5, generate the final bundle, and then follow its short site/HITL.md. Complete Ticket 12 only after the live MinisForum qualification evidence is reviewed.