Browse Source

Merge branch 'develop' of github.com:vector-im/element-web into t3chguy/querystring

 Conflicts:
	package.json
	src/@types/global.d.ts
	src/vector/app.tsx
	src/vector/jitsi/index.ts
	src/vector/platform/WebPlatform.ts
	yarn.lock
pull/13138/head
Michael Telatynski 10 months ago
parent
commit
b03b4582c0
  1. 1
      .dockerignore
  2. 31
      .eslintrc.js
  3. 12
      .github/ISSUE_TEMPLATE.md
  4. 14
      .github/ISSUE_TEMPLATE/bug_report.md
  5. 10
      .github/ISSUE_TEMPLATE/suggestion-or-feature-request.md
  6. 58
      .github/ISSUE_TEMPLATE/user-interface-or-usability-bug-report.md
  7. 11
      .github/PULL_REQUEST_TEMPLATE.md
  8. 5
      .gitignore
  9. 6
      .modernizr.json
  10. 2
      .stylelintrc.js
  11. 3
      AUTHORS.rst
  12. 1205
      CHANGELOG.md
  13. 4
      CONTRIBUTING.md
  14. 4
      CONTRIBUTING.rst
  15. 6
      Dockerfile
  16. 375
      README.md
  17. 1
      __mocks__/cssMock.js
  18. 15
      babel.config.js
  19. 12
      config.sample.json
  20. 8
      contribute.json
  21. 81
      docs/app-load.md
  22. 52
      docs/conferencing.md
  23. 157
      docs/config.md
  24. 34
      docs/customisations.md
  25. 63
      docs/e2ee.md
  26. 87
      docs/feature-flags.md
  27. BIN
      docs/img/pr-checks.png
  28. 28
      docs/jitsi-dev.md
  29. 38
      docs/jitsi.md
  30. 187
      docs/kubernetes.md
  31. 84
      docs/labs.md
  32. 10
      docs/memory-profiles-and-leaks.md
  33. 59
      docs/native-node-modules.md
  34. 33
      docs/pr-previews.md
  35. 58
      docs/review.md
  36. 16
      docs/skinning thoughts.md
  37. 30
      docs/theming.md
  38. 4
      docs/translating-dev.md
  39. 22
      docs/translating.md
  40. 28
      electron_app/build/entitlements.mac.plist
  41. BIN
      electron_app/build/icon.icns
  42. BIN
      electron_app/build/icon.ico
  43. BIN
      electron_app/build/icons/128x128.png
  44. BIN
      electron_app/build/icons/16x16.png
  45. BIN
      electron_app/build/icons/24x24.png
  46. BIN
      electron_app/build/icons/256x256.png
  47. BIN
      electron_app/build/icons/48x48.png
  48. BIN
      electron_app/build/icons/512x512.png
  49. BIN
      electron_app/build/icons/64x64.png
  50. BIN
      electron_app/build/icons/96x96.png
  51. BIN
      electron_app/build/install-spinner.gif
  52. BIN
      electron_app/img/riot.ico
  53. BIN
      electron_app/img/riot.png
  54. 15
      electron_app/package.json
  55. 34
      electron_app/riot.im/New_Vector_Ltd.pem
  56. 6
      electron_app/riot.im/README
  57. 39
      electron_app/riot.im/config.json
  58. 1
      electron_app/riot.im/env.sh
  59. 641
      electron_app/src/electron-main.js
  60. 53
      electron_app/src/protocol.js
  61. 51
      electron_app/src/squirrelhooks.js
  62. 106
      electron_app/src/tray.js
  63. 84
      electron_app/src/updater.js
  64. 144
      electron_app/src/vectormenu.js
  65. 191
      electron_app/src/webcontents-handler.js
  66. 837
      electron_app/yarn.lock
  67. 9
      element.io/README
  68. 52
      element.io/app/config.json
  69. 2
      element.io/app/deploy.py
  70. 31
      element.io/develop/config.json
  71. 249
      package.json
  72. 18
      release.sh
  73. 101
      res/css/structures/ErrorView.scss
  74. 107
      res/decoder-ring/datatypes.js
  75. 336
      res/decoder-ring/decoder.js
  76. 79
      res/decoder-ring/index.html
  77. 87
      res/manifest.json
  78. 2
      res/sw.js
  79. BIN
      res/themes/element/img/backgrounds/lake.jpg
  80. 97
      res/themes/element/img/download/apple.svg
  81. 135
      res/themes/element/img/download/fdroid.svg
  82. 70
      res/themes/element/img/download/google.svg
  83. 6
      res/themes/element/img/logos/element-logo.svg
  84. BIN
      res/themes/element/img/logos/opengraph.png
  85. BIN
      res/themes/riot/img/backgrounds/valley.jpg
  86. BIN
      res/themes/riot/img/logos/riot-im-logo-black-text.png
  87. 17
      res/themes/riot/img/logos/riot-im-logo-black-text.svg
  88. BIN
      res/themes/riot/img/logos/riot-im-logo.png
  89. 17
      res/themes/riot/img/logos/riot-im-logo.svg
  90. 6
      res/themes/riot/img/logos/riot-logo.svg
  91. BIN
      res/vector-icons/1024.png
  92. BIN
      res/vector-icons/120.png
  93. BIN
      res/vector-icons/1240x600.png
  94. BIN
      res/vector-icons/150.png
  95. BIN
      res/vector-icons/152.png
  96. BIN
      res/vector-icons/180.png
  97. BIN
      res/vector-icons/24.png
  98. BIN
      res/vector-icons/300.png
  99. BIN
      res/vector-icons/44.png
  100. BIN
      res/vector-icons/50.png
  101. Some files were not shown because too many files have changed in this diff Show More

1
.dockerignore

@ -3,7 +3,6 @@ test/
webapp/
lib/
node_modules/
electron_app/
karma-reports/
.idea/
.tmp/

31
.eslintrc.js

@ -1,3 +1,30 @@
module.exports = {
extends: ["./node_modules/matrix-react-sdk/.eslintrc.js"],
}
plugins: ["matrix-org"],
extends: [
"plugin:matrix-org/babel",
"plugin:matrix-org/react",
],
env: {
browser: true,
node: true,
},
rules: {
// Things we do that break the ideal style
"quotes": "off",
},
overrides: [{
files: ["src/**/*.{ts,tsx}"],
extends: [
"plugin:matrix-org/typescript",
"plugin:matrix-org/react",
],
rules: {
// Things we do that break the ideal style
"prefer-promise-reject-errors": "off",
"quotes": "off",
// We disable this while we're transitioning
"@typescript-eslint/no-explicit-any": "off",
},
}],
};

12
.github/ISSUE_TEMPLATE.md

@ -1,3 +1,5 @@
<!-- A picture's worth a thousand words: PLEASE INCLUDE A SCREENSHOT :P -->
<!-- Please report security issues by email to security@matrix.org -->
<!-- This is a bug report template. By following the instructions below and
@ -10,11 +12,11 @@ that aren't relevant to your particular case.
Text between <!-- and --> marks will be invisible in the report.
-->
### Description
#### Description
Describe here the problem that you are experiencing, or the feature you are requesting.
### Steps to reproduce
#### Steps to reproduce
- For bugs, list the steps
- that reproduce the bug
@ -28,7 +30,7 @@ file a bug here too! -->
<!-- Include screenshots if possible: you can drag and drop images below. -->
### Version information
#### Version information
<!-- IMPORTANT: please answer the following questions, to help us narrow down the problem -->
@ -36,9 +38,9 @@ file a bug here too! -->
For the web app:
- **Browser**: Chrome, Safari, Firefox? which version?
- **Browser**: Chrome, Firefox, Safari, Edge? which version?
- **OS**: Windows, macOS, Ubuntu, Arch Linux, etc?
- **URL**: riot.im/develop / riot.im/app / somewhere else? If a private server, what version of riot-web?
- **URL**: develop.element.io / app.element.io / somewhere else? If a private server, what version of Element Web?
For the desktop app:

14
.github/ISSUE_TEMPLATE/bug_report.md

@ -2,11 +2,13 @@
name: Bug report
about: Create a report to help us improve
title: ''
labels: bug
labels: T-Defect
assignees: ''
---
<!-- A picture's worth a thousand words: PLEASE INCLUDE A SCREENSHOT :P -->
<!-- Please report security issues by email to security@matrix.org -->
<!-- This is a bug report template. By following the instructions below and
@ -19,11 +21,11 @@ that aren't relevant to your particular case.
Text between <!-- and --> marks will be invisible in the report.
-->
### Description
#### Description
Describe here the problem that you are experiencing, or the feature you are requesting.
### Steps to reproduce
#### Steps to reproduce
- For bugs, list the steps
- that reproduce the bug
@ -38,7 +40,7 @@ Logs being sent: yes/no
<!-- Include screenshots if possible: you can drag and drop images below. -->
### Version information
#### Version information
<!-- IMPORTANT: please answer the following questions, to help us narrow down the problem -->
@ -46,9 +48,9 @@ Logs being sent: yes/no
For the web app:
- **Browser**: Chrome, Safari, Firefox? which version?
- **Browser**: Chrome, Firefox, Safari, Edge? which version?
- **OS**: Windows, macOS, Ubuntu, Arch Linux, etc?
- **URL**: riot.im/develop / riot.im/app / somewhere else? If a private server, what version of riot-web?
- **URL**: develop.element.io / app.element.io / somewhere else? If a private server, what version of Element Web?
For the desktop app:

10
.github/ISSUE_TEMPLATE/suggestion-or-feature-request.md

@ -2,19 +2,19 @@
name: Suggestion or Feature request
about: Suggest an idea for this project
title: ''
labels: suggestion
labels: T-Enhancement
assignees: ''
---
**Is your suggestion related to a problem? Please describe.**
#### Is your suggestion related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
#### Describe the solution you'd like.
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
#### Describe alternatives you've considered.
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
#### Additional context
Add any other context or screenshots about the feature request here.

58
.github/ISSUE_TEMPLATE/user-interface-or-usability-bug-report.md

@ -1,58 +0,0 @@
---
name: User Interface or Usability Bug report
about: Please include screenshots in UI/UX bug reports
title: ''
labels: bug, ui/ux
assignees: ''
---
<!-- A picture's worth a thousand words: PLEASE INCLUDE A SCREENSHOT :P -->
<!-- Please report security issues by email to security@matrix.org -->
<!-- This is a bug report template. By following the instructions below and
filling out the sections with your information, you will help the us to get all
the necessary data to fix your issue.
You can also preview your report before submitting it. You may remove sections
that aren't relevant to your particular case.
Text between <!-- and --> marks will be invisible in the report.
-->
### Description
Describe here the problem that you are experiencing, or the feature you are requesting.
### Steps to reproduce
- For bugs, list the steps
- that reproduce the bug
- using hyphens as bullet points
Describe how what happens differs from what you expected.
<!-- Please send us logs for your bug report. They're very important for bugs
which are hard to reproduce. To do this, create this issue then go to your
account settings and click 'Submit Debug Logs' from the Help & About tab -->
Logs being sent: yes/no
<!-- Include screenshots if possible: you can drag and drop images below. -->
### Version information
<!-- IMPORTANT: please answer the following questions, to help us narrow down the problem -->
- **Platform**: web (in-browser) or desktop?
For the web app:
- **Browser**: Chrome, Safari, Firefox? which version?
- **OS**: Windows, macOS, Ubuntu, Arch Linux, etc?
- **URL**: riot.im/develop / riot.im/app / somewhere else? If a private server, what version of riot-web?
For the desktop app:
- **OS**: Windows, macOS, Ubuntu, Arch Linux, etc?
- **Version**: 1.x.y <!-- check the user settings panel if unsure -->

11
.github/PULL_REQUEST_TEMPLATE.md

@ -0,0 +1,11 @@
<!-- Please read https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.md before submitting your pull request -->
<!-- Include a Sign-Off as described in https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.md#sign-off -->
<!-- To specify text for the changelog entry (otherwise the PR title will be used):
Notes:
Changelog entries will also appear in element-desktop. For PRs that *only* affect the desktop version:
Notes: none
element-desktop notes: <notes>
-->

5
.gitignore vendored

@ -4,9 +4,6 @@
/key.pem
/lib
/node_modules
/electron_app/node_modules
/electron_app/dist
/electron_app/pub
/packages/
/webapp
/.npmrc
@ -22,3 +19,5 @@ electron/pub
/src/component-index.js
/.tmp
/webpack-stats.json
.vscode
.vscode/

6
.modernizr.json

@ -1,9 +1,6 @@
{
"minify": true,
"classPrefix": "modernizr_",
"options": [
"setClasses"
],
"enableClasses": false,
"feature-detects": [
"test/css/animations",
"test/css/displaytable",
@ -29,6 +26,7 @@
"test/url/urlsearchparams",
"test/cors",
"test/crypto",
"test/iframe/sandbox",
"test/json",
"test/network/fetch",

2
.stylelintrc.js

@ -19,7 +19,7 @@ module.exports = {
"at-rule-no-unknown": null,
"no-descending-specificity": null,
"scss/at-rule-no-unknown": [true, {
// https://github.com/vector-im/riot-web/issues/10544
// https://github.com/vector-im/element-web/issues/10544
"ignoreAtRules": ["define-mixin"],
}],
}

3
AUTHORS.rst

@ -16,3 +16,6 @@ include:
* Alexandr Korsak (https://github.com/oivoodoo)
Improved multiple file uploading
* Thom Cleary (https://github.com/thomcatdotrocks)
Small update for tarball deployment

1205
CHANGELOG.md

File diff suppressed because it is too large Load Diff

4
CONTRIBUTING.md

@ -0,0 +1,4 @@
Contributing code to Element
============================
Element follows the same pattern as https://github.com/matrix-org/matrix-js-sdk/blob/master/CONTRIBUTING.rst.

4
CONTRIBUTING.rst

@ -1,4 +0,0 @@
Contributing code to Riot
=========================
Riot follows the same pattern as https://github.com/matrix-org/matrix-js-sdk/blob/master/CONTRIBUTING.rst.

6
Dockerfile

@ -1,8 +1,8 @@
# Builder
FROM node:10 as builder
FROM node:14-buster as builder
# Support custom branches of the react-sdk and js-sdk. This also helps us build
# images of riot-web develop.
# images of element-web develop.
ARG USE_CUSTOM_SDKS=false
ARG REACT_SDK_REPO="https://github.com/matrix-org/matrix-react-sdk.git"
ARG REACT_SDK_BRANCH="master"
@ -34,4 +34,4 @@ COPY --from=builder /src/webapp /app
RUN sed -i '3i\ \ \ \ application/wasm wasm\;' /etc/nginx/mime.types
RUN rm -rf /usr/share/nginx/html \
&& ln -s /app /usr/share/nginx/html
&& ln -s /app /usr/share/nginx/html

375
README.md

@ -1,80 +1,122 @@
Riot
====
Element
=======
Riot (formerly known as Vector) is a Matrix web client built using the [Matrix
Element (formerly known as Vector and Riot) is a Matrix web client built using the [Matrix
React SDK](https://github.com/matrix-org/matrix-react-sdk).
Supported Environments
======================
Riot has several tiers of support for different environments:
Element has several tiers of support for different environments:
* Supported
* Definition: Issues **actively triaged**, regressions **block** the release
* Last 2 major versions of Chrome, Firefox, and Safari on desktop OSes
* Latest release of official Riot Desktop app on desktop OSes
* Last 2 major versions of Chrome, Firefox, Safari, and Edge on desktop OSes
* Latest release of official Element Desktop app on desktop OSes
* Desktop OSes means macOS, Windows, and Linux versions for desktop devices
that are actively supported by the OS vendor and receive security updates
* Experimental
* Definition: Issues **accepted**, regressions **do not block** the release
* Riot as an installed PWA via current stable version of Chrome, Firefox, and Safari
* Element as an installed PWA via current stable version of Chrome, Firefox, and Safari
* Mobile web for current stable version of Chrome, Firefox, and Safari on Android, iOS, and iPadOS
* Not supported
* Definition: Issues only affecting unsupported environments are **closed**
* Everything else
For accessing Riot on an Android or iOS device, we currently recommend the
native apps [riot-android](https://github.com/vector-im/riot-android)
and [riot-ios](https://github.com/vector-im/riot-ios).
For accessing Element on an Android or iOS device, we currently recommend the
native apps [element-android](https://github.com/vector-im/element-android)
and [element-ios](https://github.com/vector-im/element-ios).
Getting Started
===============
The easiest way to test Riot is to just use the hosted copy at https://riot.im/app.
The `develop` branch is continuously deployed by Jenkins at https://riot.im/develop
The easiest way to test Element is to just use the hosted copy at https://app.element.io.
The `develop` branch is continuously deployed to https://develop.element.io
for those who like living dangerously.
To host your own copy of Riot, the quickest bet is to use a pre-built
released version of Riot:
To host your own copy of Element, the quickest bet is to use a pre-built
released version of Element:
1. Download the latest version from https://github.com/vector-im/riot-web/releases
1. Download the latest version from https://github.com/vector-im/element-web/releases
1. Untar the tarball on your web server
1. Move (or symlink) the `riot-x.x.x` directory to an appropriate name
1. Move (or symlink) the `element-x.x.x` directory to an appropriate name
1. Configure the correct caching headers in your webserver (see below)
1. If desired, copy `config.sample.json` to `config.json` and edit it
as desired. See the [configuration docs](docs/config.md) for details.
1. Enter the URL into your browser and log into Riot!
1. Enter the URL into your browser and log into Element!
Releases are signed using gpg and the OpenPGP standard, and can be checked against the public key located
at https://packages.riot.im/riot-release-key.asc.
at https://packages.riot.im/element-release-key.asc.
Note that for the security of your chats will need to serve Riot
Note that for the security of your chats will need to serve Element
over HTTPS. Major browsers also do not allow you to use VoIP/video
chats over HTTP, as WebRTC is only usable over HTTPS.
There are some exceptions like when using localhost, which is
considered a [secure context](https://developer.mozilla.org/docs/Web/Security/Secure_Contexts)
and thus allowed.
To install Riot as a desktop application, see [Running as a desktop
To install Element as a desktop application, see [Running as a desktop
app](#running-as-a-desktop-app) below.
Important Security Note
=======================
Important Security Notes
========================
Separate domains
----------------
We do not recommend running Riot from the same domain name as your Matrix
We do not recommend running Element from the same domain name as your Matrix
homeserver. The reason is the risk of XSS (cross-site-scripting)
vulnerabilities that could occur if someone caused Riot to load and render
vulnerabilities that could occur if someone caused Element to load and render
malicious user generated content from a Matrix API which then had trusted
access to Riot (or other apps) due to sharing the same domain.
access to Element (or other apps) due to sharing the same domain.
We have put some coarse mitigations into place to try to protect against this
situation, but it's still not good practice to do it in the first place. See
https://github.com/vector-im/riot-web/issues/1977 for more details.
https://github.com/vector-im/element-web/issues/1977 for more details.
Configuration best practices
----------------------------
Unless you have special requirements, you will want to add the following to
your web server configuration when hosting Element Web:
- The `X-Frame-Options: SAMEORIGIN` header, to prevent Element Web from being
framed and protect from [clickjacking][owasp-clickjacking].
- The `frame-ancestors 'none'` directive to your `Content-Security-Policy`
header, as the modern replacement for `X-Frame-Options` (though both should be
included since not all browsers support it yet, see
[this][owasp-clickjacking-csp]).
- The `X-Content-Type-Options: nosniff` header, to [disable MIME
sniffing][mime-sniffing].
- The `X-XSS-Protection: 1; mode=block;` header, for basic XSS protection in
legacy browsers.
[mime-sniffing]:
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing>
[owasp-clickjacking-csp]:
<https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html#content-security-policy-frame-ancestors-examples>
[owasp-clickjacking]:
<https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html>
If you are using nginx, this would look something like the following:
```
add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Content-Security-Policy "frame-ancestors 'none'";
```
Note: In case you are already setting a `Content-Security-Policy` header
elsewhere, you should modify it to include the `frame-ancestors` directive
instead of adding that last line.
Building From Source
====================
Riot is a modular webapp built with modern ES6 and uses a Node.js build system.
Element is a modular webapp built with modern ES6 and uses a Node.js build system.
Ensure you have the latest LTS version of Node.js installed.
Using `yarn` instead of `npm` is recommended. Please see the Yarn [install
@ -82,13 +124,13 @@ guide](https://classic.yarnpkg.com/en/docs/install) if you do not have it alread
1. Install or update `node.js` so that your `node` is at least v10.x.
1. Install `yarn` if not present already.
1. Clone the repo: `git clone https://github.com/vector-im/riot-web.git`.
1. Switch to the riot-web directory: `cd riot-web`.
1. Clone the repo: `git clone https://github.com/vector-im/element-web.git`.
1. Switch to the element-web directory: `cd element-web`.
1. Install the prerequisites: `yarn install`.
* If you're using the `develop` branch, then it is recommended to set up a
proper development environment (see [Setting up a dev
environment](#setting-up-a-dev-environment) below). Alternatively, you
can use https://riot.im/develop - the continuous integration release of
can use https://develop.element.io - the continuous integration release of
the develop branch.
1. Configure the app by copying `config.sample.json` to `config.json` and
modifying it. See the [configuration docs](docs/config.md) for details.
@ -97,51 +139,19 @@ guide](https://classic.yarnpkg.com/en/docs/install) if you do not have it alread
web server.
Note that `yarn dist` is not supported on Windows, so Windows users can run `yarn build`,
which will build all the necessary files into the `webapp` directory. The version of Riot
which will build all the necessary files into the `webapp` directory. The version of Element
will not appear in Settings without using the dist script. You can then mount the
`webapp` directory on your webserver to actually serve up the app, which is entirely static content.
`webapp` directory on your web server to actually serve up the app, which is
entirely static content.
Running as a Desktop app
========================
Riot can also be run as a desktop app, wrapped in Electron. You can download a
pre-built version from https://riot.im/download/desktop/ or, if you prefer,
Element can also be run as a desktop app, wrapped in Electron. You can download a
pre-built version from https://element.io/get-started or, if you prefer,
build it yourself.
To build it yourself, follow the instructions below.
1. Follow the instructions in 'Building From Source' above, but run
`yarn build` instead of `yarn dist` (since we don't need the tarball).
2. Install Electron and run it:
```bash
yarn electron
```
To build packages, use `electron-builder`. This is configured to output:
* `dmg` + `zip` for macOS
* `exe` + `nupkg` for Windows
* `deb` for Linux
But this can be customised by editing the `build` section of package.json
as per https://github.com/electron-userland/electron-builder/wiki/Options
See https://github.com/electron-userland/electron-builder/wiki/Multi-Platform-Build
for dependencies required for building packages for various platforms.
The only platform that can build packages for all three platforms is macOS:
```bash
brew install mono
yarn install
yarn build:electron
```
For other packages, use `electron-builder` manually. For example, to build a
package for 64 bit Linux:
1. Follow the instructions in 'Building From Source' above
2. `node_modules/.bin/build -l --x64`
All Electron packages go into `electron_app/dist/`
To build it yourself, follow the instructions at https://github.com/vector-im/element-desktop.
Many thanks to @aviraldg for the initial work on the Electron integration.
@ -150,7 +160,7 @@ Other options for running as a desktop app:
```bash
yarn global add nativefier
nativefier https://riot.im/app/
nativefier https://app.element.io/
```
The [configuration docs](docs/config.md#desktop-app-configuration) show how to
@ -159,31 +169,31 @@ override the desktop app's default settings if desired.
Running from Docker
===================
The Docker image can be used to serve riot-web as a web server. The easiest way to use
The Docker image can be used to serve element-web as a web server. The easiest way to use
it is to use the prebuilt image:
```bash
docker run -p 80:80 vectorim/riot-web
docker run -p 80:80 vectorim/element-web
```
To supply your own custom `config.json`, map a volume to `/app/config.json`. For example,
if your custom config was located at `/etc/riot-web/config.json` then your Docker command
if your custom config was located at `/etc/element-web/config.json` then your Docker command
would be:
```bash
docker run -p 80:80 -v /etc/riot-web/config.json:/app/config.json vectorim/riot-web
docker run -p 80:80 -v /etc/element-web/config.json:/app/config.json vectorim/element-web
```
To build the image yourself:
```bash
git clone https://github.com/vector-im/riot-web.git riot-web
cd riot-web
git clone https://github.com/vector-im/element-web.git element-web
cd element-web
git checkout master
docker build -t vectorim/riot-web .
docker build .
```
If you're building a custom branch, or want to use the develop branch, check out the appropriate
riot-web branch and then run:
element-web branch and then run:
```bash
docker build -t vectorim/riot-web:develop \
docker build -t \
--build-arg USE_CUSTOM_SDKS=true \
--build-arg REACT_SDK_REPO="https://github.com/matrix-org/matrix-react-sdk.git" \
--build-arg REACT_SDK_BRANCH="develop" \
@ -192,22 +202,28 @@ docker build -t vectorim/riot-web:develop \
.
```
Running in Kubernetes
=====================
The provided element-web docker image can also be run from within a Kubernetes cluster.
See the [Kubernetes example](docs/kubernetes.md) for more details.
config.json
===========
Riot supports a variety of settings to configure default servers, behaviour, themes, etc.
Element supports a variety of settings to configure default servers, behaviour, themes, etc.
See the [configuration docs](docs/config.md) for more details.
Labs Features
=============
Some features of Riot may be enabled by flags in the `Labs` section of the settings.
Some of these features are described in [labs.md](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md).
Some features of Element may be enabled by flags in the `Labs` section of the settings.
Some of these features are described in [labs.md](https://github.com/vector-im/element-web/blob/develop/docs/labs.md).
Caching requirements
====================
Riot requires the following URLs not to be cached, when/if you are serving Riot from your own webserver:
Element requires the following URLs not to be cached, when/if you are serving Element from your own webserver:
```
/config.*.json
/i18n
@ -219,20 +235,20 @@ Riot requires the following URLs not to be cached, when/if you are serving Riot
Development
===========
Before attempting to develop on Riot you **must** read the [developer guide
for `matrix-react-sdk`](https://github.com/matrix-org/matrix-react-sdk), which
also defines the design, architecture and style for Riot too.
Before attempting to develop on Element you **must** read the [developer guide
for `matrix-react-sdk`](https://github.com/matrix-org/matrix-react-sdk#developer-guide), which
also defines the design, architecture and style for Element too.
Before starting work on a feature, it's best to ensure your plan aligns well
with our vision for Riot. Please chat with the team in
[#riot-dev:matrix.org](https://matrix.to/#/#riot-dev:matrix.org) before you
with our vision for Element. Please chat with the team in
[#element-dev:matrix.org](https://matrix.to/#/#element-dev:matrix.org) before you
start so we can ensure it's something we'd be willing to merge.
You should also familiarise yourself with the ["Here be Dragons" guide
](https://docs.google.com/document/d/12jYzvkidrp1h7liEuLIe6BMdU0NUjndUYI971O06ooM)
to the tame & not-so-tame dragons (gotchas) which exist in the codebase.
The idea of Riot is to be a relatively lightweight "skin" of customisations on
The idea of Element is to be a relatively lightweight "skin" of customisations on
top of the underlying `matrix-react-sdk`. `matrix-react-sdk` provides both the
higher and lower level React components useful for building Matrix communication
apps using React.
@ -240,15 +256,15 @@ apps using React.
After creating a new component you must run `yarn reskindex` to regenerate
the `component-index.js` for the app (used in future for skinning).
Please note that Riot is intended to run correctly without access to the public
Please note that Element is intended to run correctly without access to the public
internet. So please don't depend on resources (JS libs, CSS, images, fonts)
hosted by external CDNs or servers but instead please package all dependencies
into Riot itself.
into Element itself.
Setting up a dev environment
============================
Much of the functionality in Riot is actually in the `matrix-react-sdk` and
Much of the functionality in Element is actually in the `matrix-react-sdk` and
`matrix-js-sdk` modules. It is possible to set these up in a way that makes it
easy to track the `develop` branches in git and to make local changes without
having to manually rebuild each time.
@ -258,7 +274,6 @@ First clone and build `matrix-js-sdk`:
``` bash
git clone https://github.com/matrix-org/matrix-js-sdk.git
pushd matrix-js-sdk
git checkout develop
yarn link
yarn install
popd
@ -269,36 +284,31 @@ Then similarly with `matrix-react-sdk`:
```bash
git clone https://github.com/matrix-org/matrix-react-sdk.git
pushd matrix-react-sdk
git checkout develop
yarn link
yarn link matrix-js-sdk
yarn install
popd
```
Finally, build and start Riot itself:
Finally, build and start Element itself:
```bash
git clone https://github.com/vector-im/riot-web.git
cd riot-web
git checkout develop
git clone https://github.com/vector-im/element-web.git
cd element-web
yarn link matrix-js-sdk
yarn link matrix-react-sdk
yarn install
yarn reskindex
yarn start
```
Wait a few seconds for the initial build to finish; you should see something like:
```
Hash: b0af76309dd56d7275c8
Version: webpack 1.12.14
Time: 14533ms
Asset Size Chunks Chunk Names
bundle.js 4.2 MB 0 [emitted] main
bundle.css 91.5 kB 0 [emitted] main
bundle.js.map 5.29 MB 0 [emitted] main
bundle.css.map 116 kB 0 [emitted] main
+ 1013 hidden modules
[element-js] <s> [webpack.Progress] 100%
[element-js]
[element-js] ℹ 「wdm」: 1840 modules
[element-js] ℹ 「wdm」: Compiled successfully.
```
Remember, the command will not terminate since it runs the web server
and rebuilds source files when they change. This development server also
@ -307,19 +317,43 @@ bundle.css.map 116 kB 0 [emitted] main
Configure the app by copying `config.sample.json` to `config.json` and
modifying it. See the [configuration docs](docs/config.md) for details.
Open http://127.0.0.1:8080/ in your browser to see your newly built Riot.
Open http://127.0.0.1:8080/ in your browser to see your newly built Element.
**Note**: The build script uses inotify by default on Linux to monitor directories
for changes. If the inotify limits are too low your build will fail silently or with
`Error: EMFILE: too many open files`. To avoid these issues, we recommend a watch limit
of at least `128M` and instance limit around `512`.
You may be interested in issues [#15750](https://github.com/vector-im/element-web/issues/15750) and
[#15774](https://github.com/vector-im/element-web/issues/15774) for further details.
To set a new inotify watch and instance limit, execute:
```
sudo sysctl fs.inotify.max_user_watches=131072
sudo sysctl fs.inotify.max_user_instances=512
sudo sysctl -p
```
If you wish, you can make the new limits permanent, by executing:
```
echo fs.inotify.max_user_watches=131072 | sudo tee -a /etc/sysctl.conf
echo fs.inotify.max_user_instances=512 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```
___
When you make changes to `matrix-react-sdk` or `matrix-js-sdk` they should be
automatically picked up by webpack and built.
If you add or remove any components from the Riot skin, you will need to rebuild
If you add or remove any components from the Element skin, you will need to rebuild
the skin's index by running, `yarn reskindex`.
If any of these steps error with, `file table overflow`, you are probably on a mac
which has a very low limit on max open files. Run `ulimit -Sn 1024` and try again.
You'll need to do this in each new terminal you open before building Riot.
You'll need to do this in each new terminal you open before building Element.
Running the tests
-----------------
@ -351,56 +385,81 @@ To add a new translation, head to the [translating doc](docs/translating.md).
For a developer guide, see the [translating dev doc](docs/translating-dev.md).
[<img src="https://translate.riot.im/widgets/riot-web/-/multi-auto.svg" alt="translationsstatus" width="340">](https://translate.riot.im/engage/riot-web/?utm_source=widget)
[<img src="https://translate.element.io/widgets/element-web/-/multi-auto.svg" alt="translationsstatus" width="340">](https://translate.element.io/engage/element-web/?utm_source=widget)
Triaging issues
===============
Issues will be triaged by the core team using the below set of tags.
Tags are meant to be used in combination - e.g.:
* P1 critical bug == really urgent stuff that should be next in the bugfixing todo list
* "release blocker" == stuff which is blocking us from cutting the next release.
* P1 feature type:voip == what VoIP features should we be working on next?
priority: **compulsory**
* P1: top priority - i.e. pool of stuff which we should be working on next
* P2: still need to fix, but lower than P1
* P3: non-urgent
* P4: interesting idea - bluesky some day
* P5: recorded for posterity/to avoid duplicates. No intention to resolves right now.
bug or feature: **compulsory**
* bug
* feature
bug severity: **compulsory, if bug**
* critical - whole app doesn't work
* major - entire feature doesn't work
* minor - partially broken feature (but still usable)
* cosmetic - feature works functionally but UI/UX is broken
types
* type:* - refers to a particular part of the app; used to filter bugs
on a given topic - e.g. VOIP, signup, timeline, etc.
additional categories (self-explanatory):
* release blocker
* ui/ux (think of this as cosmetic)
* network (specific to network conditions)
* platform specific
* accessibility
* maintenance
* performance
* i18n
* blocked - whether this issue currently can't be progressed due to outside factors
community engagement
* easy
* hacktoberfest
* bounty? - proposal to be included in a bounty programme
* bounty - included in Status Open Bounty
We strive to completely cover all applicable issues with these core labels:
1. __Type__ — Every issue is assigned a type:
- __[T-Defect](https://github.com/vector-im/element-web/labels/T-Defect):__
Bugs, crashes, hangs, vulnerabilities, or other reported problems
- __[T-Enhancement](https://github.com/vector-im/element-web/labels/T-Enhancement):__
New features, changes in functionality, performance boosts, user-facing
improvements
- __[T-Task](https://github.com/vector-im/element-web/labels/T-Task):__
Refactoring, enabling or disabling functionality, other engineering tasks
- __[T-Other](https://github.com/vector-im/element-web/labels/T-Other):__
Questions, user support, anything else
2. __Severity__ — All issues labeled `T-Defect` are also assigned a severity:
* __[S-Critical](https://github.com/vector-im/element-web/labels/S-Critical):__
Prevents work, causes data loss, affects many users, and/or has no
workaround
* __[S-Major](https://github.com/vector-im/element-web/labels/S-Major):__
Severely degrades major functionality or product features, with no
satisfactory workaround
* __[S-Minor](https://github.com/vector-im/element-web/labels/S-Minor):__
Impairs non-critical functionality, or suitable workarounds exist
* __[S-Tolerable](https://github.com/vector-im/element-web/labels/S-Tolerable):__
Purely cosmetic or low / no impact to users
3. __Priority__ — All issues which are not `T-Other` are assigned a priority:
* __[P1](https://github.com/vector-im/element-web/labels/P1):__ Next
* __[P2](https://github.com/vector-im/element-web/labels/P2):__ Later
* __[P3](https://github.com/vector-im/element-web/labels/P3):__ Eventually
* __[P4](https://github.com/vector-im/element-web/labels/P4):__ Interesting —
Not yet scheduled, will accept patches
* __[P5](https://github.com/vector-im/element-web/labels/P5):__ Dubious —
Will not schedule, would consider patches
4. __Area__ — Most issues are assigned one or several "areas" using one of the
many `A-` prefixed labels, e.g. `A-Composer` or `A-Spaces`. Each area label
maps to a group of features or portion of the UI surface in the app.
### Other common labels
We have a handful of other labels which are added on an as-needed basis, and not expected to be exhaustive:
* __Exceptions__ — Special flags for issues and pull requests:
* __[X-Needs-Info](https://github.com/vector-im/element-web/labels/X-Needs-Info):__
This issue is blocked pending further information from the reporter
* __[X-Regression](https://github.com/vector-im/element-web/labels/X-Regression):__
Denotes things breaking which previously worked
* __[X-Release-Blocker](https://github.com/vector-im/element-web/labels/X-Release-Blocker):__
Issues which must be resolved before making a release
* __[Easy](https://github.com/vector-im/element-web/labels/Easy)__ / __[Help
Wanted](https://github.com/vector-im/element-web/labels/Help%20Wanted)__ —
Well-defined issues which are suitable for folks new to the codebase
* __[A11y](https://github.com/vector-im/element-web/labels/A11y)__ /
__[Meta](https://github.com/vector-im/element-web/labels/Meta)__ /
__[I18n](https://github.com/vector-im/element-web/labels/I18n)__ /
__[Privacy](https://github.com/vector-im/element-web/labels/Privacy)__ /
__[Security](https://github.com/vector-im/element-web/labels/Security)__ —
Issues which fall under these conceptual themes (which apply to many software
projects and are not specific to Element)
* __[Sponsored](https://github.com/vector-im/element-web/labels/Sponsored)__ —
Used internally by Element to denote issues with external funding
### Ad hoc labels (`Z-`)
We have reserved the `Z-` prefix for ad hoc labels.
Any member of the core team is welcome to create labels beginning with `Z-` for
any purpose, such as tracking personal areas of interest or providing a common
way to label cross-repo initiatives. The prefix avoids interference with the
project's main labels.

1
__mocks__/cssMock.js

@ -0,0 +1 @@
module.exports = "css-file-stub";

15
babel.config.js

@ -3,12 +3,14 @@ module.exports = {
"presets": [
["@babel/preset-env", {
"targets": [
"last 2 Chrome versions", "last 2 Firefox versions", "last 2 Safari versions"
"last 2 Chrome versions",
"last 2 Firefox versions",
"last 2 Safari versions",
"last 2 Edge versions",
],
}],
"@babel/preset-typescript",
"@babel/preset-flow",
"@babel/preset-react"
"@babel/preset-react",
],
"plugins": [
["@babel/plugin-proposal-decorators", {legacy: true}],
@ -16,8 +18,9 @@ module.exports = {
"@babel/plugin-proposal-numeric-separator",
"@babel/plugin-proposal-class-properties",
"@babel/plugin-proposal-object-rest-spread",
"@babel/plugin-transform-flow-comments",
"@babel/plugin-proposal-optional-chaining",
"@babel/plugin-proposal-nullish-coalescing-operator",
"@babel/plugin-syntax-dynamic-import",
"@babel/plugin-transform-runtime"
]
"@babel/plugin-transform-runtime",
],
};

12
config.sample.json

@ -12,7 +12,7 @@
"disable_guests": false,
"disable_login_language_selector": false,
"disable_3pid_login": false,
"brand": "Riot",
"brand": "Element",
"integrations_ui_url": "https://scalar.vector.im/",
"integrations_rest_url": "https://scalar.vector.im/api",
"integrations_widgets_urls": [
@ -22,15 +22,10 @@
"https://scalar-staging.vector.im/api",
"https://scalar-staging.riot.im/scalar/api"
],
"bug_report_endpoint_url": "https://riot.im/bugreports/submit",
"bug_report_endpoint_url": "https://element.io/bugreports/submit",
"defaultCountryCode": "GB",
"showLabsSettings": false,
"features": {
"feature_pinning": "labs",
"feature_custom_status": "labs",
"feature_custom_tags": "labs",
"feature_state_counters": "labs"
},
"features": { },
"default_federate": true,
"default_theme": "light",
"roomDirectory": {
@ -38,7 +33,6 @@
"matrix.org"
]
},
"welcomeUserId": "@riot-bot:matrix.org",
"piwik": {
"url": "https://piwik.riot.im/",
"whitelistedHSUrls": ["https://matrix.org"],

8
contribute.json

@ -1,13 +1,13 @@
{
"name": "Riot",
"name": "Element",
"description": "A glossy Matrix collaboration client for the web.",
"repository": {
"url": "https://github.com/vector-im/riot-web",
"url": "https://github.com/vector-im/element-web",
"license": "Apache License 2.0"
},
"bugs": {
"list": "https://github.com/vector-im/riot-web/issues",
"report": "https://github.com/vector-im/riot-web/issues/new/choose"
"list": "https://github.com/vector-im/element-web/issues",
"report": "https://github.com/vector-im/element-web/issues/new/choose"
},
"keywords": [
"chat",

81
docs/app-load.md

@ -0,0 +1,81 @@
# App load order
Old slow flow:
![image](https://user-images.githubusercontent.com/2403652/73848963-00a2a080-4821-11ea-97d4-1200fc2638f3.png)
Current more parallel flow:
![image](https://user-images.githubusercontent.com/2403652/83146440-303a2900-a0ee-11ea-806b-4f53f039b957.png)
<details><summary>Code</summary>
<p>
<pre><code>
digraph G {
node [shape=box];
subgraph cluster_0 {
color=orange;
node [style=filled];
label = "index.ts";
entrypoint, s0, ready [shape=point];
rageshake, config, i18n, theme, skin, olm [shape=parallelogram];
mobile [shape=diamond, label="mobile"];
modernizr [shape=diamond];
redirect, incompatible [shape=egg];
entrypoint -> rageshake;
rageshake -> mobile [color=blue];
mobile -> s0 [label="No"];
mobile -> redirect [label="Yes"];
s0 -> platform;
s0 -> olm;
platform -> config;
config -> i18n [color=blue];
config -> theme [color=blue];
config -> skin [color=blue];
i18n -> modernizr [color=blue];
theme -> modernizr [color=blue];
skin -> modernizr [color=blue];
modernizr -> ready [label="Yes"];
modernizr -> incompatible [label="No"];
incompatible -> ready [label="user ignore"];
olm -> ready [color=red];
config -> ready [color=red];
skin -> ready [color=red];
theme -> ready [color=red];
i18n -> ready [color=red];
}
subgraph cluster_1 {
color = green;
node [style=filled];
label = "init.tsx";
ready -> loadApp;
loadApp -> matrixchat;
}
}
</code></pre>
</p>
</details>
Key:
+ Parallelogram: async/await task
+ Box: sync task
+ Diamond: conditional branch
+ Egg: user interaction
+ Blue arrow: async task is allowed to settle but allowed to fail
+ Red arrow: async task success is asserted
Notes:
+ A task begins when all its dependencies (arrows going into it) are fulfilled.
+ The success of setting up rageshake is never asserted, element-web has a fallback path for running without IDB (and thus rageshake).
+ Everything is awaited to be settled before the Modernizr check, to allow it to make use of things like i18n if they are successful.
Underlying dependencies:
![image](https://user-images.githubusercontent.com/2403652/73848977-08624500-4821-11ea-9830-bb0317c41086.png)

52
docs/conferencing.md

@ -1,52 +0,0 @@
# VoIP Conferencing
This is a draft proposal for a naive voice/video conferencing implementation for
Matrix clients. There are many possible conferencing architectures possible for
Matrix (Multipoint Conferencing Unit (MCU); Stream Forwarding Unit (SFU); Peer-
to-Peer mesh (P2P), etc; events shared in the group room; events shared 1:1;
possibly even out-of-band signalling).
This is a starting point for a naive MCU implementation which could provide one
possible Matrix-wide solution in future, which retains backwards compatibility
with standard 1:1 calling.
* A client chooses to initiate a conference for a given room by starting a
voice or video call with a 'conference focus' user. This is a virtual user
(typically Application Service) which implements a conferencing bridge. It
isn't defined how the client discovers or selects this user.
* The conference focus user MUST join the room in which the client has
initiated the conference - this may require the client to invite the
conference focus user to the room, depending on the room's `join_rules`. The
conference focus user needs to be in the room to let the bridge eject users
from the conference who have left the room in which it was initiated, and aid
discovery of the conference by other users in the room. The bridge
identifies the room to join based on the user ID by which it was invited.
The format of this identifier is implementation dependent for now.
* If a client leaves the group chat room, they MUST be ejected from the
conference. If a client leaves the 1:1 room with the conference focus user,
they SHOULD be ejected from the conference.
* For now, rooms can contain multiple conference focus users - it's left to
user or client implementation to select which to converge on. In future this
could be mediated using a state event (e.g. `im.vector.call.mcu`), but we
can't do that right now as by default normal users can't set arbitrary state
events on a room.
* To participate in the conference, other clients initiates a standard 1:1
voice or video call to the conference focus user.
* For best UX, clients SHOULD show the ongoing voice/video call in the UI
context of the group room rather than 1:1 with the focus user. If a client
recognises a conference user present in the room, it MAY chose to highlight
this in the UI (e.g. with a "conference ongoing" notification, to aid
discovery). Clients MAY hide the 1:1 room with the focus user (although in
future this room could be used for floor control or other direct
communication with the conference focus)
* When all users have left the conference, the 'conference focus' user SHOULD
leave the room.
* If a conference focus user joins a room but does not receive a 1:1 voice or
video call, it SHOULD time out after a period of time and leave the room.

157
docs/config.md

@ -4,13 +4,13 @@ Configuration
You can configure the app by copying `config.sample.json` to
`config.json` and customising it:
For a good example, see https://riot.im/develop/config.json.
For a good example, see https://develop.element.io/config.json.
1. `default_server_config` sets the default homeserver and identity server URL for
Riot to use. The object is the same as returned by [https://<server_name>/.well-known/matrix/client](https://matrix.org/docs/spec/client_server/latest.html#get-well-known-matrix-client),
Element to use. The object is the same as returned by [https://<server_name>/.well-known/matrix/client](https://matrix.org/docs/spec/client_server/latest.html#get-well-known-matrix-client),
with added support for a `server_name` under the `m.homeserver` section to display
a custom homeserver name. Alternatively, the config can contain a `default_server_name`
instead which is where Riot will go to get that same object, although this option is
instead which is where Element will go to get that same object, although this option is
deprecated - see the `.well-known` link above for more information on using this option.
Note that the `default_server_name` is used to get a complete server configuration
whereas the `server_name` in the `default_server_config` is for display purposes only.
@ -18,21 +18,24 @@ For a good example, see https://riot.im/develop/config.json.
`default_is_url`, however these are deprecated. They are maintained for backwards
compatibility with older configurations. `default_is_url` is respected only
if `default_hs_url` is used.
* Riot will fail to load if a mix of `default_server_config`, `default_server_name`, or
* Element will fail to load if a mix of `default_server_config`, `default_server_name`, or
`default_hs_url` is specified. When multiple sources are specified, it is unclear
which should take priority and therefore the application cannot continue.
* As of Riot 1.4.0, identity servers are optional. See [Identity servers](#identity-servers) below.
1. `features`: Lookup of optional features that may be `enable`d, `disable`d, or
exposed to the user in the `labs` section of settings. The available
optional experimental features vary from release to release and are [documented](labs.md). The feature flag process is
[documented](feature-flags.md) as well.
1. `showLabsSettings`: Shows the "labs" tab of user settings even when no `features` are enabled
or present. Useful for getting at settings which may be otherwise hidden.
* As of Element 1.4.0, identity servers are optional. See [Identity servers](#identity-servers) below.
1. `sso_immediate_redirect`: When `true`, Element will assume the default server supports SSO
and attempt to send the user there to continue (if they aren't already logged in). Default
`false`. Note that this disables all usage of the welcome page.
1. `features`: Lookup of optional features that may be force-enabled (`true`) or force-disabled (`false`).
When features are not listed here, their defaults will be used, and users can turn them on/off if `showLabsSettings`
allows them to. The available optional experimental features vary from release to release and are
[documented](labs.md). The feature flag process is [documented](feature-flags.md) as well.
1. `showLabsSettings`: Shows the "labs" tab of user settings. Useful to allow users to turn on experimental features
they might not otherwise have access to.
1. `brand`: String to pass to your homeserver when configuring email notifications, to let the
homeserver know what email template to use when talking to you.
1. `branding`: Configures various branding and logo details, such as:
1. `welcomeBackgroundUrl`: An image to use as a wallpaper outside the app
during authentication flows
during authentication flows. If an array is passed, an image is chosen randomly for each visit.
1. `authHeaderLogoUrl`: An logo image that is shown in the header during
authentication flows
1. `authFooterLinks`: a list of links to show in the authentication page footer:
@ -42,13 +45,13 @@ For a good example, see https://riot.im/develop/config.json.
1. `adminMessageMD`: An extra message to show on the reporting dialog to
mention homeserver-specific policies. Accepts Markdown.
1. `integrations_ui_url`: URL to the web interface for the integrations server. The integrations
server is not Riot and normally not your homeserver either. The integration server settings
server is not Element and normally not your homeserver either. The integration server settings
may be left blank to disable integrations.
1. `integrations_rest_url`: URL to the REST interface for the integrations server.
1. `integrations_widgets_urls`: list of URLs to the REST interface for the widget integrations server.
1. `bug_report_endpoint_url`: endpoint to send bug reports to (must be running a
https://github.com/matrix-org/rageshake server). Bug reports are sent when a user clicks
"Send Logs" within the application. Bug reports can be disabled by leaving the
"Send Logs" within the application. Bug reports can be disabled/hidden by leaving the
`bug_report_endpoint_url` out of your config file.
1. `roomDirectory`: config for the public room directory. This section is optional.
1. `roomDirectory.servers`: List of other homeservers' directories to include in the drop
@ -65,13 +68,16 @@ For a good example, see https://riot.im/develop/config.json.
1. `whitelistedISUrls`: a list of IS URLs to not redact from the analytics
1. `siteId`: The Piwik Site ID to use when sending analytics to the Piwik server configured above
1. `welcomeUserId`: the user ID of a bot to invite whenever users register that can give them a tour
1. `embeddedPages`: Configures the pages displayed in portions of Riot that
1. `embeddedPages`: Configures the pages displayed in portions of Element that
embed static files, such as:
1. `welcomeUrl`: Initial content shown on the outside of the app when not
logged in. Defaults to `welcome.html` supplied with Riot.
logged in. Defaults to `welcome.html` supplied with Element.
1. `homeUrl`: Content shown on the inside of the app when a specific room is
not selected. By default, no home page is configured. If one is set, a
button to access it will be shown in the top left menu.
1. `loginForWelcome`: Overrides `welcomeUrl` to make the welcome page be the
same page as the login page when `true`. This effectively disables the
welcome page.
1. `defaultCountryCode`: The ISO 3166 alpha2 country code to use when showing
country selectors, like the phone number input on the registration page.
Defaults to `GB` if the given code is unknown or not provided.
@ -80,25 +86,66 @@ For a good example, see https://riot.im/develop/config.json.
is special cased to the `default_theme` in the config file).
1. `disable_custom_urls`: disallow the user to change the
default homeserver when signing up or logging in.
1. `permalinkPrefix`: Used to change the URL that Riot generates permalinks with.
1. `permalinkPrefix`: Used to change the URL that Element generates permalinks with.
By default, this is "https://matrix.to" to generate matrix.to (spec) permalinks.
Set this to your Riot instance URL if you run an unfederated server (eg:
"https://riot.example.org").
Set this to your Element instance URL if you run an unfederated server (eg:
"https://element.example.org").
1. `jitsi`: Used to change the default conference options. Learn more about the
Jitsi options at [jitsi.md](./jitsi.md).
1. `preferredDomain`: The domain name of the preferred Jitsi instance. Defaults
to `jitsi.riot.im`. This is used whenever a user clicks on the voice/video
call buttons - integration managers may use a different domain.
1. `enable_presence_by_hs_url`: The property key should be the URL of the homeserver
and its value defines whether to enable/disable the presence status display
from that homeserver. If no options are configured, presence is shown for all
homeservers.
1. `disable_guests`: Disables guest access tokens and auto-guest registrations.
Defaults to false (guests are allowed).
1. `disable_login_language_selector`: Disables the login language selector. Defaults
to false (language selector is shown).
1. `disable_3pid_login`: Disables 3rd party identity options on login and registration form
Defaults to false (3rd party identity options are shown).
1. `default_federate`: Default option for room federation when creating a room
Defaults to true (room federation enabled).
1. `desktopBuilds`: Used to alter promotional links to the desktop app. By default
the builds are considered available and accessible from https://element.io. This
config option is typically used in the context of encouraging encrypted message
search capabilities (Seshat). All the options listed below are required if this
option is specified.
1. `available`: When false, the desktop app will not be promoted to the user.
1. `logo`: An HTTP URL to the avatar for the desktop build. Should be 24x24, ideally
an SVG.
1. `url`: An HTTP URL for where to send the user to download the desktop build.
1. `mobileBuilds`: Used to alter promotional links to the mobile app. By default the
builds are considered available and accessible from https://element.io. This config
option is typically used in a context of encouraging the user to try the mobile app
instead of a mobile/incompatible browser.
1. `ios`: The URL to the iOS build. If `null`, it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `android`: The URL to the Android build. If `null`, it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `fdroid`: The URL to the FDroid build. If `null`, it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `mobileGuideToast`: Whether to show a toast a startup which nudges users on
iOS and Android towards the native mobile apps. The toast redirects to the
mobile guide if they accept. Defaults to false.
1. `audioStreamUrl`: If supplied, show an option on Jitsi widgets to stream
audio using Jitsi's live streaming feature. This option is experimental and
may be removed at any time without notice.
1. `voip`: Behaviour related to calls
1. `obeyAssertedIdentity`: If set, MSC3086 asserted identity messages sent
on VoIP calls will cause the call to appear in the room corresponding to the
asserted identity. This *must* only be set in trusted environments.
Note that `index.html` also has an og:image meta tag that is set to an image
hosted on riot.im. This is the image used if links to your copy of Riot
appear in some websites like Facebook, and indeed Riot itself. This has to be
hosted on riot.im. This is the image used if links to your copy of Element
appear in some websites like Facebook, and indeed Element itself. This has to be
static in the HTML and an absolute URL (and HTTP rather than HTTPS), so it's
not possible for this to be an option in config.json. If you'd like to change
it, you can build Riot, but run
it, you can build Element, but run
`RIOT_OG_IMAGE_URL="http://example.com/logo.png" yarn build`.
Alternatively, you can edit the `og:image` meta tag in `index.html` directly
each time you download a new version of Riot.
each time you download a new version of Element.
Identity servers
================
@ -107,10 +154,10 @@ The identity server is used for inviting other users to a room via third party
identifiers like emails and phone numbers. It is not used to store your password
or account information.
As of Riot 1.4.0, all identity server functions are optional and you are
As of Element 1.4.0, all identity server functions are optional and you are
prompted to agree to terms before data is sent to the identity server.
Riot will check multiple sources when looking for an identity server to use in
Element will check multiple sources when looking for an identity server to use in
the following order of preference:
1. The identity server set in the user's account data
@ -120,28 +167,56 @@ the following order of preference:
login
3. The identity server provided by the Riot config file
If none of these sources have an identity server set, then Riot will prompt the
If none of these sources have an identity server set, then Element will prompt the
user to set an identity server first when attempting to use features that
require one.
Currently the only two public identity servers are https://vector.im and
Currently, the only two public identity servers are https://vector.im and
https://matrix.org, however in the future identity servers will be
decentralised.
Desktop app configuration
=========================
To run multiple instances of the desktop app for different accounts, you can
launch the executable with the `--profile` argument followed by a unique
identifier, e.g `riot-web --profile Work` for it to run a separate profile and
not interfere with the default one.
Alternatively, a custom location for the profile data can be specified using the
`--profile-dir` flag followed by the desired path.
+ `%APPDATA%\$NAME\config.json` on Windows
+ `$XDG_CONFIG_HOME\$NAME\config.json` or `~/.config/$NAME/config.json` on Linux
+ `~Library/Application Support/$NAME/config.json` on macOS
In the paths above, `$NAME` is typically `Riot`, unless you use `--profile
$PROFILE` in which case it becomes `Riot-$PROFILE`.
See https://github.com/vector-im/element-desktop#user-specified-configjson
UI Features
===========
Parts of the UI can be disabled using UI features. These are settings which appear
under `settingDefaults` and can only be `true` (default) or `false`. When `false`,
parts of the UI relating to that feature will be disabled regardless of the user's
preferences.
Currently, the following UI feature flags are supported:
* `UIFeature.urlPreviews` - Whether URL previews are enabled across the entire application.
* `UIFeature.feedback` - Whether prompts to supply feedback are shown.
* `UIFeature.voip` - Whether or not VoIP is shown readily to the user. When disabled,
Jitsi widgets will still work though they cannot easily be added.
* `UIFeature.widgets` - Whether or not widgets will be shown.
* `UIFeature.flair` - Whether or not community flair is shown in rooms.
* `UIFeature.communities` - Whether or not to show any UI related to communities. Implicitly
disables `UIFeature.flair` when disabled.
* `UIFeature.advancedSettings` - Whether or not sections titled "advanced" in room and
user settings are shown to the user.
* `UIFeature.shareQrCode` - Whether or not the QR code on the share room/event dialog
is shown.
* `UIFeature.shareSocial` - Whether or not the social icons on the share room/event dialog
are shown.
* `UIFeature.identityServer` - Whether or not functionality requiring an identity server
is shown. When disabled, the user will not be able to interact with the identity
server (sharing email addresses, 3PID invites, etc).
* `UIFeature.thirdPartyId` - Whether or not UI relating to third party identifiers (3PIDs)
is shown. Typically this is considered "contact information" on the homeserver, and is
not directly related to the identity server.
* `UIFeature.registration` - Whether or not the registration page is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.passwordReset` - Whether or not the password reset page is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.deactivate` - Whether or not the deactivate account button is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.advancedEncryption` - Whether or not advanced encryption options are shown to the
user.
* `UIFeature.roomHistorySettings` - Whether or not the room history settings are shown to the user.
This should only be used if the room history visibility options are managed by the server.

34
docs/customisations.md

@ -0,0 +1,34 @@
# Customisations
Element Web and the React SDK support "customisation points" that can be used to
easily add custom logic specific to a particular deployment of Element Web.
An example of this is the [security customisations
module](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/customisations/Security.ts).
This module in the React SDK only defines some empty functions and their types:
it does not do anything by default.
To make use of these customisation points, you will first need to fork Element
Web so that you can add your own code. Even though the default module is part of
the React SDK, you can still override it from the Element Web layer:
1. Copy the default customisation module to
`element-web/src/customisations/YourNameSecurity.ts`
2. Edit customisations points and make sure export the ones you actually want to
activate
3. Tweak the Element build process to use the customised module instead of the
default by adding this to the `additionalPlugins` array in `webpack.config.js`:
```js
new webpack.NormalModuleReplacementPlugin(
/src[\/\\]customisations[\/\\]Security\.ts/,
path.resolve(__dirname, 'src/customisations/YourNameSecurity.ts'),
),
```
If we add more customisation modules in the future, we'll likely improve these
steps to remove the need for build changes like the above.
By isolating customisations to their own module, this approach should remove the
chance of merge conflicts when updating your fork, and thus simplify ongoing
maintenance.

63