Self-host Norn
This section covers running Norn on infrastructure you control. You operate the compute, network, data services, backups, upgrades, and observability.
Choose a deployment method
| Method | Best for | Status |
|---|---|---|
| Docker Compose | A single host, installed with one command and configured in one file | Available |
| Kubernetes with Helm | Existing Kubernetes platforms and teams that want declarative upgrades, health checks, and configurable backing services | Available |
The deployment methods are alternatives. Choose one for an instance; do not combine their lifecycle steps or configuration files.
What every deployment runs
Norn has three long-running workloads and three data dependencies:
| Component | Responsibility | Scaling model |
|---|---|---|
| API | HTTP API, authentication, and realtime connections | Horizontally scalable |
| Web | Server-rendered dashboard | Horizontally scalable |
| Worker | Scheduled and asynchronous work | Exactly one instance |
| PostgreSQL | Primary datastore | Required |
| Valkey | Sessions, rate limits, cache, policy synchronisation, and the job queue | Required; eviction must be disabled |
| Attachment storage | Attachments and import payloads | Required; a local volume or S3-compatible storage |
The API and web workloads must share one public origin.
Attachments are stored either on a volume the API and worker share, or in an S3-compatible bucket. With a bucket, clients transfer objects directly using presigned URLs, so it needs a second browser-accessible origin and a CORS policy. On one host a shared volume avoids both; across a cluster there is no shared volume, so object storage is the practical answer.
Before you deploy
Decide who owns each operational responsibility:
- DNS and publicly trusted TLS certificates
- PostgreSQL, Valkey, and object-storage durability
- encryption-key and credential custody
- database and object backups, including restore tests
- application upgrades and rollback decisions
- metrics, logs, alerting, and capacity planning
- outbound SMTP for invitations and account recovery
For a trial instance, one cluster and the bundled data services are enough. For important data, use managed or highly available backing services and a tested backup plan.
NORN_SECURITY_ENCRYPTION_KEY protects encrypted credentials stored by Norn. Generate it once, keep
an offline recovery copy, and restore the same value after a disaster. Losing it makes existing
encrypted data unreadable.
Next step
On a single host, start with Install with Docker Compose. On an existing Kubernetes platform, start with Install with Helm. Both guides include a small path using the bundled data services and a production path with externally managed ones.
Use the shared configuration reference with any deployment method, and the environment variable reference for the complete list of settings.