Deploy on Google Cloud

Loams on Google Cloud today is one Compute Engine VM running the 0.1.1 compose stack, reached only over your own Tailscale tailnet. For production, the same VM keeps the engine's data in a Cloud Storage bucket in your project, with the VM's service account as its credentials. The OpenTofu module, Cloud Run and GKE paths are planned; the overview compares the clouds.

Read Self-hosting over Tailscale steps 1 to 4 first: create the tailnet, turn on MagicDNS and HTTPS certificates, add the tag:loams policy, and create an auth key. This page does not repeat them.

Development (VM)Copy Anchor Link

Available The light default stack on one Compute Engine VM.

1. Create the VMCopy Anchor Link

Ubuntu 24.04 ships a 6.8 kernel. Loams House needs Linux 6.7 or later for its workers' Landlock rules; Debian 12's 6.1 kernel is older, so use Ubuntu.

The VM needs an external IP or Cloud NAT for outbound traffic only: to pull images, download the bundle and reach Tailscale's coordination servers. Nothing listens on that address.

2. Open a shell without opening a port to the internetCopy Anchor Link

Use SSH through Identity-Aware Proxy TCP forwarding:

gcloud compute ssh my-loams-vm --zone europe-west1-b --tunnel-through-iap

3. Install Docker and, if you like, Tailscale on the hostCopy Anchor Link

On the VM:

curl -fsSL https://get.docker.com | sudo sh        # Docker Engine with the Compose plugin
sudo usermod -aG docker "$USER"                    # then open a new shell

# Optional: put the VM itself on your tailnet, for SSH over the tailnet
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --ssh

The stack does not need Tailscale on the host. Its own tailscale sidecar container joins the tailnet as loams. The host client only gives you a second way in for SSH.

4. Download the bundle, verify it, start the stackCopy Anchor Link

base=https://github.com/ostrium-labs/loams/releases/download/v0.1.1
curl -fLO $base/loams-compose-0.1.1.tar.gz -fLO $base/SHA256SUMS -fLO $base/SHA256SUMS.asc

# the release signing key; check that its fingerprint is
# 333A C945 99D5 A1EB 2A41 6D1E 83DC 134D 8CAF 895D
curl -fsSL https://raw.githubusercontent.com/ostrium-labs/loams/main/docs/release/loams-release-key.asc | gpg --import
gpg --verify SHA256SUMS.asc SHA256SUMS            # "Good signature from Loams Release Signing Key"
sha256sum --ignore-missing -c SHA256SUMS          # loams-compose-0.1.1.tar.gz: OK

tar -xzf loams-compose-0.1.1.tar.gz
cd loams-compose-0.1.1/release
cp .env.example .env

Edit .env:

TS_AUTHKEY=tskey-auth-…                          # tagged tag:loams
LOAMS_TAILSCALE_ALLOWED_USERS=you@example.com
LOAMS_SETUP_TOKEN=                               # the output of: openssl rand -hex 32
# COMPOSE_PROFILES=tikv                          # only on an e2-standard-2, before the first start

Then:

docker compose up -d
docker compose ps                                # every service running
docker compose exec tailscale tailscale status   # the stack is on your tailnet

Or from your own machine, once the VM is on your tailnet: unpack the same bundle locally and run the installer over SSH. It installs Docker if missing, copies the bundle to ~/loams, writes .env with mode 0600, generates LOAMS_SETUP_TOKEN and starts the stack.

cd loams-compose-0.1.1
release/byoc/install.sh you@<vm-tailnet-name>          # asks for TS_AUTHKEY
release/byoc/install.sh --tikv you@<vm-tailnet-name>   # with PD, TiKV and TiDB

5. Use itCopy Anchor Link

From a device on the same tailnet, the engine is at https://loams.<tailnet>.ts.net.

• Loams Desktop, in 0.1.1: add that URL as a server. Get it from the download page.
• The console the engine serves at /ui/: Planned for 0.1.2.
• Run first-run setup once, with the setup token, as in Self-hosting step 7.

Free tier and creditsCopy Anchor Link

The always-free e2-micro has 1 GB of memory, too little for the stack. New Google Cloud customers get $300 of credits for 90 days, which covers an e2-medium or an e2-standard-2 for the whole trial (verify on Google Cloud's free program). An e2-medium costs about $25 a month on demand (estimate). Stop the VM when you are not using it; the disk keeps the data.

To estimate the whole monthly bill on Google Cloud (compute, disk, bucket, requests and egress, from public list prices), use the cost calculator. Loams itself is free.

ProductionCopy Anchor Link

What is supported todayCopy Anchor Link

Available One Compute Engine VM with the engine's bucket on Cloud Storage. This is the development VM, sized up and with the bucket moved off the VM:

• Size: e2-standard-2 (2 vCPU, 8 GB) with a 50 GB pd-balanced disk is design 70's small install, about $60 a month with the bucket and an external IPv4 (estimate).
• The bucket: create a Cloud Storage bucket in the VM's region with uniform bucket-level access, public access prevention and object versioning. Cloud Storage supports the conditional writes the engine needs. Grant the VM's service account object read and write on that bucket only.

# .env
LOAMS_BUCKET=gs://my-loams-bucket/loams

On Compute Engine, leave GOOGLE_SERVICE_ACCOUNT_KEY out of secrets/engine.env and the engine uses the VM's service account. The VM's access scopes must allow Cloud Storage writes; the default scopes give Storage read only, so set the scope to cloud-platform and control access with IAM (verify). Off Google Cloud, put the service account's JSON key on one line in GOOGLE_SERVICE_ACCOUNT_KEY instead. Set LOAMS_BUCKET before the first start.

What stays on the VM's disk: the embedded metastore, Live, Durable, and Loams Postgres's pageserver and safekeeper storage. The bucket holds the engine's data, but the catalog that points into it is on the persistent disk. It is one node: there is no replica and no failover.

Loams House runs on chDB today, inside the loams-fabric image, and is experimental. Our own Rust engine for it is designed (design 75), not built.

BackupsCopy Anchor Link

What you can do today:

• A snapshot schedule on the VM's disk. For a consistent copy, docker compose stop first, or accept a crash-consistent snapshot.
• Object versioning on the bucket.
• Keep .env and secrets/ somewhere safe; they are not in the volumes.
• loams upgrade takes a snapshot before each upgrade, in a local volume on the VM. It is not an off-machine backup.

Planned loams backup create, writing the same snapshot into your own bucket (design 70, BY1).

NetworkingCopy Anchor Link

• Today: your tailnet only. No ingress firewall rule reaches the VM; the tailscale sidecar is the stack's only door. Machines on the tailnet, such as CI runners, use an API key.
• Planned Google Cloud workloads off the tailnet, such as Cloud Run services, reach the gateway's edge listener behind an internal load balancer, or a Private Service Connect attachment for other projects (design 69). The engine is never public.

IdentityCopy Anchor Link

• Today: one organization per install, created by first-run setup. Sign-in is your Tailscale login (tailscale), an OIDC issuer you choose (oidc), or API keys (apikey). Authorization is coarse.
• Planned Zitadel and OpenFGA (design 76), and the metadata server's ID token exchanged for a Loams token (design 69).

UpgradesCopy Anchor Link

0.1.1 changes the default stack; reinstall. Start from the 0.1.1 bundle with a fresh .env. After that, a stack with the tikv profile upgrades in place with release/byoc/upgrade.sh you@<host> --to <version> or loams upgrade on the VM. A stack on the default embedded stores is upgraded by hand for now: back up, docker compose stop, set LOAMS_VERSION, docker compose up -d.

Planned for Google CloudCopy Anchor Link