Deploy on AWS

Loams on AWS today is one EC2 instance running the 0.1.1 compose stack, reached only over your own Tailscale tailnet. For production, the same instance keeps the engine's data in an S3 bucket in your account, with the instance role as its credentials. The OpenTofu module, ECS Fargate and EKS 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 EC2 instance.

1. Launch the instanceCopy Anchor Link

Ubuntu 24.04 ships a 6.8 kernel. Loams House needs Linux 6.7 or later for its workers' Landlock rules; Amazon Linux 2023's default 6.1 kernel is older (verify for your AMI), so use Ubuntu.

The instance needs a public IPv4 address or a NAT gateway 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 portCopy Anchor Link

Use Session Manager from the EC2 console (Connect → Session Manager), or from your machine:

aws ssm start-session --target i-0123456789abcdef0

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

On the instance:

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 instance 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, with no port open.

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 a t3.large, 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 instance 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 ubuntu@<instance-tailnet-name>          # asks for TS_AUTHKEY
release/byoc/install.sh --tikv ubuntu@<instance-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 light default needs 4 GiB of memory, so t2.micro, t3.micro and t3.small are too small. AWS accounts created on or after 2025-07-15 get $200 of credits, and their Free Tier lasts six months or until the credits run out. Their eligible types include c7i-flex.large (2 vCPU, 4 GiB), which fits the light default, and m7i-flex.large (2 vCPU, 8 GiB), which fits the tikv profile (EC2 Free Tier usage; verify the list for your account and region). A t3.medium costs about $30 a month on demand in us-east-1 (estimate). Stop the instance when you are not using it; the EBS volume keeps the data.

To estimate the whole monthly bill on AWS (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 EC2 instance with the engine's bucket on S3. This is the development VM, sized up and with the bucket moved off the instance:

• Size: t3.large (2 vCPU, 8 GiB) with a 50 GB gp3 volume is design 70's small install, about $73 a month with S3, a KMS key and a public IPv4 (estimate).
• The bucket: create an S3 bucket in the same region, with Block Public Access on and versioning on. The engine needs S3's conditional writes, which S3 supports. Give the instance role s3:GetObject, s3:PutObject, s3:DeleteObject and s3:ListBucket on that bucket only.

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

# secrets/engine.env: no keys on EC2, the instance role is used
AWS_REGION=eu-west-1

On EC2 the engine uses the instance role when no keys are set. The engine runs in a container on the compose network, one network hop from the instance, so IMDSv2 must allow two hops or the engine cannot reach the role (verify; the symptom is Error performing PUT http://169.254.169.254):

aws ec2 modify-instance-metadata-options --instance-id i-0123456789abcdef0 \
  --http-tokens required --http-put-response-hop-limit 2

Set LOAMS_BUCKET before the first start. Named profiles (AWS_PROFILE) are not read.

What stays on the instance's disk: the embedded metastore, Live, Durable, and Loams Postgres's pageserver and safekeeper storage. The S3 bucket holds the engine's data, but the catalog that points into it is on the EBS volume. It is one node: there is no replica and no failover. For more than one engine, the tikv profile is the path in 0.1.1, still on one machine.

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:

• Snapshot the EBS volume on a schedule with Amazon Data Lifecycle Manager. For a consistent copy, docker compose stop first, or accept a crash-consistent snapshot.
• Turn on S3 versioning for 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 instance. 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. The security group has no inbound rules; the tailscale sidecar is the stack's only door. Machines on the tailnet, such as CI runners, use an API key.
• Planned AWS workloads off the tailnet, such as Lambda, reach the gateway's edge listener behind an internal NLB, or a PrivateLink endpoint service for other accounts (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 AWS workload identity 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 ubuntu@<host> --to <version> or loams upgrade on the instance. 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 AWSCopy Anchor Link