Install on Linux

Every GitHub release carries Linux builds of both programs for amd64 and arm64. loomctl is the command-line client, and you can put it on any machine. The server is loomplane (the API and dashboard) plus loomplane-worker (repository analysis), and it wants a host of its own with PostgreSQL. This page runs the server straight on the host under systemd. If you'd rather keep it in containers, Production on Docker covers that setup.

What a release ships for LinuxCopy Anchor Link

For a release tagged v1.2.3:

There's also a loomctl container image, ghcr.io/xraph/loomctl, for linux/amd64 and linux/arm64.

Download and verifyCopy Anchor Link

Pick the release and your architecture first. Every command below reuses these two variables:

VERSION=$(curl -fsSL https://api.github.com/repos/xraph/loomplane/releases/latest \
  | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
case "$(uname -m)" in
  x86_64) ARCH=amd64 ;;
  aarch64 | arm64) ARCH=arm64 ;;
  *) echo "Loomplane ships Linux builds for amd64 and arm64 only" >&2 ;;
esac
echo "$VERSION $ARCH"

That asks GitHub for the newest stable release. For a host you'll keep, set VERSION=1.2.3 yourself so you know what you installed. Then fetch the checksums and their signature next to whatever you download:

BASE=https://github.com/xraph/loomplane/releases/download/v$VERSION
curl -fsSLO "$BASE/binaries-checksums.txt"
curl -fsSLO "$BASE/binaries-checksums.txt.sigstore.json"

Once the files you want are in the same directory, check them. --ignore-missing skips everything in the list you didn't download:

sha256sum --check --ignore-missing binaries-checksums.txt

The checksum file proves the download wasn't damaged. To prove the Release workflow in xraph/loomplane made it, verify its signature with cosign:

cosign verify-blob \
  --bundle binaries-checksums.txt.sigstore.json \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/xraph/loomplane/\.github/workflows/release\.yml@refs/(tags/v.+|heads/main)$' \
  binaries-checksums.txt

It should print Verified OK. A release cut from the Actions tab is signed from main and one cut from a tag push from that tag, which is why the identity allows both. Once you have loomctl, loomctl node verify-release runs the same check without cosign.

Install loomctlCopy Anchor Link

curl -fsSLO "$BASE/loomctl_${VERSION}_${ARCH}.deb"
sha256sum --check --ignore-missing binaries-checksums.txt
sudo apt install "./loomctl_${VERSION}_${ARCH}.deb"

Check it, then sign in. --no-browser prints the sign-in address instead of opening it, which is what you want over SSH:

loomctl --version
loomctl login --url https://loomplane.example.com --no-browser

Open that address on your laptop or phone, check the code matches, and approve it. CI signs in with an API key instead, which CI with loomctl covers, and the loomctl reference lists every command.

Install the serverCopy Anchor Link

What you needCopy Anchor Link

• A Linux host on amd64 or arm64 with systemd 239 or newer. Ubuntu 20.04, Debian 11, RHEL 8 and anything newer qualify.
• PostgreSQL 17, on this host or reachable from it. A managed database works fine.
• A hostname pointed at the host, with TCP ports 80 and 443 open for HTTPS.
• 2 CPU cores and 8 GB of RAM to start, plus disk for the database, deployment sources and checkouts the worker unpacks (up to 2 GiB per analysis). Measure your own workload before you go smaller.

Loomplane never runs your code, so the host needs no Docker, no Git and no build tools.

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y
sudo apt install -y postgresql-17

DB_PASSWORD=$(openssl rand -hex 32)
sudo -u postgres psql -v ON_ERROR_STOP=1 \
  -c "CREATE ROLE loomplane LOGIN PASSWORD '$DB_PASSWORD'" \
  -c "CREATE DATABASE loomplane OWNER loomplane"
echo "postgres://loomplane:$DB_PASSWORD@127.0.0.1:5432/loomplane?sslmode=disable"

curl -fsSLO "$BASE/loomplane_${VERSION}_${ARCH}.deb"
sha256sum --check --ignore-missing binaries-checksums.txt
sudo apt install "./loomplane_${VERSION}_${ARCH}.deb"

openssl rand -base64 32
sudoedit /etc/loomplane/loomplane.env

sudo systemctl enable --now loomplane
curl -fsS http://127.0.0.1:8780/_/health/live && echo
sudo systemctl enable --now loomplane-worker
systemctl status loomplane loomplane-worker --no-pager

loomplane.example.com {
	# Health and metrics stay on the host.
	@internal path /_/health /_/health/* /_/metrics /_/metrics/* /debug/*
	respond @internal 404

	reverse_proxy 127.0.0.1:8780 {
		# Send events as they happen. WebSocket upgrades work as is.
		flush_interval -1
	}
}

sudo systemctl reload caddy

lp() {
  sudo -u loomplane sh -c 'cd /var/lib/loomplane && set -a && . /etc/loomplane/loomplane.env && set +a && exec loomplane "$@"' loomplane "$@"
}
lp setup-token
# Finish setup at https://loomplane.example.com/setup?token=...

Run it as a serviceCopy Anchor Link

The two units behave like any other systemd service:

systemctl status loomplane loomplane-worker
journalctl -u loomplane -u loomplane-worker -f
sudo systemctl restart loomplane

Change a setting by editing /etc/loomplane/loomplane.env and restarting both. systemd restarts either service if it exits with an error, and starts both at boot once you've enabled them.

The units lock things down. Each runs as loomplane with no capabilities, can't gain privileges, sees a read-only filesystem apart from its own directory under /var/lib and a private /tmp, and can't see /home. To change one, use a drop-in instead of editing the unit, so an upgrade doesn't overwrite it:

sudo systemctl edit loomplane

The loomplane binary has operator commands too: migrations, migrate, backup, restore and setup-token. Run them through the lp function from the setup step. Put it in root's shell profile if you'll use it often:

lp migrations
# N applied, 0 pending.

Backing up Loomplane covers backups. With this layout, the files to keep besides the database are /var/lib/loomplane and /etc/loomplane/loomplane.env, and the secret key belongs somewhere other than those backups.

UpgradeCopy Anchor Link

loomctlCopy Anchor Link

Install the newer package over the old one (sudo apt install ./loomctl_...deb or sudo dnf install ./loomctl-...rpm), or replace the binary in /usr/local/bin. Your sign-in stays.

The serverCopy Anchor Link

The order matters: back up, stop both services, install, start the API so it migrates, then start the worker. Upgrades and releases explains why, and how to roll back.

VERSION=1.2.4   # the release you're moving to

# Back up with the version you have now, while nothing writes.
sudo systemctl stop loomplane-worker loomplane
lp backup --out /var/lib/loomplane/pre-upgrade.tar.gz
sudo cp /var/lib/loomplane/pre-upgrade.tar.gz /root/

# Download and verify the new release as above, then install it.
sudo apt install "./loomplane_${VERSION}_${ARCH}.deb"   # or dnf install ./loomplane-...rpm

lp migrations   # shows what the new version will apply
sudo systemctl start loomplane
curl -fsS http://127.0.0.1:8780/_/health/live && echo
sudo systemctl start loomplane-worker

Copy that backup off the host too. The package keeps your loomplane.env, and it never starts or restarts the services by itself, so nothing runs the new version until you start it.

From the archive, it's the same order. Stop both, copy the new binaries into /usr/local/bin and the new dashboard into /usr/local/share/loomplane/, replace /etc/loomplane/config.yaml, then start the API and the worker. Compare the new systemd/ files with yours too, since a release can change them.

Loomplane won't start against a database a newer version migrated. Going back means restoring the backup you made before upgrading.

UninstallCopy Anchor Link

loomctlCopy Anchor Link

loomctl logout
sudo apt remove loomctl        # or: sudo dnf remove loomctl

From the archive, sudo rm /usr/local/bin/loomctl. loomctl logout ends your session on the server and deletes the saved login under ~/.config/loomplane.

The serverCopy Anchor Link

Removing the package stops and disables both services. It leaves your data, your settings and the loomplane user, in case you meant to reinstall:

sudo apt remove loomplane      # or: sudo dnf remove loomplane

apt purge loomplane removes /etc/loomplane as well. To remove everything else, once you're sure you have the backup you want:

sudo rm -rf /var/lib/loomplane /var/lib/loomplane-work /etc/loomplane
sudo userdel loomplane
sudo -u postgres psql -c "DROP DATABASE loomplane" -c "DROP ROLE loomplane"

From the archive, stop and disable both services, then delete the two unit files from /etc/systemd/system, the binaries from /usr/local/bin and /usr/local/share/loomplane, and run sudo systemctl daemon-reload before the commands above.