Skip to main content

Server quickstart

Install the server package globally (recommended for ops/dev machines):

npm i -g @liorandb/db

Install without npm:

  • Visit https://db.lioransolutions.com/download and download the server
  • After downloading, run ldb-serve

Start the server:

ldb-serve

Alternative entrypoint:

  • ldb (a convenience wrapper shipped by @liorandb/db)

Defaults:

  • HTTP: http://localhost:4000
  • Auth: username admin, password admin (change in production)
  • Storage: file-based local directories (no external DB required)
  • Studio: open http://localhost:4000 (bundled with the server) or use https://studio.lioransolutions.com

CLI flags (shared)​

The server and CLIs support:

  • --root <path>: override the storage root path
  • --ipc <primary|client|readonly>: process mode (see below)
  • -ed <key>: set encryption key directly
  • -ef <file>: read encryption key from a file

Write-queue tuning (backpressure):

  • --write-queue-max <n>
  • --write-queue-mode <wait|reject>
  • --write-queue-timeout-ms <ms>

Batch tuning:

  • --batch-chunk-size <n>

IPC modes (--ipc)​

Use --ipc when multiple server processes share the same --root path:

  • Primary (writer / lock owner): ldb-serve --ipc primary
  • Read-only (scale reads safely): ldb-serve --ipc readonly

In readonly mode, write endpoints respond with READONLY_MODE.

Environment variables​

In real deployments, prefer running the server with a local .env file (even outside Docker) so configuration is consistent across environments.

Create .env next to where you run ldb-serve:

# Server runtime
# Optional: load env vars from a specific file (defaults to `./.env` if present)
# LIORANDB_ENV_FILE=.env
LIORANDB_BASE_URL=http://localhost:4000
LIORANDB_TRUST_PROXY=1
LIORANDB_BODY_LIMIT=10mb

# Default admin bootstrap (created only if missing)
LIORANDB_DEFAULT_ADMIN_USERNAME=admin
LIORANDB_DEFAULT_ADMIN_PASSWORD=admin

# Engine root path (node-0 uses this path; node-1..node-9 use __cluster_nodes/node-i)
# LIORANDB_ROOT_PATH=C:\path\to\liorandb-data

# Single-node mode (disables internal multi-node cluster startup)
# If set, overrides LIORANDB_CLUSTER_NODES to 1.
# Also disables the local IPC listener used for multi-process access.
# LIORANDB_SINGLE_NODE=1

# In single-node mode, HTTP stays enabled by default (bound to 127.0.0.1).
# Set to 0/false/off to disable the API/dashboard.
# LIORANDB_HTTP_ENABLED=0

# HTTP bind host (useful in Docker so published ports work)
# LIORANDB_HTTP_HOST=0.0.0.0

# Cluster (server default is 10 nodes if unset)
LIORANDB_CLUSTER_NODES=10
LIORANDB_CLUSTER_HOST=127.0.0.1
LIORANDB_CLUSTER_RAFT_BASE_PORT=7100
LIORANDB_CLUSTER_WAL_BASE_PORT=8100
LIORANDB_CLUSTER_CLIENT_BASE_PORT=9100
LIORANDB_RPC_TOKEN=change-me

# Cache budget per node (MB)
LIORANDB_MAX_RAM_MB=12,288

# Optional: pass-through engine options (JSON) to enable newer features without server code changes
# LIORANDB_ENGINE_OPTIONS_JSON={"security":{"enabled":true}}

Common environment variables:

  • PORT (default 4000)
  • NODE_ENV
  • LOG_LEVEL
  • LIORANDB_IPC_MODE (primary|client|readonly) (equivalent to --ipc)

Write queue:

  • LIORANDB_WRITE_QUEUE_MAX
  • LIORANDB_WRITE_QUEUE_MODE (wait|reject)
  • LIORANDB_WRITE_QUEUE_TIMEOUT_MS

Batch:

  • LIORANDB_BATCH_CHUNK_SIZE