Moorhold docs

This page explains what Moorhold is made of, where each part runs, and how a change goes from a person or an agent to the tools. It describes the latest release (2026.11.4).

A Moorhold server runs open-source data tools and Moorhold's own services beside them, each in a container, from one Docker Compose project. On the host, the moorhold command and a few systemd units do what needs root.

people
|
v
Caddy (https://<hostname>)
|
+--> the portal --> Postgres
| (desired state,
| audit log)
+--> Keycloak ^
+--> Superset, DataHub, |
Airflow |
|
the reconciler <-------------+
|
+--> one adapter per tool
--> Keycloak, Trino,
Superset, DataHub,
Airflow
on the host: moorhold and
Moorhold's systemd units

Keycloak signs everyone in, once, for every tool. Trino answers SQL across your tables. Apache Airflow runs the loads on a schedule. Apache Superset makes charts and dashboards. DataHub catalogues what you have and where it came from. Postgres holds the warehouse and each tool's own database. People use each tool's own interface: the portal links to them and never frames them.

The profiles and components reference lists the versions and what each profile runs.

Service What it does
The portal The web interface at https://<hostname>: the launchpad, sources, proposals, the Stack, updates, people and the audit log. It reads and writes the desired state in Postgres.
The reconciler Makes every tool match the desired state, through one adapter per tool. See the concepts page on desired state and reconciliation.
The collector Builds the audit log: Keycloak's token events, and the tools' own query events.
The portal MCP server Where agents follow proposals, find each tool's own MCP server and run metrics.
moorhold-lineage Collects lineage when the Stack uses Moorhold's own lineage in place of DataHub's.
moorhold-wake Shows a page while a sleeping tool starts, and puts idle tools to sleep, when the Stack asks for it.
moorhold-backup Takes the encrypted backups with restic.
Caddy The front: HTTPS for every name, the certificate, rate limits, the access log and, from 2026.11.3, a header telling search engines not to index the portal or the tools.

The moorhold command runs as root on the server: installs, upgrades, backups, restores and sudo moorhold apply. moorhold.service starts the stack at boot. Other systemd units wait for approvals from the portal and act on them.

  1. Someone asks. An admin adds a source in the portal, or a proposer asks for one, or an operator edits the Stack and runs sudo moorhold apply. Each of these writes a resource to Moorhold's store in Postgres. Nothing in a tool has changed.
  2. Someone approves, if it's a proposal. A different person approves it in the portal.
  3. The reconciler acts. It sees the new desired state, and each adapter in turn observes its tool, plans and applies: a Trino catalog, a Superset database and datasets, a DataHub ingestion, an Airflow connection and DAG.
  4. The status comes back. The reconciler records what it did on the resource. The portal shows it on the Sources and Stack pages.

The portal and the containers have no power over the host. When an admin approves something that needs root, such as an update or more memory for an app, the portal leaves an empty file in a directory a systemd unit watches. The unit runs moorhold as root, which reads the approval from Moorhold's store, checks it again, and acts. The portal can't tell the host what to run, only that there's something to check.

The server files and services reference lists the directories and units.

Every person has one account, in the server's Keycloak. Moorhold gives each Keycloak group the right role in each tool, from the Stack's RoleProjection. An agent acts as the person it signed in for, with a token from the same Keycloak.