DocsDeployConfiguration

Configuration

Operator-oriented configuration cheatsheet. For the complete variable list with source-file references and consumer paths, see Server & CLI reference — that page is the canonical source of truth. This page provides .env examples, defaults rationale, and a pre-production checklist.

Where to look up every variable

Server & CLI reference → Environment variables lists all 22 variables the binary reads, with source-file line numbers and consumer paths. Every variable documented on the Deploy pages traces back to that table. Do not rely on memory — check the reference page.

Minimal .env (development)

.env (development)
# Minimal .env for local development (RocksDB default, no auth required)
RUST_LOG=topgun_server=info
# STORAGE_BACKEND defaults to rocksdb — omit for zero-config local dev
# TOPGUN_DATA_DIR defaults to ./topgun-data — omit to keep the store in cwd

Zero configuration needed for local development: pnpm start:server uses the embedded RocksDB store by default, binds to 0.0.0.0:8080, and does not require JWT_SECRET (auth is skipped when the variable is absent). Add TOPGUN_NO_AUTH=true if you want to disable auth checks explicitly (test and demo use only — do not enable in production).

Production .env

.env (production)
# Production .env — embedded store on a persistent volume, auth enabled, memory tuned for 4 GB instance
RUST_LOG=topgun_server=info
TOPGUN_LOG_FORMAT=json

# Storage
STORAGE_BACKEND=rocksdb
TOPGUN_DATA_DIR=/data/topgun-data
TOPGUN_REDB_PATH=/data/topgun.redb
TOPGUN_WAL_DIR=/data/topgun-wal

# Auth (required in production — never disable)
JWT_SECRET=your-production-secret-min-32-chars

# Admin UI credentials
TOPGUN_ADMIN_USERNAME=admin
TOPGUN_ADMIN_PASSWORD=your-secure-admin-password

# Memory ceiling — set to 80% of instance RAM
# Example: 4 GB instance → 3200 MB
TOPGUN_MAX_RAM_MB=3200
TOPGUN_EVICTION_HIGH_PCT=85
TOPGUN_EVICTION_LOW_PCT=70
TOPGUN_EVICTION_INTERVAL_MS=1000

# Write-behind buffer
# Idle linger: the longest a buffered write waits while the flush task is idle (default 100)
TOPGUN_WRITEBEHIND_FLUSH_INTERVAL_MS=100
# BATCH_SIZE is accepted and has no effect: a flush pass is fixed at 1000 entries or 8 MiB
TOPGUN_WRITEBEHIND_BATCH_SIZE=100
TOPGUN_WRITEBEHIND_CAPACITY=10000
# Soft bound on the memory of buffered values, in MiB (default 256; 0 disables it)
TOPGUN_WRITEBEHIND_CAPACITY_MB=256

# Bind address (explicit for containers)
TOPGUN_BIND_ADDR=0.0.0.0

Copy this file, fill in your secrets, and mount it into your container or pass it via your deployment system’s secret management.

Defaults rationale

The server emits its effective configuration at startup (tracing::info!) so operators can confirm the active values without reading source.

Why 1024 MB TOPGUN_MAX_RAM_MB? Conservative ceiling for a fresh demo server. At 1 GB, the cache holds tens of millions of CRDT records before eviction engages. For a production instance, set this to ~80% of available RAM.

Why 85 / 70 water marks? The 15-percentage-point gap between TOPGUN_EVICTION_HIGH_PCT (85) and TOPGUN_EVICTION_LOW_PCT (70) prevents eviction churn: after the high-water mark triggers a flush, the eviction loop does meaningful work (removing 15% of capacity) before stopping. Narrower gaps (e.g., 85/83) cause the eviction loop to wake, do trivial work, and wake again immediately under continuous write pressure.

Why a 100 ms write-behind interval (TOPGUN_WRITEBEHIND_FLUSH_INTERVAL_MS)? A write is acknowledged once it is in the write-ahead log, and the write-behind buffer then carries it to the store. There is no write delay: a write is due as soon as it is buffered. A flush pass cut by its limit (1000 writes or 8 MiB) is followed by the next one at once; after a pass that took every due write the flush task waits up to the interval, so writes arriving meanwhile are stored in one pass. The interval is how long a buffered write waits while the flush task is idle, and so the window in which a pass forms. Measured on a Mac (M1 Max) with the open-loop load harness, the server in-process on RocksDB, offering 2·10⁴ writes/s of new keys with values of tens of bytes, against the previous release run with TOPGUN_WRITEBEHIND_CAPACITY=0 (its acknowledgement path with the buffer unbounded; at its defaults it acknowledges about a quarter of that load): a 10 ms linger, run with capacity 0, formed passes of about 270 writes and acknowledged 3–4 % fewer writes per second than that comparator; 100 ms, at the default capacity, formed passes of about 800 and matched it. It bounds how many new keys a node admits: about TOPGUN_WRITEBEHIND_CAPACITY / (interval + 2 × pass time) per second (a key holds its place until the pass that took it is stored). The old default of 1000 held that near 10⁴ per second, and any value of 500 or more logs a startup warning; remove an explicit 1000 from older configurations. 0 refuses to start.

Why a byte bound on the write buffer (TOPGUN_WRITEBEHIND_CAPACITY_MB, default 256)? TOPGUN_WRITEBEHIND_CAPACITY bounds how many keys wait for the store, not how large their values are, and an OR slot can grow with every write to it while the store is down. The byte bound caps the memory of the waiting values: at or above it, a plain write that grows its key’s buffered value is refused, and so is every in-place OR write — OR add and remove, the tombstone prune, the TTL sweep’s OR removals and a client’s OR push diff — before it changes anything, because its growth is not known before it runs. Both bounds are decided before a write changes anything, so a write refused at a bound is seen by no read and no subscriber; a write refused after that decision — because the store failed or began shutting down, its tenant was being closed, or its write-ahead-log append failed — is not covered, and its change stays visible (TODO-992). A refusal is a temporary error: the client keeps the write and sends it again, a refused prune is retried by a later pass, and a client’s push diff is merged up to the refused entry, with the rest merged at the client’s next connection (nothing is lost; the client keeps its records). The byte bound never refuses a remove, a remove_all, an LWW write of a top-level null or a rewrite that does not grow, since those relieve the pressure; the key bound is unchanged and still refuses a remove of a key that is not buffered once TOPGUN_WRITEBEHIND_CAPACITY keys are buffered. A single value larger than the budget is admitted into a buffer below it, so no write is refused for ever while the store accepts. Values are counted at a structural estimate of their stored encoding, not at their heap size. 0 disables the bound; a value that does not parse warns and uses the default; a value whose bytes do not fit in 64 bits ends the process at startup with the panic message on stderr and exit status 101. The memory adds to TOPGUN_MAX_RAM_MB. Measured on Linux (Hetzner ccx33, 8 vCPU AMD EPYC-Milan) with the in-process open-loop load harness on RocksDB, at the default bounds, values of 0 bytes, three runs of this release against six of the release before it: at 2·10⁴ and at 4·10⁴ new keys/s both acknowledged the offered rate with no refusal in every run, and at 4·10⁴/s the service latency of this release was p50 1.12–1.15 ms and p99 9.37–11.06 ms, against 1.13–1.16 ms and 9.93–11.12 ms. No throughput or latency difference between the releases is claimed: in an earlier series on the same host class the release before it reached its 10 000-key bound at 4·10⁴/s and refused writes in 4 of 6 runs, in this one in none, and the latencies of both releases were about 0.5 ms lower in this series. With 4 KiB values at 10⁴/s (key bound off) the buffered charge (the structural estimate, not heap bytes) peaked at 4.7–49.1 MB in three runs, with 64 KiB values at 10³/s at 7.8–9.6 MB; the byte bound refused nothing at the default budget. Throughput smoke (median of three, 50 connections, 10 s): fire-and-wait 9 542 ops/s against 9 553, fire-and-forget 534 080 against 540 334. Not shown: that the key bound is never reached at 4·10⁴/s (peak 4 456 of 10 000 keys in three runs), any figure at 8·10⁴/s (the load generator was the limit), a throughput gain, or a latency difference between the releases.

Why 271 partitions? Fixed in the binary as PARTITION_COUNT = 271 (a prime) in packages/topgun-core. Prime partition counts reduce hash collisions in consistent-hashing cluster layouts. Not user-configurable via env var; changing it requires a rebuild.

Pre-production checklist

Before going live, verify:

  • Auth is enabled. JWT_SECRET is set to a random string of at least 32 characters. TOPGUN_NO_AUTH is not set (or is false). INSECURE_FORWARD_AUTH_ERRORS is not set (or is false).
  • Storage backend is set. STORAGE_BACKEND=rocksdb (the default) with TOPGUN_DATA_DIR and TOPGUN_WAL_DIR pointing to the same persistent volume (the image defaults are /data/topgun-data and /data/topgun-wal). TOPGUN_REDB_PATH (image default /data/topgun.redb) names only the store file of earlier versions, which is migrated into the data directory once; see Storage backends.
  • TLS is terminated externally. The binary does not read TOPGUN_TLS_* env vars today. Use a reverse proxy (nginx, Caddy, AWS ALB) to terminate TLS in front of the server.
  • Memory ceiling is set. TOPGUN_MAX_RAM_MB is set to ~80% of your instance RAM. Default 1024 MB is tuned for demo; most production instances have more.
  • Log format is set. For log aggregators (Datadog, CloudWatch, Splunk), set TOPGUN_LOG_FORMAT=json. Default is human-readable text.
  • Admin credentials are changed. TOPGUN_ADMIN_USERNAME defaults to admin; TOPGUN_ADMIN_PASSWORD has no default and causes a startup error if the admin UI is served — set it explicitly.
  • Bind address is explicit. TOPGUN_BIND_ADDR=0.0.0.0 in containers ensures the server listens on all interfaces, not just loopback.