The Stack resource
On this page
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/v1alpha1kind: Stackmetadata: name: <name> labels: {} annotations: {}spec: # the fields belowmetadata.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.
spec fields
Section titled "spec fields"compose (the default) or helm. Moorhold renders a Docker Compose project. Kubernetes isn't
supported, so leave this at compose.
manifest
Section titled "manifest"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.
components
Section titled "components"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: datahubThe core profile leaves out bi and catalog. Each name refers to a Component resource. See
the resource kinds reference.
identity
Section titled "identity"| 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. |
agents
Section titled "agents"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. |
entrypointPrefixes
Section titled "entrypointPrefixes"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 [].
backups
Section titled "backups"| 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.
memory
Section titled "memory"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.
public
Section titled "public"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.
externalObjectStore
Section titled "externalObjectStore"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.
secretProviders
Section titled "secretProviders"A list of {name, type, address, auth}. It has no effect in the latest release.
Component overrides
Section titled "Component overrides"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. |
status
Section titled "status"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. |