Skip to content

Commit 93fb299

Browse files
fkwpfkwp
committed
add self-hosting section
1 parent f79d7cf commit 93fb299

File tree

3 files changed

+173
-3
lines changed

3 files changed

+173
-3
lines changed

‎README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -83,9 +83,12 @@ and voice calls within Matrix rooms.
8383
> Embedded packaging is recommended for Element Call in widget mode!
8484
8585

86-
MSC4222 allow clients to opt-in to a change of the sync v2 API that allows them
87-
to correctly track the state of the room. This is required by Element Call to
88-
track room state reliably.
86+
## 🛠️ Self-Hosting
87+
88+
For operating and deploying Element Call on your own server, refer to the
89+
[**Self-Hosting Guide**](./docs/self-hosting.md).
90+
91+
8992

9093
Element Call requires a Livekit SFU alongside a [Livekit JWT
9194
service](https://github.com/element-hq/lk-jwt-service) to work. The url to the

‎docs/MSC4195_setup.drawio.png‎

49 KB
Loading

‎docs/self-hosting.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Self-Hosting Element Call
2+
3+
## Prerequisites
4+
5+
> [!IMPORTANT]
6+
> This section covers the requirements for deploying a **Matrix site**
7+
> compatible with MatrixRTC, the foundation of Element Call. These requirements
8+
> apply to both Standalone as well as Widget mode operation of Element Call.
9+
10+
### A Matrix Homeserver
11+
12+
The following [MSCs](https://github.com/matrix-org/matrix-spec-proposals) are
13+
required for Element Call to work properly:
14+
15+
-
16+
**[MSC3266](https://github.com/deepbluev7/matrix-doc/blob/room-summaries/proposals/3266-room-summary.md):
17+
Room Summary API**: In Standalone mode Element Call is able to join rooms
18+
over federation using knocking. In this context MSC3266 is required as it
19+
allows to request a room summary of rooms you are not joined. The summary
20+
contains the room join rules. We need that information to decide if the user
21+
gets prompted with the option to knock ("Request to join call"), a "cannot
22+
join error" or "the join view".
23+
24+
-
25+
**[MSC4140](https://github.com/matrix-org/matrix-spec-proposals/blob/toger5/expiring-events-keep-alive/proposals/4140-delayed-events-futures.md)
26+
Delayed Events**: Delayed events are required for proper call participation
27+
signalling. If disabled it is very likely that you end up with stuck calls in
28+
Matrix rooms.
29+
30+
-
31+
**[MSC4222](https://github.com/matrix-org/matrix-spec-proposals/blob/erikj/sync_v2_state_after/proposals/4222-sync-v2-state-after.md)
32+
Adding `state_after` to sync v2**: Allow clients to opt-in to a change of the
33+
sync v2 API that allows them to correctly track the state of the room. This is
34+
required by Element Call to track room state reliably.
35+
36+
37+
If you're using [Synapse](https://github.com/element-hq/synapse/) as your homeserver, you'll need
38+
to additionally add the following config items to `homeserver.yaml` to comply with Element Call:
39+
40+
```yaml
41+
experimental_features:
42+
# MSC3266: Room summary API. Used for knocking over federation
43+
msc3266_enabled: true
44+
# MSC4222 needed for syncv2 state_after. This allow clients to
45+
# correctly track the state of the room.
46+
msc4222_enabled: true
47+
48+
# The maximum allowed duration by which sent events can be delayed, as
49+
# per MSC4140.
50+
max_event_delay_duration: 24h
51+
52+
rc_message:
53+
# This needs to match at least the heart-beat frequency plus a bit of headroom
54+
# Currently the heart-beat is every 5 seconds which translates into a rate of 0.2s
55+
per_second: 0.5
56+
burst_count: 30
57+
```
58+
59+
### MatrixRTC Backend
60+
61+
In order to **guarantee smooth operation** of Element Call MatrixRTC backend is
62+
required for each site deployment.
63+
64+
![MSC4195 compatible setup](MSC4195_setup.drawio.png)
65+
66+
As depicted above, Element Call requires a
67+
[Livekit SFU](https://github.com/livekit/livekit) alongside a
68+
[Matrix Livekit JWT auth service](https://github.com/element-hq/lk-jwt-service)
69+
to implement
70+
[MSC4195: MatrixRTC using LiveKit backend](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md).
71+
72+
> [!IMPORTANT]
73+
> As defined in
74+
> [MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)
75+
> MatrixRTC backend must be announced to the client via your **homeserver's
76+
> `.well-known/matrix/client`**. The configuration is a list of Foci configs:
77+
```json
78+
"org.matrix.msc4143.rtc_foci": [
79+
{
80+
"type": "livekit",
81+
"livekit_service_url": "https://someurl.com"
82+
},
83+
{
84+
"type": "livekit",
85+
"livekit_service_url": "https://livekit2.com"
86+
},
87+
{
88+
"type": "another_foci",
89+
"props_for_another_foci": "val"
90+
},
91+
]
92+
```
93+
94+
95+
## Building Element Call
96+
97+
> [!NOTE]
98+
> This step is only required if you want to deploy Element Call in Standalone
99+
> mode.
100+
101+
Until prebuilt tarballs are available, you'll need to build Element Call from
102+
source. First, clone and install the package:
103+
104+
```sh
105+
git clone https://github.com/element-hq/element-call.git
106+
cd element-call
107+
yarn
108+
yarn build
109+
```
110+
111+
If all went well, you can now find the build output under `dist` as a series of
112+
static files. These can be hosted using any web server that can be configured
113+
with custom routes (see below).
114+
115+
You also need to add a configuration file which goes in `public/config.json` -
116+
you can use the sample as a starting point:
117+
118+
```sh
119+
cp config/config.sample.json public/config.json
120+
# edit public/config.json
121+
```
122+
123+
The sample needs editing to contain the homeserver that you are using.
124+
125+
Because Element Call uses client-side routing, your server must be able to route
126+
any requests to non-existing paths back to `/index.html`. For example, in Nginx
127+
you can achieve this with the `try_files` directive:
128+
129+
```jsonc
130+
server {
131+
...
132+
location / {
133+
...
134+
try_files $uri /$uri /index.html;
135+
}
136+
}
137+
```
138+
139+
140+
## Configuration
141+
142+
There are currently two different config files. `.env` holds variables that are
143+
used at build time, while `public/config.json` holds variables that are used at
144+
runtime. Documentation and default values for `public/config.json` can be found
145+
in [ConfigOptions.ts](src/config/ConfigOptions.ts).
146+
147+
> [!CAUTION]
148+
> Please note configuring MatrixRTC backend via `config.json` of
149+
> Element Call is only available for developing and debug purposes. Relying on
150+
> it might break Element Call going forward!
151+
152+
153+
## A Note on Standalone Mode of Element Call
154+
155+
Element Call in Standalone mode requires a homeserver with registration enabled
156+
without any 3pid or token requirements, if you want it to be used by
157+
unregistered users. Furthermore, it is not recommended to use it with an
158+
existing homeserver where user accounts have joined normal rooms, as it may not
159+
be able to handle those yet and it may behave unreliably.
160+
161+
Therefore, to use a self-hosted homeserver, this is recommended to be a new
162+
server where any user account created has not joined any normal rooms anywhere
163+
in the Matrix federated network. The homeserver used can be setup to disable
164+
federation, so as to prevent spam registrations (if you keep registrations open)
165+
and to ensure Element Call continues to work in case any user decides to log in
166+
to their Element Call account using the standard Element app and joins normal
167+
rooms that Element Call cannot handle.

0 commit comments

Comments
 (0)