Run the site, the viewer, the API server and PostgreSQL behind Caddy with one Compose file.
Website · Documentation · Networking guide · Issues
It works on a public server, on an office network or on one laptop. Caddy handles TLS and routing, PostgreSQL sits on a network with no route out, and only people holding an access key can broadcast.
You need Docker Engine 24+ with Compose v2 (Linux for anything real; Docker Desktop is fine for trying it) and about 2 GB of RAM for the first build.
git clone https://github.com/biga-sh/docker.git biga && cd biga
./scripts/setup.shsetup.sh asks how people will reach the server, then writes .env with a generated database password and access key. It refuses to overwrite an existing .env unless you pass --force.
docker compose up -d --build
docker compose psThe first build takes a few minutes. Wait until every service reports healthy.
setup.sh prints the exact command, for example:
BIGA_API_URL=https://biga.example.com BIGA_ACCESS_KEY=bgk_… biga startViewers only need the link the CLI prints.
| Mode | For | Setup |
|---|---|---|
public |
A domain on the internet. Caddy gets and renews a Let's Encrypt certificate; ports 80 and 443 must be reachable. | ./scripts/setup.sh --mode public --domain biga.example.com |
internal |
A private network, by name or IP. Caddy runs its own certificate authority; run ./scripts/trust-ca.sh once per device. |
./scripts/setup.sh --mode internal --domain biga.internal |
http |
A network you fully trust, or TLS added by something in front. Keys travel in clear text. | ./scripts/setup.sh --mode http --domain 192.168.1.20 |
IPv4, IPv6, intranets, VPNs and existing proxies are covered in the networking guide.
| Service | Role |
|---|---|
caddy |
TLS, HTTP/3 and routing: /api/sessions/* to the server, everything else to the site. The only published ports. |
server |
The API server, built from biga-sh/server |
web |
The site and viewer, built from biga-sh/website |
postgres |
Every session, in the pgdata volume |
Every container runs with no-new-privileges, Linux capabilities dropped, a read-only root filesystem and rotated logs. Secrets stay in .env, mode 600, ignored by git.
docker compose logs -f server # follow a service
docker compose pull --ignore-buildable && docker compose up -d --build # update
./scripts/backup.sh # dump the database to backups/
./scripts/restore.sh backups/biga-….dump # restore a dump
docker compose run --rm --no-deps server gen-key # another access key
docker compose down # stop; data stays in volumesTo revoke an access key, remove it from BIGA_ACCESS_KEYS in .env and run docker compose up -d. Ended sessions are deleted after BIGA_RETENTION_DAYS (default 30) by the server's own hourly sweep.
| Optional file | Adds |
|---|---|
compose.ipv6.yaml |
IPv6 inside Docker, so IPv6 visitors keep their addresses |
compose.scale.yaml |
Several API server instances sharing live events through Valkey |
Stop the stack before changing which files it uses, then start it with docker compose -f compose.yaml -f compose.ipv6.yaml up -d. COMPOSE_FILE in .env makes the choice stick.
To build from local checkouts instead of GitHub, set BIGA_SERVER_SOURCE=../server and BIGA_WEB_SOURCE=../website in .env and run docker compose up -d --build.
CI runs shellcheck on the scripts, validates every combination of Compose files and every Caddyfile mode, then starts the stack and broadcasts through it.
| Repository | What it is |
|---|---|
| cli | The biga command. Watches a folder and streams every save. |
| server | The Go API. Stores sessions and streams updates to viewers. |
| website | The site, the live viewer and the documentation. |
| docker | Self-hosting: the whole stack with Docker Compose. |
Bug reports, focused fixes and pull requests are welcome. Read the contributing guide before you start, and report vulnerabilities privately as described in the security policy, not in a public issue.
biga is MIT licensed.
biga · Made for people who teach, pair and build in public.