Install on your own server
On this page
This guide installs Moorhold on a physical server you run yourself, in an office or at home. It uses the same signed installer as the cloud guides, run by hand.
This route needs more from you than a cloud server: you look after the hardware, the network and the router. If that isn't for you, a cloud server on IONOS Cloud is simpler.
Before you start
Section titled "Before you start"You need a server that meets the Requirements: 12 GB of memory for the full profile or 8 GB for the core profile, an x86-64 processor, at least 100 GB of disk, and Ubuntu 24.04 LTS or 26.04 LTS. You also need:
- a domain where you can add two DNS records, for example
data.yourorg.exampleand*.data.yourorg.example; - a public IPv4 address that reaches the server, with TCP ports 80 and 443 open to the internet, or a Moorhold relay (see If the installer recommends a relay);
- a Moorhold access key from account.moorhold.dev. An organisation's first key is approved by a person at Moorhold, so allow for that.
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, more memory for a tool is refused: the portal says the server hasn't room, because Moorhold keeps 4.5 GiB spare above its apps' limits.
Home and office networks
Section titled "Home and office networks"Moorhold needs to be reachable on its name by your users, by Let's Encrypt and from your own network. The installer checks this before it asks for certificates, says what it found, and recommends a relay when your network needs one. You can also check by hand first:
- Carrier-grade NAT (CGNAT). Some providers, especially fibre and mobile broadband, share one
public address between many customers. If the WAN address your router shows is in
100.64.0.0/10, or differs from the address a "what is my IP" site reports, port forwarding can't work. Use a relay, ask your provider whether they offer a public IPv4 address, or use a cloud server instead. - Blocked ports. Some residential providers block incoming port 80 or 443. A relay needs no inbound port at home.
- A changing address. Most home connections get a new address now and then. Ask for a static address, or use a dynamic DNS service that updates both records (the name and the wildcard) when it changes. Until DNS catches up, Moorhold is unreachable.
- Hairpin NAT. Some routers can't reach their own public address from inside the network, so your address works from outside but not from your desk. Turn on "NAT loopback" or "hairpin NAT" in the router if it has it. Otherwise use a relay, and every device works on the same name, inside and outside.
- Power. A power cut stops Moorhold and its databases mid-write. A small UPS that lets the server shut down cleanly is worth having.
- Exposure. You're putting a server on the internet. Forward only ports 80 and 443, to this
server only. Keep SSH off the internet, keep the system updated (
unattended-upgradesis on by default on Ubuntu), and keep the server on its own network segment if your router allows.
Install the operating system
Section titled "Install the operating system"The installer also accepts Debian 12, though the steps below are written for Ubuntu.
-
Install Ubuntu Server 24.04 or 26.04 LTS on the whole disk. A minimal install is enough. The installer adds Docker and the tools it needs from the system's own archive.
-
Give the server a fixed local address, either in its network settings or as a DHCP reservation in your router, so port forwarding keeps pointing at it.
-
Bring the system up to date, then restart:
Terminal window sudo apt update && sudo apt full-upgrade
If it's a desktop install, check On a desktop install first.
Forward ports 80 and 443
Section titled "Forward ports 80 and 443"In your router, forward TCP 80 and TCP 443 from the internet to the server's fixed local address, on the same ports. Leave every other port closed.
Point your domain at it
Section titled "Point your domain at it"Use your public IPv4 address (the router's WAN address), not the server's local one. At your DNS provider, add two A records, both with that address as the value:
data(or the name you chose), for the portal;*.data, a wildcard for the tools. Moorhold publishes the dashboards tool, the catalogue and the orchestrator atsuperset.data…,datahub.data…andairflow.data…, behind the same sign-in.
If your DNS provider doesn't accept a wildcard, add three A records instead: superset.data,
datahub.data and airflow.data. With the core profile, only airflow.data is used.
Download and check the installer
Section titled "Download and check the installer"On the server, as your own user (not root):
mkdir -p ~/moorhold && cd ~/moorholdcurl -fsSLO https://get.moorhold.dev/2026.11.4/install.shecho '31575b713ddee80dd36de3e5f1bb5e93da36a34f066ba145212ed37bf4ec6618 install.sh' | sha256sum -c -The last command must print install.sh: OK. If it doesn't, stop.
These commands are for the latest release, 2026.11.4.
The installer itself checks the release's signature against Moorhold's release key before it uses anything it downloads. To check the signature yourself as well, follow Checking by hand in Release files.
To check the server without installing anything, run
sudo bash install.sh --check --hostname data.yourorg.example. It asks for no key and installs
nothing.
Run the installer
Section titled "Run the installer"sudo bash install.sh --hostname data.yourorg.example --profile full- Use your own address in place of
data.yourorg.example. - On an 8 GB server, use
--profile coreinstead of--profile full. - From 2026.10.16, a fresh install has the sample data only if you add
--sample-data. In a terminal, the installer asks whether to load it, and the answer defaults to no.--no-sample-dataleaves it out and never deletes anything already there. First-run setup can also offer Download the sample data after the install; see First-run setup. - It also asks which profile you want if you leave out
--profile.
When it asks for your access key, paste the key you made at
account.moorhold.dev and press Enter. It isn't shown on screen.
Installing without a terminal, from a script or cloud-init? Give --access-key-file <path>
instead: a file of mode 0600 that holds the key.
When the registry accepts your access key, the installer keeps a copy that only root can read, in
/etc/moorhold/secrets/registry-access-key. Upgrades and reruns of the installer use that copy.
Once the images are pulled, the installer deletes the file it read the key from, unless you added
--keep-access-key-file. If you replace the key at account.moorhold.dev,
give the server the new one with sudo moorhold access-key set.
To update the server to a newer release, see the release notes. From 2026.10.16, an update that an admin has approved shows its progress in the portal.
The installer installs Docker and its tools, checks the signed release, pulls Moorhold's images by
digest with your key, generates every password and key on the server, starts the stack and gets
its certificates. It shows its stages under headings and counts the images as it pulls them. It
ends with the command to read your one-time setup code and the address to use it at. The code is
also in /etc/moorhold/secrets/MOORHOLD_SETUP_CODE, readable by root only.
If the installer recommends a relay
Section titled "If the installer recommends a relay"If the installer's network check found no problem, skip this step.
A Moorhold relay is a small cloud server of your own, on Hetzner Cloud or IONOS Cloud. Your DNS points at the relay, and it passes each connection on to your server over an encrypted WireGuard tunnel that your server opens. You need no port forwarding at home, and every device reaches Moorhold on the same name, on your network or off it. The relay never holds a certificate or sees a request: TLS ends on your server, and the relay passes each visitor's own address on to your server.
-
On your server, write the relay's set-up file. For IONOS, use
--provider ionos:Terminal window sudo moorhold relay init --provider hetznerIt makes your server's tunnel key, which stays on your server, and writes
/opt/moorhold/relay/cloud-init-hetzner.yaml, which holds only public keys. The top of the file says where to paste it and what size to choose. -
Create the relay server in your provider's console with Ubuntu 24.04 and a public IPv4 address. Paste that file as its cloud config, then wait for it to start.
-
Open the relay's console in your provider's panel. The login screen shows the Moorhold relay public key. On your server, connect to the relay:
Terminal window sudo moorhold relay connect --endpoint <the relay's public IPv4 address> --relay-key <that key> -
Point both DNS records (
dataand*.data) at the relay's public IPv4 address instead of your router's. -
When DNS has caught up,
sudo moorhold relay checksays whether everything is reachable.
The relay keeps nothing. To update or replace it, make a new one the same way. To stop using it, run
sudo moorhold relay disconnect, then point DNS back at your router.
Open Moorhold
Section titled "Open Moorhold"Go to https://data.yourorg.example/setup, using your own address, and enter the setup code. Then
follow First-run setup. The steps are the same as on a
cloud server.
Check it works
Section titled "Check it works"https://data.yourorg.example/api/moorhold/healthshows{"moorhold":true,"status":"ok"}.- From outside your network (a phone on mobile data, say), the portal and
https://superset.data.yourorg.exampleopen with a trusted certificate. - On the server,
sudo docker pslists the stack's containers as running or healthy.
On a desktop install
Section titled "On a desktop install"If the machine runs a desktop edition (Ubuntu Desktop, Kubuntu, Xubuntu and so on) rather than Ubuntu Server, check these before you run the installer:
-
Ports 80 and 443 must be free. Moorhold's front listens on both. Stop or remove anything already using them, such as Apache, nginx or another web server. This shows what's listening:
Terminal window sudo ss -ltnp '( sport = :80 or sport = :443 )' -
Docker. The installer uses Docker if it's already installed, and installs Ubuntu's own
docker.ioand Compose packages if not. A Docker installed as a snap, or Docker Desktop, isn't what the installer expects. Remove it first, or use a machine without it. -
Sleep and suspend. Desktops go to sleep when idle, which takes Moorhold offline. Turn off automatic suspend in the power settings, or run:
Terminal window sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target -
Memory. The desktop itself uses memory. On a 12 GB machine running the full profile, close other applications, or use the core profile.
-
Firewall. If you've turned on
ufw, allow ports 80 and 443 withsudo ufw allow 80,443/tcp.
After the install
Section titled "After the install"- Backups. A new install backs up its databases every day, on the same server, and shows the backup key once.
sudo moorhold backup keyshows it again. Keep a copy of the key off the server, and test a restore before you rely on it, because a backup on the same machine isn't a second copy. - Newer releases. To update the server, see Upgrading in the release notes.
- Your network. If your public address changes, update both DNS records. If you change routers, forward ports 80 and 443 again. With a relay, neither applies: DNS points at the relay, and your server dials out to it.
If something goes wrong
Section titled "If something goes wrong"- "unsupported system". The server isn't Ubuntu 24.04, Ubuntu 26.04 or Debian 12, or you're using an installer older than 2026.10.1 on 26.04.
- "this server has … GiB of memory". Use
--profile core, or add memory. - No certificate. Run
sudo moorhold relay check. It says whether both DNS records point at the right address, and whether ports, CGNAT or the router are in the way. If one of them is, a relay may help. - The certificate isn't trusted. You installed with
--acme staging. See Switch from staging to a trusted certificate. - The portal opens, but Superset doesn't. The wildcard record (or the three tool records) is missing.
- It works outside, but not inside your network. Your router has no NAT loopback. Use a relay.
If you're still stuck, email hello@moorhold.dev and say which step you reached. Please don't send passwords, keys or other secrets.
Switch from staging to a trusted certificate
Section titled "Switch from staging to a trusted certificate"Earlier versions of the install guide suggested installing with --acme staging first. We no longer
do: browsers don't trust a staging certificate, and on release 2026.10.1 it also stopped the tools
signing each other in. If you installed with it, once the portal opens:
-
Run the same installer command again, without
--acme staging. If the server kept your access key, the installer uses it. If not, paste your key when it asks. The installer keeps every password and key it generated, and the tools it published, and rewrites the Stack to use Let's Encrypt's production service. -
Restart the front so it reads the new setting. It then asks for trusted certificates:
Terminal window sudo docker restart $(sudo docker ps -q --filter name=moorhold-proxy)