---
title: "Production Deployment: Advanced Deployment Scenarios"
---

# Production Deployment: Advanced Deployment Scenarios

**Part of**: [Production Deployment Guide](https://www.heliosdb.com/docs/full/deployment/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](/docs/full/reference/configuration/) 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

:::caution[TLS: next release]
HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in
front, and native PostgreSQL TLS (with post-quantum key exchange preferred) is
planned for the next release. The `--tls-cert`, `--tls-key` and `--tls-require`
flags in this section belong to that release.
:::

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).

```bash
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](https://www.heliosdb.com/docs/full/deployment/production_deployment_backup/)) 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:

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

```bash
# 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](https://www.heliosdb.com/docs/full/deployment/production_deployment_backup/)).

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

---

## Navigation

- **Previous**: [Troubleshooting](https://www.heliosdb.com/docs/full/deployment/production_deployment_troubleshooting/)
- **Next**: [Production Checklist](https://www.heliosdb.com/docs/full/deployment/production_deployment_checklist/)
- **Index**: [Production Deployment Guide](https://www.heliosdb.com/docs/full/deployment/production_deployment_guide/)