Self-Hosting

Minimal topology, LiveKit and Egress, environment variable reference, health probes, backup and upgrade.

Version v1.1.0 · Updated 2026-10-26 · revision 1

Self-hosting is what most distinguishes ni-meet from "just using someone else's cloud": the whole stack runs on your own machines or cluster. This page covers the three deployment shapes, environment variables, health checks, backup and upgrade, and the hard requirements for production.

Three deployment shapes

Shape	Command	Media plane	Recording	Use
Local development	`pnpm dev:api`	memory simulator	in-process simulated scheduling	business logic, tests and doc examples with zero dependencies
Local real SFU	`docker compose -f deploy/compose.yml up livekit redis api` (`NIMEET_SFU_ADAPTER=livekit`)	real LiveKit	LiveKit Egress	verify the real media path
Full stack	`docker compose -f deploy/compose.yml up`	LiveKit + TURN	dedicated `egress` container + `egress-worker`	same shape as production, including isolation and load testing

bash

docker compose -f deploy/compose.yml up -d --build
# API            https://api.your-domain.example
# console        https://console.your-domain.example
# docs           https://docs.your-domain.example
# meeting demo   https://meet.your-domain.example
# LiveKit ws     wss://sfu.your-domain.example
# MinIO          https://objects.your-domain.example    (optional `objectstore` profile; nimeet / nimeet-secret)
# egress worker  internal health/stats surface (not public)

On first start the API writes one-time demo credentials to data/demo-credentials.json. Before exposing it to the internet you must change CONSOLE_SEED_PASSWORD, NIMEET_WEBHOOK_SIM_SECRET and NIMEET_EGRESS_WORKER_TOKEN.

Environment variables (only the ones that affect behaviour)

Variable	Default	Meaning
`PORT` / `HOST`	8787 / 0.0.0.0	API listener
`NIMEET_SFU_ADAPTER`	`memory`	`memory` (simulated) or `livekit`
`LIVEKIT_HOST` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET`	—	required by the `livekit` adapter
`NIMEET_EGRESS_MODE`	`local`	with `remote`, jobs are dispatched to worker processes
`NIMEET_EGRESS_WORKERS`	—	comma-separated list of worker URLs
`NIMEET_EGRESS_WORKER_TOKEN`	—	bearer token for the worker control plane
`EGRESS_MAX_CONCURRENT` / `EGRESS_QUEUE_LIMIT`	8 / 200	control-plane concurrency gate and queue
`EGRESS_NODE_COUNT` / `EGRESS_NODE_CAPACITY`	2 / 4	shape of the local node pool
`NIMEET_SEED_DEMO`	true	whether to seed the demo project and analytics data (set false in production)
`RECORDING_STORAGE_VENDOR`	local	`s3` / `oss` / `cos` / `gcs` / `local`
`RTMP_PUSH_BASE` / `HLS_PLAY_BASE`	example domains	ingest/playback URL templates
`WORKER_CAPACITY` / `WORKER_QUEUE_LIMIT` / `WORKER_MAX_JOB_MS`	2 / 100 / 4h	egress worker limits
`NIMEET_RATE_LIMIT_PER_MINUTE` / `_BURST`	600 / 60	request rate limiting (see Quota)
`PUBLIC_BASE_URL`	—	externally reachable address; used to build absolute URLs for callback links and share links
`VITE_SFU_URL` (at front-end build/start time)	—	the media address the browser connects to (local `wss://sfu.your-domain.example`, production `wss://sfu.your-domain.example`). The token carries no SFU address field: the front end has only two sources — this build-time variable, or the `serverUrl` returned by the IM provider

Health and readiness

Endpoint	Purpose
`GET /healthz`	liveness probe (the process is still up)
`GET /readyz`	readiness probe (storage and SFU are usable)
`GET /metrics`	Prometheus metrics (operator use; never expose publicly)

In Kubernetes, wire healthz as the liveness probe and readyz as the readiness probe; keep scheduler and worker operator surfaces on the cluster network only.

Network and ingress

The public reverse proxy should expose only: /v1/*, /dev/v1/*, /console/*, the operator surface; the remaining the operator surface endpoints are operations tooling;
WebSocket upgrade must be allowed (/rtc proxied to LiveKit), otherwise clients reconnect forever;
TURN: the compose stack ships LiveKit with TURN built in; allow 3478/udp and 5349/tcp;
The LiveKit webhook only has to be configured once (deploy/livekit.yaml); the API derives the project from the room name <appId>:<channel> and verifies the signature.

Production hard requirements (do not go live without them)

Item	Requirement	Why
Storage	Use a Postgres implementation of the storage interface	the in-memory store assumes a single process and loses everything on restart
Recording isolation	Run `egress-worker` on separate machines/CPU pools from the SFU	recording is CPU-intensive and will starve the media plane
Capacity	Size `WORKER_CAPACITY` from your own measured egress stress-test numbers	guessing leads to queued jobs timing out
Secrets	Keep everything in a secret manager, never in the image	a leaked `appCertificate` means every token can be forged
Backup	Daily business-database backups + an object-storage lifecycle policy	recording files are customer assets

Upgrade steps

Upgrade the API first (one version of backward compatibility) and watch readyz and the error rate;
Then upgrade the egress worker: drain it (stop accepting new jobs) → wait for running jobs to finish → replace it;
Finally upgrade LiveKit / Egress (media-plane version changes affect streaming and recording encoding);
After upgrading, run node examples/run-all.mjs --all in the documentation examples directory as a regression check.

Backup and restore

Data	Location	Backup method
Projects/channels/jobs/usage	business database	database snapshots + PITR
Recording files	the object storage behind `RECORDING_STORAGE_VENDOR`	bucket versioning + cross-region replication
Driver logs	process stdout / logging system	retain ≥ 7 days, searchable by `X-Request-Id`

Common deployment problems

Symptom	Cause	Action
Clients stay in RECONNECTING	the reverse proxy does not allow WebSocket	enable Upgrade/Connection header pass-through
Recording jobs stay queued	`EGRESS_MAX_CONCURRENT` too small, or the worker is down	check the operator surface
Recording files return 404	storage vendor configuration and bucket permissions disagree	run the recording-storage self-check
Callbacks never arrive	webhook not configured / secret mismatch	configure it in the console, then check the delivery log
All data is lost after a restart	the in-memory store was used	switch to a Postgres implementation

Self-Hosting

Three deployment shapes#

Environment variables (only the ones that affect behaviour)#

Health and readiness#

Network and ingress#

Production hard requirements (do not go live without them)#

Upgrade steps#

Backup and restore#

Common deployment problems#