HeliosDB-Lite Production Deployment Guide

---

Table of Contents

1. Deployment Shape
2. System Requirements
3. Installation
4. Configuration
5. Running as a Service
6. Containers and Kubernetes
7. Security
8. High Availability
9. Backups
10. Monitoring
11. Upgrades

---

Deployment Shape

In production, HeliosDB Lite runs as a server: one heliosdb-lite start process per data directory. It serves:

Listener	Default	Purpose
PostgreSQL wire protocol	127.0.0.1:5432	SQL from any PostgreSQL driver or psql
HTTP	port 8080	REST API under /v1, /health, /metrics, /version
WAL replication	port 5433	Primary to standby streaming (replication roles only)

For development and single-user tools, heliosdb-lite repl opens the same database format in-process.

---

System Requirements

Minimum

Component	Requirement
CPU	2 cores
Memory	4 GB
Disk	10 GB
OS	Linux, macOS, Windows
Rust toolchain	Needed to build from the source distribution

Recommended for Production

Component	Recommendation
CPU	8+ cores
Memory	16+ GB
Disk	100+ GB SSD
Filesystem	ext4 or XFS with noatime

Size the disk for the data set after compression, plus write-ahead log space and room for dump files. As a starting point, provision SSD space of about 3.5x the raw data volume.

---

Installation

HeliosDB Lite is available to licensed customers as a source distribution; contact sales@heliosdb.com for access. There are no public binary downloads, crates.io packages or public container images.

# Inside the unpacked source distribution
cargo build --release
sudo cp target/release/heliosdb-lite /usr/local/bin/

# The CLI has no --version flag
heliosdb-lite --help

To check the build version, run \version inside heliosdb-lite repl --memory, or curl http://127.0.0.1:8080/version against a running server.

---

Configuration

Settings live in a TOML file passed with --config. Command-line flags override the file. A production starting point:

/etc/heliosdb/config.toml

[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 100

[storage]
wal_enabled = true
compression = "Zstd"          # "None", "Zstd" or "Lz4"
query_timeout_ms = 30000

[compression]
enable_alp = true             # numeric columns
enable_fsst = true            # string columns

[encryption]
enabled = true
key_source = { File = "/etc/heliosdb/encryption.key" }

Environment variables read by the server:

Variable	Purpose
HELIOSDB_JWT_SECRET	Signing secret for REST API tokens. Required: the server will not start without it
HELIOSDB_METRICS_KEY	Read-only key that unlocks /metrics and the detailed /health body
HELIOSDB_CORS_ALLOWED_ORIGINS	Comma-separated browser origins allowed to call the REST API
RUST_LOG	Log filter, for example RUST_LOG=info

See the CLI Reference for every flag and the Configuration reference for every TOML key.

---

Running as a Service

/etc/systemd/system/heliosdb.service

[Unit]
Description=HeliosDB Lite
After=network.target

[Service]
User=heliosdb
Group=heliosdb
# HELIOSDB_JWT_SECRET, HELIOSDB_METRICS_KEY and the admin password live here (mode 600)
EnvironmentFile=/etc/heliosdb/secrets.env
ExecStart=/usr/local/bin/heliosdb-lite start \
  --data-dir /var/lib/heliosdb \
  --config /etc/heliosdb/config.toml \
  --auth scram-sha-256 --password ${HELIOSDB_ADMIN_PASSWORD} \
  --tls-cert /etc/heliosdb/server.crt --tls-key /etc/heliosdb/server.key
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now heliosdb

Without systemd, heliosdb-lite start --daemon --pid-file /var/run/heliosdb.pid runs the server in the background, and heliosdb-lite stop / heliosdb-lite status manage it through the same PID file.

---

Containers and Kubernetes

Build an image from the source distribution and push it to your private registry. The Docker Deployment guide covers single-node and replicated Compose setups.

For Kubernetes, run each node as a StatefulSet replica with its own persistent volume, pass HELIOSDB_JWT_SECRET from a Secret, and probe GET /health on the HTTP port:

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  periodSeconds: 10

---

Security

• Authentication: start with --auth scram-sha-256 --password .... The default, trust, accepts every connection and is for local development only.
• Listen address: keep the default 127.0.0.1 unless clients on other hosts must connect; put a firewall in front of any other address.
• TLS: start with --tls-cert and --tls-key. The server then offers TLS to every client; require it on the client side with sslmode=require or stricter.
• Encryption at rest: see the Encryption Quick Start.
• Row-level security: superusers bypass RLS, so connect applications as non-superuser roles. See the RLS Quick Start.

See Security Hardening for the full checklist.

---

High Availability

HeliosDB Lite streams its write-ahead log from a primary to standbys. Replication needs a binary built with cargo build --release --features ha-tier1:

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
# Primary
heliosdb-lite start --data-dir /var/lib/heliosdb --config /etc/heliosdb/config.toml \
  --replication-role primary --standby-hosts standby1.internal:5433 --sync-mode semi-sync

# Standby
heliosdb-lite start --data-dir /var/lib/heliosdb --config /etc/heliosdb/config.toml \
  --replication-role standby --primary-host primary.internal:5433

Export HELIOSDB_JWT_SECRET in each node’s environment first. Replication traffic is encrypted with TLS when the node is started with --tls-cert (or with --replication-tls true). See High Availability for roles, sync modes and failover.

---

Backups

Use heliosdb-lite dump for logical backups:

# Dump a stopped data directory for a consistent copy
heliosdb-lite dump --data-dir /var/lib/heliosdb \
  --output /backups/heliosdb-$(date +%Y%m%d).heliodump

# Restore into a new data directory, checking integrity first
heliosdb-lite restore --input /backups/heliosdb-20260101.heliodump \
  --target /var/lib/heliosdb-restored --verify

Encrypt and copy dump files off the host, keep the encryption key backed up separately, and test restores regularly. See Dump and Restore.

---

Monitoring

Endpoint	Access	Returns
GET /health	Anyone	{"status":"ok"} while the process serves HTTP
GET /health	With the metrics key	Detailed checks (disk, memory, WAL, connections); 503 when unhealthy
GET /metrics	With the metrics key	Prometheus metrics; 403 without the key

Present the key as Authorization: Bearer <key> or x-metrics-key: <key>:

prometheus.yml

scrape_configs:
  - job_name: heliosdb-lite
    authorization:
      credentials: <HELIOSDB_METRICS_KEY value>
    static_configs:
      - targets: ['db1.internal:8080']

Inside the database, pg_stat_activity and the HeliosDB system views report sessions, statements and storage; see the System View Catalog.

Suggested starting alert thresholds: CPU above 80%, memory above 90% and free disk below 10%.

---

Upgrades

1. Dump the database (heliosdb-lite dump) and copy the data directory.
2. Build the new release from the licensed source distribution.
3. Stop the server (systemctl stop heliosdb or heliosdb-lite stop).
4. Install the new binary and start the server.
5. Check curl http://127.0.0.1:8080/version and run a smoke query.

Read the release notes for the target release before upgrading; they list storage-format and configuration changes.