Docs
Docs menu

Install a node

Run the Moru node image with Docker Compose and Caddy, create the first admin, and put the node behind HTTPS.

A Moru node is one container image, ghcr.io/webstonehq/moru-node, built for linux/amd64 and linux/arm64. It holds the node binary with the web UI built in, plus git. Wherever you run it, it needs three things:

  1. A persistent volume mounted at /data. Everything the node keeps lives there.
  2. MORU_PUBLIC_URL, the URL people use to reach the node. It goes into clone URLs, runner leases and sign-in links.
  3. Port 7070 reachable through something that terminates TLS.

Run exactly one container per data volume. A node is a single instance: don’t scale it out.

If you’d rather use a hosting platform, see Fly.io or Railway, Render and Kubernetes. The rest of this page applies there too.

Try it on your machine#

To look around before you set up a server:

docker run -d --name moru -v moru-data:/data -p 127.0.0.1:7070:7070 \
  -e MORU_PUBLIC_URL=http://127.0.0.1:7070 ghcr.io/webstonehq/moru-node:latest
docker logs moru 2>&1 | grep 'setup#code='

Open the link the second command prints and create the first admin. The node is at http://127.0.0.1:7070. The quick start goes on from there to a repository from GitHub and a first request.

On a server: Docker Compose and Caddy#

This is the simplest production setup. Caddy sits in front of the node, gets a TLS certificate and renews it. You need:

  • a Linux host with Docker and the Compose plugin,
  • ports 80 and 443 open to the internet,
  • a domain whose DNS (A and/or AAAA records) points at the host before the first start, so Caddy can get a certificate.

Make a directory, for example /srv/moru, and put three files in it.

compose.yaml:

name: moru

services:
  moru:
    image: ${MORU_IMAGE:-ghcr.io/webstonehq/moru-node:latest}
    restart: unless-stopped
    # Any other MORU_* setting in .env reaches the node too.
    env_file: .env
    environment:
      MORU_PUBLIC_URL: https://${MORU_DOMAIN:?set MORU_DOMAIN in .env}
      # Caddy reaches the node over the Compose network.
      MORU_TRUSTED_PROXIES: private
    volumes:
      - moru-data:/data
    # Running jobs and pushes get time to finish.
    stop_grace_period: 30s

  caddy:
    image: caddy:2.11
    restart: unless-stopped
    ports:
      - '${MORU_HTTP_PORT:-80}:80'
      - '${MORU_HTTPS_PORT:-443}:443'
      - '${MORU_HTTPS_PORT:-443}:443/udp'
    environment:
      MORU_DOMAIN: ${MORU_DOMAIN:?set MORU_DOMAIN in .env}
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    depends_on:
      - moru

volumes:
  # Everything the node keeps. Back it up with `moru-node backup`.
  moru-data:
  # Caddy's certificates and ACME account.
  caddy-data:
  caddy-config:

Caddyfile:

{$MORU_DOMAIN} {
	reverse_proxy moru:7070 {
		# The event stream and runner long-polls need unbuffered, long reads.
		flush_interval -1
		transport http {
			read_timeout 5m
		}
	}
	request_body {
		# git pushes; scratch repos have their own quota (50 MiB by default).
		max_size 200MB
	}
}

.env:

# The node's domain. Point its DNS at this host before the first start.
MORU_DOMAIN=moru.example.com

# The image. `:latest` follows every release; pin a version (`:2026.11.5`) or a
# digest (`@sha256:…`) to upgrade only when you choose.
MORU_IMAGE=ghcr.io/webstonehq/moru-node:latest

# Optional node settings, for example:
# MORU_EVENTS_RETENTION=30d
# MORU_JOB_QUEUE_TTL=12h

Then start it and find the setup link in the node’s log:

docker compose up -d
docker compose logs moru | grep 'setup#code='

Every MORU_* variable you add to .env reaches the node. Configuration lists them all.

MORU_HTTP_PORT and MORU_HTTPS_PORT in .env change the host ports Caddy publishes (80 and 443 by default). If you already run a reverse proxy on the host, drop the caddy service instead, publish the node’s port 7070 to your proxy only, and see behind your own proxy.

Create the first admin#

A new node has no accounts. On every start until someone is admin, it prints a setup link to its log:

========================================================================
No admin yet. Open this link to create one (it works once, for 24 hours,
and a restart replaces it):

    https://moru.example.com/setup#code=mrs_…
========================================================================

Open the whole link (the code is the part after #). Pick a handle and a password of at least 12 characters, and click Create admin and sign in. You’re now the node’s admin. The link works once, for 24 hours, and each restart replaces it until it’s used.

If you’d rather not use the link, make the first admin from the command line. It prints an invite link where they set their password:

docker compose exec moru moru-node create-user mira --admin

After that, admins invite everyone else from the People page. See Accounts and sign-in.

Run commands in the container#

The moru-node command in the image runs as the moru user (uid 10001) however you start it, so running it as root with docker compose exec is safe and won’t leave files the node can’t read:

docker compose exec moru moru-node create-user jon          # an invite link for jon
docker compose exec moru moru-node list-runners
docker compose exec -T moru moru-node backup - > moru.tgz   # see Backups

The image sets MORU_DATA=/data, so you don’t pass --data. moru-node commands lists every command.

If the volume was mounted with another owner (some platforms mount volumes as root), the image gives /data to uid 10001 when it starts.

Behind your own reverse proxy#

The node speaks plain HTTP. Whatever terminates TLS in front of it needs:

  • No response buffering, and reads of at least 5 minutes. The UI’s event stream (/api/v0/events) stays open, and runners long-poll for 20 seconds at a time.
  • Request bodies as large as your biggest push. 200 MB is a reasonable start.
  • The node’s own setting for it. Set MORU_PUBLIC_URL to the address people use, and MORU_TRUSTED_PROXIES to the proxy’s address so sign-in rate limits see each client’s address rather than the proxy’s.

With Caddy on the same host:

moru.example.com {
	reverse_proxy 127.0.0.1:7070 {
		flush_interval -1
		transport http {
			read_timeout 5m
		}
	}
	request_body {
		max_size 200MB
	}
}

With nginx, set proxy_buffering off, proxy_read_timeout 300s and a client_max_body_size big enough for your pushes:

server {
    listen 443 ssl;
    server_name moru.example.com;
    # ssl_certificate and ssl_certificate_key as usual

    client_max_body_size 200m;

    location / {
        proxy_pass http://127.0.0.1:7070;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_read_timeout 300s;
    }
}

A container behind such a proxy, published on loopback only:

docker run -d --name moru --restart unless-stopped -v moru-data:/data \
  -p 127.0.0.1:7070:7070 \
  -e MORU_PUBLIC_URL=https://moru.example.com \
  -e MORU_TRUSTED_PROXIES=private \
  ghcr.io/webstonehq/moru-node:latest

private covers loopback and the private address ranges, which is where Docker’s own networks are.

Without a container#

The node is one binary. In the image it’s at /usr/local/lib/moru/moru-node (the moru-node on the image’s PATH is a small wrapper that switches to the moru user). To copy it out:

docker create --name moru-bin ghcr.io/webstonehq/moru-node:latest
docker cp moru-bin:/usr/local/lib/moru/moru-node /usr/local/bin/moru-node
docker rm moru-bin

It’s built on Debian 13 (trixie), so it runs there and on Linux distributions with the same or a newer glibc. It needs git on its PATH and keeps everything in its data directory.

Use git 2.40 or later (the image has 2.47). The node checks open changes against their target branch with it, to show which ones no longer apply. With an older git the node still runs, but logs a warning at startup and skips these checks: conflicts then show up only when someone merges.

A systemd unit, running as a dedicated moru user behind a proxy on the same host:

[Unit]
Description=Moru node
After=network-online.target

[Service]
User=moru
ExecStart=/usr/local/bin/moru-node --data /var/lib/moru serve --listen 127.0.0.1:7070 --public-url https://moru.example.com --trusted-proxy 127.0.0.1
Restart=on-failure
UMask=0077

[Install]
WantedBy=multi-user.target

journalctl -u moru shows the setup link on the first start. Run other commands as the same user, with the same --data:

sudo -u moru moru-node --data /var/lib/moru create-user jon

The node stops cleanly on SIGTERM or SIGINT.

From your own registry#

You can run the node from a copy of the image in a registry you run, so your hosts never pull from ghcr.io. Copy each release once, with both architectures:

docker buildx imagetools create -t registry.example.com/moru/moru-node:2026.11.5 \
  ghcr.io/webstonehq/moru-node:2026.11.5

crane copy and skopeo copy --all do the same. A plain docker pull followed by docker push copies only your machine’s architecture.

Then point your setup at the copy: MORU_IMAGE in .env with Compose, the image in fly.toml or the StatefulSet elsewhere. Copy a version tag rather than latest, so you know which release you run, and copy again for each upgrade and weekly rebuild you want.

The image carries the runner downloads, so runners installed from your node come from your registry’s copy too.

For a host with no access to any registry, save the image where you have one and load it on the host:

docker pull --platform linux/amd64 ghcr.io/webstonehq/moru-node:2026.11.5
docker save ghcr.io/webstonehq/moru-node:2026.11.5 | gzip > moru-node-2026.11.5.tar.gz
# on the host:
gunzip -c moru-node-2026.11.5.tar.gz | docker load

Pick the platform of the host (linux/arm64 for an ARM server).

Next steps#

Command menu
Search for a page, repository, change or request, or run a command