Deployment overview

This page introduces the supported ways to run and self-host Chorus, lists what each form needs, and helps you pick one. Once you have chosen, the Docker, local self-host, production, and operations guides take you the rest of the way.

Deployment forms

Chorus runs the same application in two forms, local and production. The difference is where its data lives and how many people use it.

Local single-machine

One process on one machine for a single user. Chorus bundles an embedded PostgreSQL database (PGlite), so there is nothing external to install: the command creates its own database, applies migrations, and serves the web app on port 8637. This is the fastest way to try Chorus and the right choice for individual, local use.

The Get started guide walks through this path end to end: install the global package, set an administrator account, and sign in. This page does not repeat those steps.

You can also run the local form in Docker as a standalone container: the same embedded database, with its data kept in a Docker volume. See Standalone (embedded database).

Self-hosted on one host

A long-running instance on your own Linux or macOS host, with a real PostgreSQL 17 database in Docker Compose instead of the embedded one. Chorus 0.22.2 and later set it up with bash install.sh --target local: the installer pulls or builds the app image, writes protected account configuration, and saves a wrapper for repeatable redeployments. The app is reachable from your LAN over HTTP, with optional self-signed LAN HTTPS or a Cloudflare Named Tunnel. It is a single-instance setup without Redis. See Self-host on a local machine.

Production

A shared installation for a team, backed by an external PostgreSQL database that you manage and back up (the repository’s Compose files default to PostgreSQL 17), and served by one or more application instances. Redis 7 is optional for a single instance and required when you run more than one, because instances propagate live updates (Server-Sent Events) to each other through Redis. Without Redis, Chorus falls back to in-memory eventing, which only works for a single instance.

Redis provides cross-instance SSE and shared authentication counters over separate connections. A nonempty REDIS_URL wins; otherwise REDIS_HOST uses TLS (rediss), with port 6379 and username default unless overridden. The username is used with REDIS_PASSWORD. For non-TLS Redis use redis:// explicitly. Only when both URL and host are absent are events and limits process-local. Redis failures use per-process insurance limits, not a shared budget or an all-login block; unexpected limiter errors can fail open. See shared authentication throttling for exact limits and recovery behavior.

You can run the production form as a container (see Deploy with Docker), from the global npm package against your own PostgreSQL and Redis, or on the bundled AWS CDK stack (see Deploy in production).

Choose account management separately

Managed local accounts are database-backed, not configured by DEFAULT_USER / DEFAULT_PASSWORD. Inject SUPER_ADMIN_EMAIL and SUPER_ADMIN_PASSWORD_HASH into the app, then create a local-account workspace and invite its first Workspace Admin from the admin panel. No identity provider or mail service is required. Local accounts and OIDC are mutually exclusive per workspace; existing workspaces cannot be converted. Persist NEXTAUTH_SECRET, share it across replicas, and use HTTPS with COOKIE_SECURE=true for shared access. See operations for account setup and disabling only legacy Default Auth.

Prerequisites

• Node.js 22 or later — Chorus targets the Node.js 22 runtime (the Docker image is built on node:22-alpine).
• Port 8637 — the application listens here. Publish or proxy this port to reach the UI and the MCP endpoint.
• Database — nothing to provision for the local form (embedded PGlite). For production, an external PostgreSQL database reachable over a connection string. The repository’s Compose files and the self-host stack default to PostgreSQL 17; an existing PostgreSQL 16 data volume must be migrated before you switch (see Self-host on a local machine).
• Cache — none required for a single instance. For multi-instance production, a Redis 7 endpoint for cross-instance event propagation.

How to choose

If you want to…	Use	Database	Cache
Try Chorus or work solo on one machine	Local single-machine	Embedded PGlite	None
Run a shared instance with the least moving parts	Local form in a standalone container	Embedded PGlite (in a volume)	None
Run a long-lived instance on your own host, reachable from your LAN	Self-hosted on one host (install.sh --target local)	PostgreSQL 17 (in Compose)	None
Run a shared, resilient, or multi-instance install	Production (Docker, npm, or AWS CDK)	External PostgreSQL (17 by default)	Redis 7 (required for 2+ instances)

Continue

• Deploy with Docker — the published chorusaidlc/chorus-app image: standalone and production Compose files, a docker run example, the full environment-variable reference, and startup behaviour.
• Self-host on a local machine — install.sh local setup, the redeploy wrapper, optional self-signed LAN HTTPS or Cloudflare Tunnel, and the PostgreSQL 16 to 17 migration.
• Deploy in production — running against your own PostgreSQL and Redis, multi-instance requirements, and the full AWS CDK walkthrough.
• Operate a self-hosted Chorus — first-login bootstrap, deployment-side authentication, automatic migrations, and backing up before you upgrade.