Self-hosting on managed cloud infrastructure

The default self-hosted stack bundles Postgres and Redis so a single host runs everything. Most production operators prefer their cloud provider's managed database and cache — backups, failover and patching handled by the provider, the data in the account and region the organization already governs. This page describes how Perihelium runs that way.

The external-infrastructure overlay

The distribution ships a compose overlay for external infrastructure. An overlay is a supported file you add, never a shipped file you edit, so an upgrade replaces the stack and leaves your configuration where it is. Applied, it:

• removes the bundled Postgres and Redis services;
• routes every database client — the API, the worker, the migration and bootstrap jobs, the backup job — to your managed Postgres over TLS with the server certificate verified (PGSSLMODE=verify-full and your provider's CA bundle), so no client can be left talking in clear;
• routes the cache clients to your managed Redis over TLS;
• keeps the grants step that runs after migrations, which gives the audit spine its append-only role. Skipping it would leave the audit chain unable to write, silently; the overlay cannot skip it.

The bootstrap runs with a non-superuser administrator, as managed providers require, and every statement it needs is one such a role can execute; a provider that refuses one fails the deploy at that statement rather than leaving a half-initialised database.

What Redis is for, and what a wipe loses

Redis holds the live state the platform must agree on across instances: sessions and refresh tokens (every access token carries a session id that is checked against Redis on each request), rate-limit counters, month-to-date API-call metering and the event streams the worker consumes. A managed Redis must be configured with no eviction (noeviction), persistence on, and support for Streams consumer groups.

The consequences are exact. A restart with persistence on loses nothing. A wipe, where the data is deleted, ends every active session, so people sign in again; rate-limit counters restart from zero; and the month's API-call metering restarts from zero, so usage for the month is under-counted. With Redis unreachable the platform cannot create or check a session, so new sign-ins and authenticated requests are refused, and the readiness check reports it.

Backups to object storage

With a managed database, the platform's daily logical dump writes to an S3-compatible bucket you name — your provider's object storage or your own — encrypted with a key you hold, through an egress allowlist you configure. The restore drill works from the dumps alone, on a fresh host, and is documented step by step with the expected output at each step; run it before you need it. Your provider's point-in-time recovery remains available beneath it.

The minimal footprint

Not every install wants the documentation site, the marketing site, the web application or the observability stack. Each is opt-in on a self-hosted install, and the console states which optional components are running, so an absent one reads as "not deployed", never as broken. The measured minimum for the authentication and governance core is published with each release in the distribution's notes, per container, from the build you are installing.

Secrets as files

Every secret the platform reads accepts a *_FILE variant naming a file on the host, so an install can mount secrets from your cloud's secret manager or a volume rather than placing values in the environment. The two forms are equivalent; the file form keeps secrets out of process listings and compose files.

The signed audit checkpoint

The audit chain's tip — its sequence number, hash and time — is published as a signed checkpoint under the install's published key, fetchable with an operator credential. An external log, your SIEM or a second install can witness it, so the chain's history cannot be rewritten between two readings without the rewrite showing. The checkpoint is the same artefact on the managed service and on your install.

The deployment health view

An operator's Deployment health page in the console shows readiness per dependency, backup freshness against the schedule and the latest signed checkpoint. The dependency snapshot behind it (the database connection pool, Redis memory and persistence, event-bus lag per consumer group, disk headroom and signing-key age) is on GET /api/v1/observability/health/deep for the platform operator's own monitoring.

Licences and environments

A self-hosted licence names its environment: one production install and the number of non_production installs the licence allows, each bound to its own install. A non-production install shows a persistent indicator in the console so nobody mistakes it. Exceeding a count warns the operator; it never refuses a sign-in.

Self-assurance on a self-hosted install

The tenant self-assurance catalogue runs on the managed service, where the platform owns the infrastructure the scenarios exercise. On a self-hosted install the platform's own assurance programme is published with each release, and the operator's security testing of the install is theirs to run against their own infrastructure.