Moorhold docs

The Stack is the resource that says what your Moorhold server runs: which tools fill which roles, who signs in, who may propose and approve changes, where backups go, and how the server is reached. There's one Stack on a server. On an installed server it's /opt/moorhold/stack/stack.yaml, and sudo moorhold apply applies your edits to it.

This page describes the Stack in the latest release (2026.11.4).

Every Moorhold resource has the same envelope:

apiVersion: moorhold/v1alpha1
kind: Stack
metadata:
name: <name>
labels: {}
annotations: {}
spec:
# the fields below

metadata.name is a DNS label: lower-case letters, digits and hyphens, starting and ending with a letter or digit, up to 63 characters. Moorhold sets generation, resourceVersion, finalizers and deletionTimestamp itself, and writes status. See the resource kinds reference for the envelope's other fields.

compose (the default) or helm. Moorhold renders a Docker Compose project. Kubernetes isn't supported, so leave this at compose.

The supported-versions manifest this Stack is checked against. The installer sets it to the release's manifest. You don't change it: moorhold upgrade does.

A map from a role to the name of the Component that fills it. The installed Stack has:

components:
identity: keycloak
query: trino
orchestrator: airflow
bi: superset
catalog: datahub

The core profile leaves out bi and catalog. Each name refers to a Component resource. See the resource kinds reference.

Field Type Default What it does
issuer URL required The OpenID Connect issuer everyone signs in with. On an installed server, https://<hostname>/realms/shipboard. It can't hold $, { or }.
upstreamIdPs list [] Other identity providers people may sign in through. Each has an alias, a type (oidc or saml) and a secretRef to its client secret.

Who may propose changes, who may approve them, and which clients count as people.

Field Type Default What it does
mcpAudience string required The audience an agent's token must carry for the portal's MCP server. Installed value: shipboard-mcp.
proposerGroups list of groups required Groups whose members, and whose agents, may propose a change. Installed value: [data-engineers, shipboard-admins].
approverGroups list of groups required Groups whose members may approve or reject a proposal, and who are the stack's admins in the portal. Installed value: [shipboard-admins].
firstLoadGroups list of groups the approver groups Groups whose members may run a new source's first load. Installed value: [data-engineers, shipboard-admins].
humanClients list of client ids required The sign-in clients that mean a person is at the keyboard. Only a session from one of these can decide a proposal. Installed value: [shipboard-portal-ui]. It can't include moorhold-trusted-header.

A list of dotted module paths, such as acme.models. Moorhold imports a REST source's extractor, or an analytics task's entry point, only from a module that equals one of these or sits below one. Unset or empty, nothing is imported, and a source or task that names code is refused. The installed Stack sets [].

Field Type Default What it does
at HH:MM, UTC 02:00 When the daily backup runs.
keep.daily 1 to 366 7 How many daily snapshots to keep.
keep.weekly 0 to 520 4 How many weekly snapshots to keep.
keep.monthly 0 to 120 6 How many monthly snapshots to keep.
repository volume, objectStore or s3 volume Where the encrypted repository is. volume keeps it on this server. s3 needs the s3 block.
s3 object none A bucket of your own: endpoint, region, bucket, path (optional), allowInsecureHttp (optional, for development) and the secret references accessKeyIdRef and secretAccessKeyRef. Give it with repository: s3 and only then.

The installer writes at: "02:00", keeps 7, 4 and 6, and repository: volume. Use sudo moorhold backup target to move backups to a bucket: it writes these fields for you.

A map from a container's name to its memory limit, in place of the tool's own default: a whole number of MiB (3072m) or GiB (4g). The installer records it from the server's memory, so an upgrade keeps it. Approving more memory for an app in the portal changes it. On a full server with less than about 24 GB of memory (the 12 GB and 16 GB sizes included), or a core server with 8 GB, the portal refuses more memory for an app, because Moorhold keeps 4.5 GiB spare above its apps' limits. Unset, every tool uses its default.

How the server is reached from the internet, at https://<hostname>.

Field Type Default What it does
hostname DNS name required The server's name. Lower case, with at least one dot, never an IP address.
launcherOrigins list of https:// origins ["https://moorhold.dev"] The pages that may ask the server's health endpoint whether it's up.
acme production or staging production Which Let's Encrypt service issues the certificate. staging is for testing.
publish list of component names [] The tools reached at their own name under the hostname. Each name once. Installed value: [superset, datahub, airflow].
relay.address IPv4 or IPv6 address none The relay's address on the WireGuard tunnel, when an optional relay passes traffic on to this server. Never a loopback address. sudo moorhold relay connect sets it.
index true or false false Whether search engines may index the server and its published tools. Unset or false, every public host tells them not to, with an X-Robots-Tag: noindex, nofollow header and a robots.txt that disallows every path. Set true only if you want the server to appear in search results.
sleepWhenIdle.components list of component names none Tools that stop when nobody has used them for idleMinutes, and start again on the next request, which shows a page while they start. DataHub and Superset may sleep. Each name once, and at least one.
sleepWhenIdle.idleMinutes 5 to 1440 30 How long a tool is idle before it sleeps.

Unset sleepWhenIdle keeps every tool running: sleep is off unless you set it. After you set it, run sudo moorhold power setup.

A one-person install on one machine, as the Moorhold app for Mac makes it: local: {}. A Stack has public or local, never both. Every tool is on its own port on 127.0.0.1, and there's no hostname or certificate. moorhold install --local runs the light profile on it, and only a local Stack can run that profile.

A map from a slot, a part of Moorhold that more than one provider can fill, to the provider you chose. Unset, each slot takes its default. Slots are off the defaults only when you set them.

Slot Providers Default
lineage native, datahub datahub when the Stack has a DataHub catalog, otherwise native
catalog native, datahub datahub when the Stack has a DataHub catalog, otherwise native
search postgres, opensearch opensearch with the DataHub catalog, postgres with the native one
semantic native native

lineage and catalog also take two providers joined with +, such as native+datahub, while moving from one to the other. The first is the one Moorhold reads. search follows catalog: the native catalog searches with Postgres, and DataHub brings its own OpenSearch. The catalog can't be changed after install. moorhold plan -f on a Stack file says which slot choices that Stack makes.

An S3-compatible object store you bring, in place of the one the stack would run. It isn't in the default Stack or in the full or core profiles: you set it when you want the lake in a store of your own. It can't be combined with objectStore: seaweedfs, and it needs icebergCatalog: polaris. When it's set, each IcebergCatalog must omit spec.bucket (each catalog gets a prefix in the one bucket). Moorhold doesn't back up a lake held in your own S3 store; spec.backups covers Postgres only.

Field Required What it is
endpoint yes Scheme and host (and optional port) only: no login, path, query or fragment. https, unless allowInsecureHttp is true. Must not name this machine, a link-local address, or a cloud metadata host.
region yes 1 to 32 lower-case letters, digits and - (for example eu-central-1).
bucket yes 3 to 63 lower-case letters, digits, . and -, starting and ending with a letter or digit; no ... The one bucket the lake lives in.
pathStyle no Default false. True only when the value is exactly true.
allowInsecureHttp no Default false. True only for development (an http endpoint). Forbidden on a public stack (spec.public).
accessKeyIdRef yes A secret reference, <provider>://<path>[#<key>]. Inline credential field names are refused.
secretAccessKeyRef yes The same form as accessKeyIdRef.
vending no If set: required roleArn (an AWS or MinIO IAM role ARN), and optional stsEndpoint (same origin rules as endpoint). Absent: the store has no usable STS, so engines such as Trino hold the S3 credentials themselves.

Unknown fields are refused.

A list of {name, type, address, auth}. It has no effect in the latest release.

A Component's spec.overrides holds settings for its own adapter. The installed Stack sets these:

Component Override What it is
every tool secretRefs References to the tool's own secrets, by name. Never a value.
keycloak uiUrl Where the launchpad sends people for their account: the realm's account console.
keycloak mcpUrl The public address of the portal's MCP server. Unset, http://localhost:8096. The installed Stack doesn't set it.
trino groupFile Where Trino reads the group file Moorhold writes.
airflow dagsDir, codeDir Where Moorhold writes DAG files, and the host directory of extractor code, mounted read-only on the scheduler.
superset queryEngine How Superset reaches Trino: component, host, port and tlsVerifyPath, the certificate it trusts.
datahub mcpUrl DataHub's own MCP server. Installed value: http://localhost:8099/mcp.
datahub warehouse How DataHub reads the warehouse: platform, host, port, database, username, passwordRef.

The reconciler writes status. You don't edit it.

Field What it is
observedGeneration The metadata.generation the reconciler last acted on.
conditions Ready, Drifted and Degraded, each True, False or Unknown, with a reason, a message and lastTransitionTime.
components For each component, its version, health and image digest.