Repository navigation
Guide
Step by step, deploy your own server.
It is very simple really:
Any linux server (x86_64 or ARM) with one of:
| engine | packages |
|---|---|
| Docker |
docker, + compose plugin (docker compose) |
| Podman, rootless |
podman podman-compose
|
Commands below use docker compose; with podman swap in podman-compose, the
rest is identical. Optionally install sqlite3 and binutils for debugging.
Rootless (podman or rootless-docker) can't bind 80/443 by default.
What has to be reachable from the internet:
| port | proto | for |
|---|---|---|
| 22 | tcp | SSH (adjust if you moved sshd) |
| 80 | tcp | caddy: ACME http-01 + http->https redirect |
| 443 | tcp + udp | caddy: https, and HTTP/3 (QUIC) on udp |
| 40000-40002 | tcp + udp | voice/video, one port per mediasoup worker (CAESAR_WEBRTC_WORKERS, default 3) |
Keep your VPS provider's firewall and open exactly those. Many cheap providers cannot allow UDP 443 (HTTP/3) or a UDP range (voice): only then disable it, and read the note below first.
Then ufw on the host:
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp # SSH adjust if you moved sshd off 22
ufw allow 443 # caddy: https (tcp) + http/3 (udp)
ufw allow 80/tcp # caddy ACME http-01 + http->https redirect
ufw allow 40000:40002/tcp # voice, widen with CAESAR_WEBRTC_WORKERS
ufw allow 40000:40002/udp
ufw enable && ufw statusNote
Which firewall covers the published ports depends on the engine.
- Rootful
docker(the default install) publishes ports through its owniptableschain, evaluated beforeufw.ufwonly covers what runs on the host itself (sshd, accidental listeners). Without a provider firewall, theports:blocks ofdocker-compose.yamlalone decide what is public: 80, 443 and the voice range. Any port you add there is public, whateverufw statussays. - Rootless
podman(and rootless docker) publish through a userspace forwarder (regular host sockets), soufwapplies: without the two voice rules above, calls do not connect.
Do not expose CAESAR_PORT (4991): only caddy reaches it, inside the compose network.
To test, curl -v that port from another machine: it should hang at Trying... or be refused. That is because 4991 is in no ports: block, not because of ufw.
You can also do the same with any firewall equivalent: firewalld ...
git clone <url> && cd caesar.env holds deploy settings, config.ini the rate limits; both ship with
defaults, see Configuration.
It runs the published image from ghcr.io/h8d13/caesar (amd64 + arm64).
Pick the tag with CAESAR_IMAGE_TAG in .env:
| tag | published on | |
|---|---|---|
edge |
every push to master | default until the first release |
sha-<short> |
every build | pin an exact commit |
Each build carries a GitHub provenance attestation (commit + workflow run). To verify the image was built from master by this repo's image workflow:
gh attestation verify oci://ghcr.io/h8d13/caesar:edge \
--repo h8d13/caesar \
--signer-workflow h8d13/caesar/.github/workflows/image.yml \
--source-ref refs/heads/master
--owner h8d13alone would accept any workflow in any repo of that account. The same command works for asha-<short>tag and prints the source commit. Needs the gh CLI, on any machine.
Data lives in named volumes (caesar_caesar_data, caddy certs in
caesar_caddy_data), owned by the container's user.
Set CAESAR_SITE in .env (the rest of the file is optional knobs with
their defaults):
CAESAR_SITE=sub.example.comCompose reads
.envfrom the directory ofdocker-compose.yamlautomatically, and passes every variable in it to the server.
It can be domains, IPs directly, Tailscale nodes, whatever. One host, no port:
the port belongs to Caddy, which publishes 80/443 (host:port only works for
prod-dev on :8443).
To set these easily you can:
echo "CAESAR_SITE=localhost" >> .env
echo "CAESAR_IMAGE_TAG=edge" >> .env
docker compose -f compose.prod-dev.yaml up --buildEach mediasoup worker gets one port. Defaults fit a cheap 4 vCPUs server:
3 workers (CAESAR_WEBRTC_WORKERS in .env) on the published range in
docker-compose.yaml:
ports:
- "40000-40002:40000-40002/tcp"
- "40000-40002:40000-40002/udp"Note
One vCPU is left free, you could also try 4.
- More workers: raise
CAESAR_WEBRTC_WORKERSand widen that range to match (your hardware becomes the limit). - Fewer than 4 vCPUs: lower
CAESAR_WEBRTC_WORKERS(vCPUs minus one, at least 1).
The caesar container is capped so it cannot starve the host (sshd, caddy):
2 GiB of memory (CAESAR_MEM_LIMIT), 512 processes/threads, logs rotated at
5 x 10 MB. On a 1-2 GB VPS set CAESAR_MEM_LIMIT to RAM minus 512m. CPU is
uncapped by default (CAESAR_CPUS=0). See
Configuration.
See also the server-helpers script: one-time host tweaks, like bigger network buffers for lots of screen shares/webcams at once, and capped log sizes.
Caddy runs caddy reverse-proxy straight from
docker-compose.yaml:
one site, CAESAR_SITE to caesar:CAESAR_PORT, automatic HTTPS, no config file.
Anything beyond that: Custom Caddyfile.
For further config refer to Caddy documentation: https://caddyserver.com/docs/
If you have a domain + a VPS, you can point to it by adding a A record:
www IN A XX.XX.XX.XXX
@ IN A XX.XX.XX.XXX
CAESAR_SITE is one canonical host, not a list: it is also the WebAuthn RP ID
(hardware 2FA / passkeys are bound to it), so the server refuses to boot on a
value containing a space or a comma. Serve the www record with its own
redirect block in a Custom Caddyfile:
example.com {
reverse_proxy caesar:4991
}
www.example.com {
redir https://example.com{uri} 301
}Both records then work, certs are issued for both, and the RP ID stays
example.com. Skip the www A record if you don't want the alias.
Full env var reference: Configuration.
Needed for aliases (www), extra instances or
on-demand TLS.
Two files next to docker-compose.yaml (gitignored if you run from a clone):
Can also use tls internal for quick tests.
caddy/Caddyfile, e.g. the www example above. The primary site must match
CAESAR_SITE and proxy to caesar:<CAESAR_PORT>.
docker-compose.override.yaml, auto-loaded by docker compose and
podman-compose:
services:
caddy:
command: caddy run --config /etc/caddy/Caddyfile --adapter caddyfile
volumes:
- ./caddy/Caddyfile:/etc/caddy/Caddyfile:roVolumes merge with the base file, certs in caddy_data stay. Apply with
docker compose up -d caddy. Later edits reload live:
docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile.
# prod build
docker compose up -dThis runs Caesar behind Caddy on 443. Access at: https://yourdomain.ext or with www depending on how you set it up.
Then docker logs caesar on first run will give you the owner token, a unique UUID.
Login through the main entry page: First user is always allowed without an invite.
Go to DevTools > Console: useToken("UUID") this sets you as the server owner.
Do both right after the first start: until you sign up, anyone who finds the page can take the invite-free first account (not Owner, that needs the token from your log). The token only works while the server has no Owner, so an old log line is harmless once you have claimed it.
docker compose pull && docker compose up -d --force-recreateup -d alone never re-pulls a tag it already has, and edge / latest move
with every publish. The version shown in the app is the commit the image was built from.
Data volumes are kept. --force-recreate because podman-compose leaves a
running container on its old image when only the pulled tag changed.
Optionally remove old images
docker image prune
Additional dep: docker-buildx
Test the checkout first with prod-dev.
Made with 🖤 CHANGELOG