psvensson/lagrange repository overview

⁠Lagrange

Distributed SQL database and compute-near-data runtime: a cluster of equal nodes that stores partitioned, Raft-replicated SQL tables and runs your compute (JS/WASM services) on the node that owns the data it reads.

• Source / issues: https://codeberg.org/psvensson/lagrange⁠
• License: AGPL-3.0-only
• Mirror registry: codeberg.org/psvensson/lagrange (same image, best-effort mirror of this repository)

⁠Tags

Images are linux/amd64 only and built on distroless Node.js 22⁠ — there is no shell, package manager, or npm inside the container.

⁠Quick start — single node

docker run --rm -p 8080:8080 -p 8081:8081 -p 8082:8082 psvensson/lagrange:latest

A node started without SEED_NODE_ADDRESS becomes the seed of a new cluster. It opens three ports:

To interact with the node, connect the admin CLI from a checkout of the repository (the image itself has no shell to exec into):

git clone https://codeberg.org/psvensson/lagrange && cd lagrange
npm install
npm run cli    # interactive terminal UI against localhost:8081

⁠Multi-node cluster

One container per node — two nodes cannot share a network namespace because the admin port is fixed at 8081. Joiners point SEED_NODE_ADDRESS at the seed and advertise an address other nodes can reach:

docker network create lagrange-net

docker run -d --name seed --network lagrange-net \
  -e TRANSPORT_WS_HOST=0.0.0.0 \
  -e NODE_ADDRESS=seed:8080 \
  -e NODE_ADVERTISED_WS_ADDRESS=seed:8082 \
  psvensson/lagrange:latest

docker run -d --name node2 --network lagrange-net \
  -e TRANSPORT_WS_HOST=0.0.0.0 \
  -e NODE_ADDRESS=node2:8080 \
  -e NODE_ADVERTISED_WS_ADDRESS=node2:8082 \
  -e SEED_NODE_ADDRESS=http://seed:8080 \
  psvensson/lagrange:latest

Leave NODE_ID unset: join admission requires a UUID identity, which the node mints on first start and restores from its data directory on restart.

⁠Configuration

Set via environment variables (-e):

⁠Persistence

All state — partition storage, Raft logs, and the node's durable identity — lives under DATA_DIR (/app/data). Mount a volume to survive container replacement:

docker run -d -v lagrange-data:/app/data -p 8080:8080 -p 8081:8081 -p 8082:8082 \
  psvensson/lagrange:latest

⁠Kubernetes

The repository ships a Helm chart (1 seed + N joiner StatefulSets, name-first addressing, per-pod PVCs) that deploys this image: charts/lagrange-node⁠.

⁠Memory

The container starts Node with --max-old-space-size=1536. Give the container more than that (the Helm chart defaults to a 2 GiB limit), or override the heap cap by replacing the command:

docker run ... psvensson/lagrange:latest --max-old-space-size=3072 src/index.js

⁠Learn more

• README — what Lagrange is, mental model, examples⁠
• Architecture overview⁠
• Release process and guarantees⁠