---
title: "HeliosDB-Lite Production Deployment Guide"
---

# HeliosDB-Lite Production Deployment Guide

---

## Table of Contents

1. [Deployment Shape](#deployment-shape)
2. [System Requirements](#system-requirements)
3. [Installation](#installation)
4. [Configuration](#configuration)
5. [Running as a Service](#running-as-a-service)
6. [Containers and Kubernetes](#containers-and-kubernetes)
7. [Security](#security)
8. [High Availability](#high-availability)
9. [Backups](#backups)
10. [Monitoring](#monitoring)
11. [Upgrades](#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](mailto:sales@heliosdb.com) for access. There are no public binary
downloads, crates.io packages or public container images.

```bash
# 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:

```toml
# /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](/docs/lite/reference/cli/) for every flag and the
[Configuration reference](/docs/lite/user-guide/configuration/) for every TOML key.

---

## Running as a Service

```ini
# /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
```

```bash
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](/docs/lite/guides/docker_deployment/) 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:

```yaml
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](/docs/lite/guides/encryption_quickstart/).
- **Row-level security**: superusers bypass RLS, so connect applications as
  non-superuser roles. See the [RLS Quick Start](/docs/lite/guides/rls_quickstart/).

See [Security Hardening](/docs/lite/guides/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`:

```bash
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](/docs/lite/features/high-availability/) for roles, sync modes and
failover.

---

## Backups

Use `heliosdb-lite dump` for logical backups:

```bash
# 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](/docs/lite/guides/user/dump_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>`:

```yaml
# 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](/docs/lite/reference/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](/docs/lite/releases/) for the target release before
upgrading; they list storage-format and configuration changes.