Networking

This page assumes the Docker setup. The same guide ships with it as docs/networking.md.

How traffic flowsCopy Anchor Link

• Only Caddy is exposed. It terminates TLS and routes requests.
• Postgres is on an internal network, with no route out and no published port.
• The server trusts only Caddy for a client's address, and Caddy sends exactly one: the real client, after its own BIGA_UPSTREAM_PROXIES. That address drives rate limits, and IPv6 clients are counted per /64.

The CLI and the viewer share one URL, BIGA_PUBLIC_URL: the CLI uploads to /api/sessions/... on it and prints BIGA_PUBLIC_URL/session/<id>.

Pick a modeCopy Anchor Link

./scripts/setup.sh asks for the mode and the name or address and writes the rest. What follows is what to set up around it.

IPv4 on the internetCopy Anchor Link

curl -4 -sI https://biga.example.com/ | head -1

sudo iptables -I DOCKER-USER -i eth0 ! -s 203.0.113.0/24 -j DROP

IPv6Copy Anchor Link

biga works over IPv6 end to end: Caddy, the server and the CLI all handle it, and Let's Encrypt validates over IPv6.

docker compose down
docker compose -f compose.yaml -f compose.ipv6.yaml up -d

curl -6 -sI https://biga.example.com/ | head -1
curl -4 -sI https://biga.example.com/ | head -1

An IPv6-only host serves only IPv6 clients. Offer both families if viewers might be on IPv4-only networks, which is still common on mobile and in offices.

An office or home networkCopy Anchor Link

./scripts/setup.sh --mode internal --domain biga.internal
docker compose up -d --build
./scripts/trust-ca.sh

BIGA_BIND_ADDRESS=192.168.1.20

Keep access keys on: anyone on the network can reach the server, and a key decides who may broadcast through it. If many people reach it through one NAT address, raise BIGA_READ_RATE_LIMIT or set it to 0.

No internet at allCopy Anchor Link

Build the images on a connected machine and carry them over:

docker compose build
docker save biga/server:local biga/web:local postgres:17-alpine caddy:2-alpine \
  | gzip > biga-images.tar.gz
# on the air-gapped host
gunzip -c biga-images.tar.gz | docker load
docker compose up -d

Nothing is pulled (BIGA_PULL_POLICY defaults to never). Use internal or http mode, since Let's Encrypt needs the internet.

A VPNCopy Anchor Link

Treat a Tailscale, WireGuard or ZeroTier network like an intranet. Bind to the host's VPN address so the server answers only over the VPN, and use internal mode with that address or the VPN's DNS name:

./scripts/setup.sh --mode internal --domain 100.101.102.103 --bind 100.101.102.103

With Tailscale, the MagicDNS name (studio.tail1234.ts.net) works as the domain too.

Behind a proxy you already runCopy Anchor Link

When nginx, Traefik or a load balancer already owns ports 80 and 443, run the stack in http mode on a loopback port and proxy to it:

./scripts/setup.sh --mode http --domain biga.example.com --bind 127.0.0.1 --http-port 8088

Set BIGA_PUBLIC_URL to the public https:// address, and set BIGA_UPSTREAM_PROXIES to the address Caddy sees your proxy from (through a loopback port that is the Docker bridge gateway; docker network inspect biga_edge shows it). The proxy must stream server-sent events and accept large uploads:

location / {
    proxy_pass http://127.0.0.1:8088;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;          # live updates
    proxy_read_timeout 1h;        # long-lived streams
    client_max_body_size 64m;     # snapshot uploads
}

Behind Cloudflare's proxy, keep public mode and set BIGA_UPSTREAM_PROXIES to Cloudflare's published IP ranges, or every visitor looks like Cloudflare.

PortsCopy Anchor Link

BIGA_HTTP_PORT and BIGA_HTTPS_PORT change the host side. Public mode needs the defaults, because Let's Encrypt validates on port 80.

TroubleshootingCopy Anchor Link