Self-hosting guide

Requirements

Check the SHA-256 checksums on the download page.

Install on Windows

1. Run BROARchat-Server-Setup-11.4.exe as an administrator. The installer isn't code-signed yet, so if SmartScreen warns you, choose More info → Run anyway.
2. The installer puts everything under C:\Program Files\BROARchat Server: PostgreSQL, the identity service, the LiveKit voice server, nginx and the gateway. Then the configuration wizard opens.
3. Pick a scope:
   • Local network: the server uses this PC's LAN IP over plain HTTP. This is the fastest way to start, and you don't need a domain.
   • Internet: enter your domain. HTTPS is provided by a reverse proxy you put in front (see HTTPS / TLS).
4. Create the admin account, optionally paste a license key (leave it blank for the free Community mode), and click Install. The wizard registers the services, runs the database migrations and opens the Windows Firewall for the web and voice ports only.
5. Open the address the wizard shows (for example http://192.168.1.50) in a browser and sign in.

The Start Menu has BROARchat Server Console (status and logs), Configure BROARchat Server (re-run the wizard) and two uninstall options. The services are BROARchat-DB, BROARchat-Core, BROARchat-API, BROARchat-Voice and BROARchat-Web, and they start automatically at boot.

Install on Linux (Docker)

curl -fsSL https://get.docker.com | sh        # if Docker isn't installed yet
tar xzf broarchat-docker-11.3.tar.gz
cd broarchat-docker-11.3
sudo ./setup.sh

setup.sh checks your prerequisites, then asks for a hostname, protocol, ports and (optionally) SMTP, a Giphy key and your license key. It generates every secret with openssl rand, writes .env and server.cfg, renders the configs, runs docker compose up -d --build and, if you chose Let's Encrypt, requests the certificate. At the end it prints your URL and the exact firewall commands.

All containers use host networking, which LiveKit's UDP media needs. As a result Postgres (5432), the Matrix API (8008) and the gateway (4000) listen on every interface. Don't forward those ports, and keep them blocked with your host firewall:

ufw allow 80/tcp && ufw allow 443/tcp
ufw allow 7880/tcp && ufw allow 7881/tcp
ufw allow 7882/udp && ufw allow 50000:50050/udp
ufw default deny incoming && ufw enable

Ports

These are the defaults. You can change any of them in the wizard or in .env.

If voice connects but nobody can hear each other, the UDP ports almost always aren't reaching the server. For internet-facing installs, also turn on "Advertise a public IP" (USE_EXTERNAL_IP / PUBLIC_IP) so WebRTC hands out your public address.

DNS

For a LAN-only server you don't need DNS at all; members use the IP address. To reach the server from the internet:

1. Create an A record (and an AAAA record if you have IPv6), for example chat.example.com → your public IP. If your home IP changes, use a dynamic-DNS service.
2. Forward the ports above on your router to the server's LAN IP.
3. If you put the site behind a CDN or proxy such as Cloudflare, proxy only the web ports. Voice (7880–7882 and the UDP range) must go straight to your server, so create a separate DNS-only record for it, or leave the voice hostname unproxied.

HTTPS / TLS

Browsers only allow microphone and camera access on https:// pages, or on localhost. On a LAN over plain HTTP, some browsers may block voice until you add the site as trusted. For anything beyond testing, use HTTPS.

• Linux: pick letsencrypt in setup.sh and the certificate is issued automatically. Port 80 must be reachable and DNS must already point at the server. If that fails, setup falls back to a self-signed certificate and prints a retry command. You can also choose selfsigned or none.
• Windows: choose HTTPS via reverse proxy in the wizard and terminate TLS in front of the server, using Caddy, nginx, a Cloudflare Tunnel or your router's reverse proxy. Point the proxy at the server's HTTP port, and allow WebSocket upgrades (the app uses /socket and /livekit-signal/). The UDP voice ports still go straight to the server, not through the proxy.

Connecting members

Share your server's address. Members can open it in any modern browser, install it to their phone's home screen, or use the Windows desktop app, which also finds servers on the local network automatically. To bring people into a Space, send them an invite link from that Space's menu.

License activation

Without a key the server runs in Community mode: free, up to 5 users and 5 Spaces, with chat, voice, video and screen share. A paid key unlocks your tier's features and limits. It activates the first time the server boots with it, by checking in with license.broarchat.com. There are three ways to add or change a key:

1. During install: paste it into the Windows wizard or setup.sh. Setup verifies it immediately without using up an activation.
2. In the app: go to Settings → License (owner/admin only). This works at any time, with no files to edit.
3. In the config: set LICENSE_KEY= in .env (Linux) and restart the gateway, or re-run the Windows configuration wizard.

A blank, invalid or expired key never bricks the server. It just falls back to Community mode, and your data stays put.

Moved, renamed or rebuilt your server?

Each license covers a fixed number of servers (one for Gamer and Pro, three for Business). BROARchat identifies a server by its machine identity, so a renamed, reinstalled or replaced machine counts as a new server. If the key says all activation slots are in use:

1. Sign in at broarchat.com/account with the email you bought with.
2. Under your license, find the old server and click Release.
3. Enter the key again on the new server (in Settings → License, or by restarting it).

Can't release a server, or lost access to your account? Email [email protected] with your license key.

Upgrading

Back up first (see below). Upgrades can run database migrations.

• Windows: run the new BROARchat-Server-Setup-<version>.exe. It detects the existing install, offers Upgrade, and keeps your database, media and settings. Finish the configuration wizard that opens afterwards: it's the step that restarts the services. If you close it early, run Configure BROARchat Server from the Start Menu.
• Linux: unpack the new release over your folder (or git pull), then run sudo ./setup.sh and choose reuse existing .env. You can also run docker compose up -d --build directly. Data lives in Docker volumes and in matrix_data/, certs/ and certbot/, and an upgrade never touches them.

Release notes for every version are in the changelog.

Backups

Linux

./backup.sh                    # timestamped backup into ./backups/
./backup.sh --retention 14     # keep the newest 14
./backup.sh --no-config        # leave .env / secrets out of the backup

./restore.sh 20260714-030000 --confirm   # DESTRUCTIVE: overwrites live data

# daily at 03:00, keep a week (crontab -e)
0 3 * * * /path/to/broarchat/backup.sh --retention 7 >> /var/log/broarchat-backup.log 2>&1

Each backup contains a pg_dump of every database, media.tar.gz and (unless you pass --no-config) a 0600 copy of your config. The config holds secrets, so keep backups off shared storage. Backups are safe to take while the server is running.

Windows

Everything lives in the install folder. Stop the BROARchat services from the Server Console (or with Stop-Service BROARchat-* in an admin PowerShell), then copy:

• C:\Program Files\BROARchat Server\data\: database (postgres), identity service (dendrite) and uploads (media)
• C:\Program Files\BROARchat Server\server.cfg and config\: your settings and secrets

Then start the services again. To restore, reinstall the same version, stop the services, put the folders back and start them.

Troubleshooting

• "Some services could not start" on Windows: port 80 is usually taken by IIS or another web server. Stop it, or pick another HTTP port in the wizard.
• Can't hear anyone / voice stuck connecting: forward the UDP ports, check the host firewall, and turn on "Advertise a public IP" for internet installs.
• Mic or camera blocked: the page isn't on HTTPS. See HTTPS / TLS.
• Desktop app doesn't find the server: LAN discovery uses UDP 47800 on the local network only. Type the address manually from other networks.
• License says all slots are used: release the old server in your account.

Still stuck? Email [email protected], or check the FAQ.