Skip to content
Registry StackDocsv0.38.0

Prepare the operator handoff

View as Markdown

The authoring environment is disposable. What crosses into a deployment is one sealed package, one matching SQLite source, and one reviewed change report. The operator binds those to local paths, keys, issuers, and limits, and can change none of the meaning inside them.

Handoff sequence

Section titled “Handoff sequence”
StageCommandResult owner
Classify the changerelayctl diff <previous> <current>Registry Authority reviewer
Prove governancerelayctl check <project> --productionData publisher
Replay fixturesrelayctl test <project>Data publisher
Seal the revisionrelayctl package <project> --output <dir>Data publisher
Bind the deploymentruntime.yamlDeployment operator
Runrelay serve --runtime-config <file>Deployment operator
ConfirmGET /health and GET /readyDeployment operator

Packaging recompiles the project under the production profile, so a package cannot be produced from a revision that would fail check --production. Generation and packaging never start a service or resolve a secret. Packaging does open each bound source read-only to observe its structure, and refuses when a binding cannot be observed.

Obtain the runtime

Section titled “Obtain the runtime”

The installer installs the Linux amd64 relay and relayctl binaries together:

Terminal window
curl -fsSL https://github.com/registrystack/registry-stack/releases/latest/download/relay-install.sh | bash

The installer verifies both downloaded binaries against the release SHA256SUMS before anything reaches the install directory, installs both or neither, and refuses any other platform rather than guessing. It does not verify release authenticity. The signed checksum chain that does, and the checks behind it, are recorded in OpenSSF and release trust. Replace | bash with | less to read the installer before you run it on a host you operate. For a higher-assurance installation, follow the release verification procedure in release/VERIFY.md at the tag you install, https://github.com/registrystack/registry-stack/blob/<tag>/release/VERIFY.md, where <tag> is the tag of the latest release. Then rerun the installer with RELAY_ASSET_DIR pointing at the verified directory. RELAY_INSTALL_DIR selects the install directory; the default is ~/.local/bin.

Each release publishes the container image ghcr.io/registrystack/relay:<tag>, built on distroless nonroot. It exposes port 8080, runs relay serve --runtime-config /etc/relay/runtime.yaml by default, and probes itself with relay healthcheck.

relayctl also ships for each platform in platform support. The Linux assets are the plain relayctl-<tag>-linux-amd64 and relayctl-<tag>-linux-arm64 executables. Starting with v0.33.0, relayctl-<tag>-macos-arm64.tar.gz contains the macOS executable, its shared AWS-LC-FIPS libraries, and third-party notices. Extract the complete macOS bundle into one private directory and keep its contents together. Releases through v0.32.0 retain their plain macOS binary assets. Take the applicable asset directly when the combined installer does not support the target platform, or build it from source. Operators who prefer to place relay themselves take the relay-<tag>-linux-amd64 asset the same way.

Record operator-owned inputs

Section titled “Record operator-owned inputs”

Before the first activation, record:

  • The package directory, its package digest, and the contract revision it seals
  • The SQLite source path and the source profile the package already chose
  • The token issuer identity, discovery URL, audience, and accepted algorithms, or the decision that the deployment is fully anonymous
  • The audit destination and path, its rotation and retention settings, and where sealed files are shipped for append-only storage
  • The cursor integrity key reference and maximum cursor age
  • The listener address, the TLS termination point, and the limits and quotas
  • The Unix service identity that owns every trusted path

Relay resolves secrets through secret:env/<NAME> or secret:file/<name> references in runtime.yaml, where <name> is a single flat lowercase filename under the declared secretProviders.file.root. Secret values never belong in the package, and the package never travels with the database.

The package proves integrity, not authenticity

Section titled “The package proves integrity, not authenticity”

The package digest is the SHA-256 digest of the package’s SHA256SUMS, which lists the digest of every other file, and package.expectedDigest pins it. It detects a modified or truncated package. It is not a signature, and Registry Relay does not sign packages or responses. Authenticity is whatever the institution’s transfer, storage, and access controls make it, so treat the package like any other trusted deployment artifact.

At startup relay serve re-derives the compiled registry and the entire artifact set from the governed files inside the package and requires byte-for-byte equality before it activates. On Unix it also refuses symbolic links and group-writable or world-writable components in the runtime and package paths; on other platforms that check fails closed and the service does not start.

Use the operations guidance

Section titled “Use the operations guidance”

Next

Section titled “Next”