Self-hosting
Run the biga server on your own infrastructure.
biga has two server-side parts:
- The API server, biga-sh/server: one Go binary on Postgres. It stores sessions and streams every save to viewers. Redis or Valkey is optional, for running several instances.
- The site and viewer, biga-sh/website: a Next.js app that renders sessions. It holds no data.
Both need to answer on one origin, with /api/sessions/* going to the API
server, so the CLI and the viewer share one URL.
Choose a setup
| Setup | When |
|---|---|
| Docker | The easy path. Everything, with TLS, on one machine. |
| The server binary or image, behind your own proxy | You already run a reverse proxy and Postgres. |
| The site on Vercel, the server elsewhere | You want the site on a CDN. Point the site at the server with BIGA_SERVER_URL (proxied) or NEXT_PUBLIC_BIGA_API_URL (direct, with BIGA_CORS_ORIGINS on the server). |
Run the server on its own
docker run -p 8080:8080 \
-e DATABASE_URL='postgres://biga:…@db:5432/biga' \
-e BIGA_PUBLIC_URL=https://biga.example.com \
-e BIGA_TRUSTED_PROXIES=private \
ghcr.io/biga-sh/server:1Or build it with Go 1.26+: go build ./cmd/biga-server. It applies its
database migrations on start, answers GET /healthz (process up) and
GET /readyz (Postgres and Redis reachable), and shuts down gracefully on
SIGTERM.
Then route /api/sessions/* to it and everything else to the site. Your proxy
must not buffer server-sent events; see the nginx example under
Networking.
Configuration
The settings you are most likely to need:
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | required | Postgres connection string (13 or newer). |
BIGA_PUBLIC_URL | unset | The origin viewers open. Returned to the CLI as the share link. |
BIGA_ACCESS_KEYS | unset | When set, only holders of one of these keys can broadcast. Generate keys with biga-server gen-key. |
BIGA_TRUSTED_PROXIES | unset | Proxies whose X-Forwarded-For is believed: IPs, CIDRs, loopback or private. Set it behind a proxy, or every client looks like the proxy. |
BIGA_LISTEN | :8080 | Addresses to listen on, IPv4 or IPv6, or unix:/path. |
BIGA_CORS_ORIGINS | unset | Browser origins allowed to read the API cross-origin. |
BIGA_RETENTION_DAYS | 30 | Days an ended session is kept. The server sweeps hourly. |
REDIS_URL | unset | Redis or Valkey, to share live events and rate limits across instances. |
Every option, including body limits, rate limits, stream caps and TLS, is in
the server README. Secrets
can be read from files by adding _FILE to the name.
The site
| Variable | Description |
|---|---|
BIGA_SERVER_URL | Where the site proxies /api/sessions/*. Defaults to http://localhost:8080 in development; unset in production when a reverse proxy already routes it. |
NEXT_PUBLIC_BIGA_API_URL | Have browsers call the server directly instead. Baked in at build time. |
NEXT_PUBLIC_SITE_URL | The public origin, for absolute metadata URLs. |
BIGA_DEMO_SESSION_ID | The session the landing page embeds. Give the server the same value so retention keeps it. |
Point the CLI at it
BIGA_API_URL=https://biga.example.com biga startAdd BIGA_ACCESS_KEY=<key> if the server requires one.