Docker
Run the whole of biga on your own machine or network with one Compose file.
biga-sh/docker runs the site and viewer, the API server, Postgres and Caddy together. It works on a public server, on an office network, or on one laptop.
Start
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.
Get the files and configure
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.
Start the stack
docker compose up -d --build
docker compose psThe first build takes a few minutes. Wait until every service reports
healthy.
Broadcast to it
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.
Modes
A domain on the internet. Caddy gets a certificate from Let's Encrypt and
renews it. The domain's A and/or AAAA records must point at the host, and
ports 80 and 443 must be reachable.
./scripts/setup.sh --mode public --domain biga.example.comIPv4, IPv6, intranets, VPNs and existing proxies are covered in Networking.
What runs
| Service | Role |
|---|---|
caddy | TLS, HTTP/3 and routing: /api/sessions/* to the server, everything else to the site. The only published ports. |
server | The Go API server: sessions, uploads, live streams. Built from biga-sh/server. |
web | The site and the viewer. Built from biga-sh/website. |
postgres | Every session, in the pgdata volume, on a network with no route out. |
Secure by default
- Only a session's creator can write to it. The CLI gets an owner token when it creates a session; a link lets people watch, nothing more.
- Only key holders can broadcast.
setup.shgenerates an access key; pass--no-access-keyfor an open server. - Only Caddy is reachable. Postgres has no published port and no route out.
- Every container runs with
no-new-privileges, Linux capabilities dropped, a read-only root filesystem and rotated logs. - Rate limits see real client addresses: the server trusts only Caddy,
and Caddy trusts only the proxies in
BIGA_UPSTREAM_PROXIES. - Secrets stay in
.env, mode600, ignored by git.
Day to day
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. Broadcasts using it stop at their next request.
Ended sessions are deleted after BIGA_RETENTION_DAYS (30) by the server's own
hourly sweep. Nothing needs scheduling.
Optional files
| File | Adds |
|---|---|
compose.ipv6.yaml | IPv6 inside Docker, so IPv6 visitors keep their addresses. Use it whenever the host has IPv6. |
compose.scale.yaml | Several API server instances sharing live events through Valkey. |
docker compose down
docker compose -f compose.yaml -f compose.ipv6.yaml up -dStop the stack before changing which files it uses: the networks change, and
reattached containers lose their service names. COMPOSE_FILE in .env makes
the choice stick.
Building your own changes
Set BIGA_SERVER_SOURCE=../server and BIGA_WEB_SOURCE=../website in .env
to build from local checkouts instead of GitHub, then run
docker compose up -d --build.