Skip to main content

​
Single-server baseline

The default Compose stack runs PostgreSQL 16, Redis 7.2, a migration job, and Agent Server with an embedded worker. It is suitable for a single-host baseline and staging. Disable insecure development auth and configure TLS/OIDC before production use.

​
Independently scaled topology

The API is stateless and scales horizontally. Scale workers on PostgreSQL pending queue age/depth. API and worker images must contain the same lingxigraph.json and graph versions.

​
Release order

1

Build and validate

Build an immutable image; run tests, SBOM generation, dependency/image scans, signing, and lingxigraph doctor.
2

Migrate

Run lingxigraph migrate as a separate job. Migrations must remain compatible with currently running API/worker versions.
3

Roll out

Deploy workers first and Agent Server second. Keep an old graph version until no run remains pinned to it.
4

Canary

Create a canary run and verify state, event sequence, checkpoints, and traces.

​
Kubernetes

The Helm chart is in deploy/helm/lingxigraph:
The chart configures non-root UID 10001, read-only root filesystem, RuntimeDefault seccomp, startup/readiness/liveness probes, HPA, PDB, and graceful termination. Put database, OIDC, and provider credentials in Secrets or an external secret manager—not ConfigMaps.

​
Data and recovery

  • Enable TLS, encrypted backup, PITR, and high availability for PostgreSQL.
  • Redis contains no unique business state and can be rebuilt empty.
  • Back up the lingxigraph schema and migration version table.
  • Regularly test worker termination, Redis restart, brief database loss, and checkpoint recovery.
  • After fixing a dead letter, call POST /v1/runs/{id}/redrive; never use redrive to provide new input.
Deleting Compose volumes or the PostgreSQL schema permanently removes threads, runs, events, checkpoints, and Store data. Back up and verify recovery before doing so.