From 2961cfa52c093f55cfb895bd90b52c6ac408b0fa Mon Sep 17 00:00:00 2001 From: fkwp Date: Wed, 6 Nov 2024 20:20:29 +0100 Subject: [PATCH] update README.md --- README.md | 102 ++++++++++++++++++++++--------- backend/tls_localhost_nginx.conf | 2 +- 2 files changed, 75 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index a395729f..ee4d93a4 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,24 @@ [![Chat](https://img.shields.io/matrix/webrtc:matrix.org)](https://matrix.to/#/#webrtc:matrix.org) [![Localazy](https://img.shields.io/endpoint?url=https%3A%2F%2Fconnect.localazy.com%2Fstatus%2Felement-call%2Fdata%3Fcontent%3Dall%26title%3Dlocalazy%26logo%3Dtrue)](https://localazy.com/p/element-call) -Group calls with WebRTC that leverage [Matrix](https://matrix.org) and an open-source WebRTC toolkit from [LiveKit](https://livekit.io/). +Group calls with WebRTC that leverage [Matrix](https://matrix.org) and an +open-source WebRTC toolkit from [LiveKit](https://livekit.io/). -For prior version of the Element Call that relied solely on full-mesh logic, check [`full-mesh`](https://github.com/element-hq/element-call/tree/full-mesh) branch. +For prior version of the Element Call that relied solely on full-mesh logic, +check [`full-mesh`](https://github.com/element-hq/element-call/tree/full-mesh) +branch. ![A demo of Element Call with six people](demo.jpg) -To try it out, visit our hosted version at [call.element.io](https://call.element.io). You can also find the latest development version continuously deployed to [call.element.dev](https://call.element.dev/). +To try it out, visit our hosted version at +[call.element.io](https://call.element.io). You can also find the latest +development version continuously deployed to +[call.element.dev](https://call.element.dev/). ## Host it yourself -Until prebuilt tarballs are available, you'll need to build Element Call from source. First, clone and install the package: +Until prebuilt tarballs are available, you'll need to build Element Call from +source. First, clone and install the package: ``` git clone https://github.com/element-hq/element-call.git @@ -22,17 +29,23 @@ yarn yarn build ``` -If all went well, you can now find the build output under `dist` as a series of static files. These can be hosted using any web server that can be configured with custom routes (see below). +If all went well, you can now find the build output under `dist` as a series of +static files. These can be hosted using any web server that can be configured +with custom routes (see below). -You may also wish to add a configuration file (Element Call uses the domain it's hosted on as a Homeserver URL by default, -but you can change this in the config file). This goes in `public/config.json` - you can use the sample as a starting point: +You may also wish to add a configuration file (Element Call uses the domain it's +hosted on as a Homeserver URL by default, but you can change this in the config +file). This goes in `public/config.json` - you can use the sample as a starting +point: ``` -cp config/config.devenv.json public/config.json +cp config/config.sample.json public/config.json # edit public/config.json ``` -Because Element Call uses client-side routing, your server must be able to route any requests to non-existing paths back to `/index.html`. For example, in Nginx you can achieve this with the `try_files` directive: +Because Element Call uses client-side routing, your server must be able to route +any requests to non-existing paths back to `/index.html`. For example, in Nginx +you can achieve this with the `try_files` directive: ``` server { @@ -44,17 +57,36 @@ server { } ``` -By default, the app expects you to have a Matrix homeserver (such as [Synapse](https://element-hq.github.io/synapse/latest/setup/installation.html)) installed locally and running on port 8008. If you wish to use a homeserver on a different URL or one that is hosted on a different server, you can add a config file as above, and include the homeserver URL that you'd like to use. +By default, the app expects you to have a Matrix homeserver (such as +[Synapse](https://element-hq.github.io/synapse/latest/setup/installation.html)) +installed locally and running on port 8008. If you wish to use a homeserver on a +different URL or one that is hosted on a different server, you can add a config +file as above, and include the homeserver URL that you'd like to use. -Element Call requires a homeserver with registration enabled without any 3pid or token requirements, if you want it to be used by unregistered users. Furthermore, it is not recommended to use it with an existing homeserver where user accounts have joined normal rooms, as it may not be able to handle those yet and it may behave unreliably. +Element Call requires a homeserver with registration enabled without any 3pid or +token requirements, if you want it to be used by unregistered users. +Furthermore, it is not recommended to use it with an existing homeserver where +user accounts have joined normal rooms, as it may not be able to handle those +yet and it may behave unreliably. -Therefore, to use a self-hosted homeserver, this is recommended to be a new server where any user account created has not joined any normal rooms anywhere in the Matrix federated network. The homeserver used can be setup to disable federation, so as to prevent spam registrations (if you keep registrations open) and to ensure Element Call continues to work in case any user decides to log in to their Element Call account using the standard Element app and joins normal rooms that Element Call cannot handle. +Therefore, to use a self-hosted homeserver, this is recommended to be a new +server where any user account created has not joined any normal rooms anywhere +in the Matrix federated network. The homeserver used can be setup to disable +federation, so as to prevent spam registrations (if you keep registrations open) +and to ensure Element Call continues to work in case any user decides to log in +to their Element Call account using the standard Element app and joins normal +rooms that Element Call cannot handle. ## Configuration -There are currently two different config files. `.env` holds variables that are used at build time, while `public/config.json` holds variables that are used at runtime. Documentation and default values for `public/config.json` can be found in [ConfigOptions.ts](src/config/ConfigOptions.ts). +There are currently two different config files. `.env` holds variables that are +used at build time, while `public/config.json` holds variables that are used at +runtime. Documentation and default values for `public/config.json` can be found +in [ConfigOptions.ts](src/config/ConfigOptions.ts). -If you're using [Synapse](https://github.com/element-hq/synapse/), you'll need to additionally add the following to `homeserver.yaml` or Element Call won't work: +If you're using [Synapse](https://github.com/element-hq/synapse/), you'll need +to additionally add the following to `homeserver.yaml` or Element Call won't +work: ``` experimental_features: @@ -72,10 +104,16 @@ rc_message: burst_count: 30 ``` -MSC3266 allows to request a room summary of rooms you are not joined. -The summary contains the room join rules. We need that to decide if the user gets prompted with the option to knock ("ask to join"), a cannot join error or the join view. +MSC3266 allows to request a room summary of rooms you are not joined. The +summary contains the room join rules. We need that to decide if the user gets +prompted with the option to knock ("ask to join"), a cannot join error or the +join view. -Element Call requires a Livekit SFU behind a [Livekit JWT service](https://github.com/element-hq/lk-jwt-service) to work. The url to the Livekit JWT service can either be configured in the config of Element Call (fallback/legacy configuration) or be configured by your homeserver via the `.well-known/matrix/client`. This is the recommended method. +Element Call requires a Livekit SFU alongside a [Livekit JWT +service](https://github.com/element-hq/lk-jwt-service) to work. The url to the +Livekit JWT service can either be configured in the config of Element Call +(fallback/legacy configuration) or be configured by your homeserver via the +`.well-known/matrix/client`. This is the recommended method. The configuration is a list of Foci configs: @@ -98,13 +136,18 @@ The configuration is a list of Foci configs: ## Translation -If you'd like to help translate Element Call, head over to [Localazy](https://localazy.com/p/element-call). You're also encouraged to join the [Element Translators](https://matrix.to/#/#translators:element.io) space to discuss and coordinate translation efforts. +If you'd like to help translate Element Call, head over to +[Localazy](https://localazy.com/p/element-call). You're also encouraged to join +the [Element Translators](https://matrix.to/#/#translators:element.io) space to +discuss and coordinate translation efforts. ## Development ### Frontend -Element Call is built against [matrix-js-sdk](https://github.com/matrix-org/matrix-js-sdk/pull/2553). To get started, clone, install, and link the package: +Element Call is built against +[matrix-js-sdk](https://github.com/matrix-org/matrix-js-sdk/pull/2553). To get +started, clone, install, and link the package: ``` git clone https://github.com/matrix-org/matrix-js-sdk.git @@ -122,13 +165,14 @@ yarn yarn link matrix-js-sdk ``` -To use it, create a local config by, e.g., `cp ./config/config.sample.json -./public/config.json` and adapt it if necessary. The sample config should work -with the backend development environment as outlined in the next section out of -box. +To use it, create a local config by, e.g., `cp ./config/config.devenv.json +./public/config.json` and adapt it if necessary. The `config.devenv.json` config +should work with the backend development environment as outlined in the next +section out of box. -(Be aware, that this is only the fallback Livekit SFU. If the homeserver -advertises one in the client well-known, this will not be used.) +(Be aware, that this `config.devenv.json` is exposing a deprecated fallback +LiveKit config key. If the homeserver advertises SFU backend via +`.well-known/matrix/client` this has precedence.) You're now ready to launch the development server: @@ -167,7 +211,8 @@ yarn backend To add a new translation key you can do these steps: 1. Add the new key entry to the code where the new key is used: `t("some_new_key")` -1. Run `yarn i18n` to extract the new key and update the translation files. This will add a skeleton entry to the `public/locales/en-GB/app.json` file: +1. Run `yarn i18n` to extract the new key and update the translation files. This + will add a skeleton entry to the `public/locales/en-GB/app.json` file: ```jsonc { ... @@ -175,8 +220,9 @@ To add a new translation key you can do these steps: ... } ``` -1. Update the skeleton entry in the `public/locales/en-GB/app.json` file with the English translation: - ```jsonc +1. Update the skeleton entry in the `public/locales/en-GB/app.json` file with + the English translation: +```jsonc { ... "some_new_key": "Some new key", diff --git a/backend/tls_localhost_nginx.conf b/backend/tls_localhost_nginx.conf index 19efa5ba..2a593210 100644 --- a/backend/tls_localhost_nginx.conf +++ b/backend/tls_localhost_nginx.conf @@ -13,7 +13,7 @@ server { # Note well-known is currently not effective due to: # https://spec.matrix.org/v1.12/client-server-api/#well-known-uri the spec # says it must be at https://$server_name/... (implied port 443) Hence, we - # currently rely for local development environment on depricated config.json + # currently rely for local development environment on deprecated config.json # setting for livekit_service_url location /.well-known/matrix/client { return 200 '{"m.homeserver": {"base_url": "http://synapse.localhost:8008"}, "org.matrix.msc4143.rtc_foci": [{"type": "livekit", "livekit_service_url": "http://localhost:8080"}]}';