Turning on Huddles on your server

Applies to: the IT Admin User (server and firewall) and Workspace Admins (test and limits) · Time: about 10 minutes

Overview

Huddles are quick audio calls inside Messaging. On your own server they run on an audio server (LiveKit) that is included with Digital Workspace and runs next to it. Audio never leaves your network, there is no per-minute charge, and there is no organization limit. The installer turns huddles on.

This article covers the server. Who can start huddles, people per huddle, the monthly allowance, alerts and usage are set by Workspace Admins: see "Setting up Huddles (audio calls in Messaging)".

Before you begin

HTTPS is turned on (see "Turning on HTTPS"). Browsers only allow the microphone on a secure (https) address.
Remote colleagues need the VPN or outside access to reach these ports too (see "Access from outside your network").
You can sign in to the server and change the company firewall, or you know who can.

Steps for the IT Admin User

Open two ports in the firewall from your users' networks (offices, VPN) to the server: TCP 7881 and UDP 7882. Audio travels on these ports. Call setup uses the normal web address (/livekit on ports 80/443), so nothing else is needed.
Check that the audio server is on. In the installation folder run:
```
cd /opt/digital-workspace
sudo ./huddles.sh status
```
It should say Huddles: on · server IP … · ports TCP 7881, UDP 7882.
If it says Huddles: off (for example, a server installed before huddles existed, after its update), turn it on:
```
sudo ./huddles.sh on
```
If the server has several network addresses, give the one people's computers reach: sudo ./huddles.sh on 10.0.0.15.

Test a call (Workspace Admin)

Two people open Digital Workspace by its normal HTTPS address (not port 3000) and open the same conversation in Messages.
One clicks Huddle. The other hears the ring and clicks Join.
Both allow the microphone when the browser asks, and check that they hear each other.
Open Workspace settings › Huddles and set the limits for your organization.

Turning huddles off

For the whole server: sudo ./huddles.sh off. The keys stay in .env, and sudo ./huddles.sh on reuses them. To turn huddles off for one organization only, a Workspace Admin switches them off in Workspace settings › Huddles.

Sizing

The recommended server handles a few hundred people in huddles at the same time. Audio uses about 50 kbit/s per person.

Decision for your company

Prefer LiveKit Cloud instead of the bundled audio server? Set LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET in .env, add the webhook https://<your address>/api/huddles/webhook in the LiveKit project, and restart with sudo docker compose up -d app. This needs internet access from your offices, and LiveKit bills it per minute. Call audio then leaves your network (see "What data leaves your server").

Troubleshooting

Symptom	Resolution
Huddles need a secure (https) address for the microphone. Ask your admin to turn on HTTPS.	Turn on HTTPS, then open the app by its https:// address.
Huddles need the audio server on this installation (Workspace settings › Huddles), or "Huddles aren't set up on this server yet."	Run `sudo ./huddles.sh on` on the server.
Couldn't join the huddle, or the call connects but nobody hears anything	Ports TCP 7881 and UDP 7882 are blocked between the person's network and the server. Open them in the firewall (and on the VPN). If the server has several addresses, run `sudo ./huddles.sh on <IP>` with the address people reach.
Huddles don't connect when the app is opened at http://<server IP>:3000	Open Digital Workspace by its normal address. Port 3000 skips the web proxy that carries call setup.
Couldn't detect this server's IP address.	Give the address yourself: `sudo ./huddles.sh on <IP>`.

← 12. Setting up Single Sign-On (SSO) with Microsoft 365 14. Setting up Huddles (audio calls in Messaging) →

These articles are also in the Knowledge Base on your own server, after it is updated.

Need help? Write to info@digitalworkspace.app.