Skip to content
HeliosDB HeliosDB Full

Production Deployment: Advanced Deployment Scenarios

Part of: Production Deployment Guide

Each scenario below uses the heliosdb-full server, its flags and environment variables, and standard infrastructure (systemd, containers, Kubernetes, load balancers, storage snapshots). The Server Configuration Reference lists every flag used here.

A heliosdb-full server is a single node that owns one data directory. Scenarios that span sites or versions are built around that: one active server per data directory, with copies of the directory moved between servers.

10.1 Hybrid Cloud Deployment

Run the server where the data must live (on premises or in one cloud) and reach it from the other environment over a private link (site-to-site VPN, Direct Connect / ExpressRoute / Interconnect).

Terminal window
heliosdb-full --data-dir /var/lib/heliosdb \
  --bind-addr 10.20.0.5 --allow-external \
  --tls-cert /etc/heliosdb/tls/server.crt --tls-key /etc/heliosdb/tls/server.key --tls-require
  • Bind to the private interface only, not 0.0.0.0.
  • Require TLS on the PostgreSQL listener; tunnel the plaintext listeners (HTTP, MySQL, Oracle and others) through the private link or a TLS proxy.
  • Keep a copy of the data directory in the second environment with storage snapshots (see Backup & Disaster Recovery) so it can take over.

10.2 Air-Gapped Environment

The server needs no outbound network access. To install without internet:

  1. On a connected machine, save the image (docker save <heliosdb-full-image> -o heliosdb-full.tar) or copy the heliosdb-full binary, and record its checksum (sha256sum).
  2. Transfer the file through your approved media process and verify the checksum.
  3. Load the image (docker load -i heliosdb-full.tar) into the internal registry, or install the binary under /usr/local/bin.
  4. Leave the AI routes of the HTTP gateway unconfigured (no HELIOSDB_AI_* variables), or point HELIOSDB_AI_API_BASE at an internal model server with HELIOSDB_AI_ALLOW_PRIVATE_NETWORK=1.

10.3 Multi-Tenancy Deployment

Tenant isolation is achieved by running a server per tenant (or per tenant group), each with its own data directory, credentials and ports:

Terminal window
# tenant-a (its own environment file with its own HELIOSDB_SUPERUSER_PASSWORD)
heliosdb-full --data-dir /srv/heliosdb/tenant-a --postgres-port 15432 --http-port 18443
# tenant-b
heliosdb-full --data-dir /srv/heliosdb/tenant-b --postgres-port 25432 --http-port 28443

In Kubernetes, use one StatefulSet (or Helm release) per tenant in its own namespace with its own PersistentVolumeClaim, Secret and NetworkPolicy. Inside one server, roles authenticate separately (CREATE ROLE ... LOGIN PASSWORD, CONNECTION LIMIT), but every role that logs in can read all data: GRANT/REVOKE, row-level security and CREATE TENANT return SQLSTATE 0A000 in the current release. Per-IP connection and query limits (--conn-rate-limit, --query-rate-limit) protect each server from a noisy client.

10.4 Edge Computing Deployment

The server runs on small hosts as well as large ones. For an edge site:

  • Use a small read cache (--read-cache-mb 64 or leave it off) and lower --max-connections.
  • Keep --synchronous-commit on if the site loses power unexpectedly; the WAL recovers committed writes.
  • Ship data to the central site with your integration tooling (scheduled SELECT exports, application-level sync) and back up the edge data directory with snapshots.

10.5 Disaster Recovery Testing

Test recovery regularly with a restore, not just a backup:

Terminal window
# 1. Restore the latest backup into a scratch location
mkdir -p /tmp/dr-test && tar -C /tmp/dr-test -xzf /backup/heliosdb-latest.tar.gz


# 2. Start it on spare ports, without external access
heliosdb-full --data-dir /tmp/dr-test/heliosdb --postgres-port 55432 --http-port 58443 &


# 3. Verify
curl -fsS http://127.0.0.1:58443/ready
psql "host=127.0.0.1 port=55432 user=postgres" -c "SELECT COUNT(*) FROM orders"


# 4. Record the time from step 1 to step 3 as your measured recovery time
kill %1

10.6 Blue-Green Deployment

Use blue-green for server upgrades:

  1. Blue serves traffic. Stop it at the start of the window (SIGTERM flushes storage), copy or snapshot its data directory.
  2. Start green (new version) on the copy and verify it: heliosdb-full --version, /ready, a smoke-test query set.
  3. Switch clients (DNS, load-balancer target, Kubernetes Service selector) to green.
  4. Keep blue’s directory untouched until green has run for an agreed period; rolling back means pointing clients back at blue with its own copy.

Writes are not mirrored between blue and green, so plan the window so that no writes reach blue after the copy, or replay them.

10.7 Canary Deployment

For a read-mostly workload, start the new version on a copy of the data and send a share of read-only traffic to it (separate connection string, load-balancer weight) to compare latency and results before switching writes. For write traffic, use blue-green above: two servers must never share a data directory.

10.8 Geographic Distribution

Place the server close to the applications that write to it. For readers in other regions:

  • Serve read-heavy, latency-sensitive data from regional copies refreshed from snapshots on a schedule, and accept their staleness.
  • Keep a restore-ready copy in a second region for disaster recovery (Backup & Disaster Recovery).

Built-in multi-region replication is not part of the current server (SHOW REPLICATION STATUS returns 0A000).