2020-07-17 11:18:01 +00:00
Element
=======
2015-06-09 16:40:42 +00:00
2020-07-17 11:56:19 +00:00
Element (formerly known as Vector and Riot) is a Matrix web client built using the [Matrix
2020-02-14 18:04:54 +00:00
React SDK](https://github.com/matrix-org/matrix-react-sdk).
2015-06-24 15:33:53 +00:00
2020-02-14 18:04:54 +00:00
Supported Environments
======================
2020-07-17 11:18:01 +00:00
Element has several tiers of support for different environments:
2020-02-14 18:04:54 +00:00
* Supported
* Definition: Issues **actively triaged** , regressions **block** the release
2021-03-05 13:17:47 +00:00
* Last 2 major versions of Chrome, Firefox, Safari, and Edge on desktop OSes
2020-07-17 11:18:01 +00:00
* Latest release of official Element Desktop app on desktop OSes
2020-02-24 16:52:28 +00:00
* Desktop OSes means macOS, Windows, and Linux versions for desktop devices
that are actively supported by the OS vendor and receive security updates
2020-02-14 18:04:54 +00:00
* Experimental
* Definition: Issues **accepted** , regressions **do not block** the release
2020-07-17 11:18:01 +00:00
* Element as an installed PWA via current stable version of Chrome, Firefox, and Safari
2020-02-14 18:04:54 +00:00
* 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
2020-07-17 11:18:01 +00:00
For accessing Element on an Android or iOS device, we currently recommend the
2020-08-16 08:59:05 +00:00
native apps [element-android ](https://github.com/vector-im/element-android )
and [element-ios ](https://github.com/vector-im/element-ios ).
2019-03-14 18:59:57 +00:00
2016-06-14 14:12:35 +00:00
Getting Started
2015-07-22 05:45:01 +00:00
===============
2016-07-11 17:25:58 +00:00
2021-08-01 15:05:33 +00:00
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 >
2019-02-10 08:53:38 +00:00
for those who like living dangerously.
2016-07-28 14:05:03 +00:00
2020-07-17 11:18:01 +00:00
To host your own copy of Element, the quickest bet is to use a pre-built
2020-07-17 11:52:36 +00:00
released version of Element:
2016-06-14 14:12:35 +00:00
2021-08-01 15:05:33 +00:00
1. Download the latest version from < https: // github . com / vector-im / element-web / releases >
2016-06-14 14:12:35 +00:00
1. Untar the tarball on your web server
2020-11-24 14:05:44 +00:00
1. Move (or symlink) the `element-x.x.x` directory to an appropriate name
2019-02-15 12:43:47 +00:00
1. Configure the correct caching headers in your webserver (see below)
2016-06-14 14:12:35 +00:00
1. If desired, copy `config.sample.json` to `config.json` and edit it
2019-06-27 18:04:06 +00:00
as desired. See the [configuration docs ](docs/config.md ) for details.
2020-07-17 11:18:01 +00:00
1. Enter the URL into your browser and log into Element!
2016-06-14 14:12:35 +00:00
2019-04-16 11:53:59 +00:00
Releases are signed using gpg and the OpenPGP standard, and can be checked against the public key located
2021-08-01 15:05:33 +00:00
at < https: / / packages . riot . im / element-release-key . asc > .
2016-10-25 10:20:23 +00:00
2020-07-17 11:18:01 +00:00
Note that for the security of your chats will need to serve Element
2018-03-21 15:18:08 +00:00
over HTTPS. Major browsers also do not allow you to use VoIP/video
2018-02-15 01:17:37 +00:00
chats over HTTP, as WebRTC is only usable over HTTPS.
2019-09-01 11:41:21 +00:00
There are some exceptions like when using localhost, which is
2019-08-27 20:28:15 +00:00
considered a [secure context ](https://developer.mozilla.org/docs/Web/Security/Secure_Contexts )
and thus allowed.
2018-12-19 20:50:16 +00:00
2020-07-17 11:18:01 +00:00
To install Element as a desktop application, see [Running as a desktop
2019-04-25 12:22:32 +00:00
app](#running-as-a-desktop-app) below.
2016-12-24 05:32:16 +00:00
2021-02-04 12:20:07 +00:00
Important Security Notes
========================
Separate domains
----------------
2016-08-26 23:13:20 +00:00
2020-07-17 11:18:01 +00:00
We do not recommend running Element from the same domain name as your Matrix
2016-10-20 15:54:30 +00:00
homeserver. The reason is the risk of XSS (cross-site-scripting)
2020-07-17 11:18:01 +00:00
vulnerabilities that could occur if someone caused Element to load and render
2016-10-20 15:54:30 +00:00
malicious user generated content from a Matrix API which then had trusted
2020-07-17 11:18:01 +00:00
access to Element (or other apps) due to sharing the same domain.
2016-08-26 23:13:20 +00:00
2016-10-20 15:54:30 +00:00
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
2021-08-01 15:05:33 +00:00
< https: / / github . com / vector-im / element-web / issues / 1977 > for more details.
2016-08-26 23:13:20 +00:00
2021-02-04 12:20:07 +00:00
Configuration best practices
----------------------------
Unless you have special requirements, you will want to add the following to
your web server configuration when hosting Element Web:
2021-08-01 15:05:33 +00:00
* The `X-Frame-Options: SAMEORIGIN` header, to prevent Element Web from being
2021-02-04 12:20:07 +00:00
framed and protect from [clickjacking][owasp-clickjacking].
2021-08-01 15:05:33 +00:00
* The `frame-ancestors 'none'` directive to your `Content-Security-Policy`
2021-02-04 12:20:07 +00:00
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]).
2021-08-01 15:05:33 +00:00
* The `X-Content-Type-Options: nosniff` header, to [disable MIME
2021-02-04 12:20:07 +00:00
sniffing][mime-sniffing].
2021-08-01 15:05:33 +00:00
* The `X-XSS-Protection: 1; mode=block;` header, for basic XSS protection in
2021-02-04 12:20:07 +00:00
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.
2016-06-14 14:12:35 +00:00
Building From Source
====================
2020-07-17 11:18:01 +00:00
Element is a modular webapp built with modern ES6 and uses a Node.js build system.
2019-03-13 10:53:21 +00:00
Ensure you have the latest LTS version of Node.js installed.
2015-06-24 16:58:13 +00:00
2019-03-12 11:06:57 +00:00
Using `yarn` instead of `npm` is recommended. Please see the Yarn [install
2020-04-10 21:43:54 +00:00
guide](https://classic.yarnpkg.com/en/docs/install) if you do not have it already.
2015-06-24 16:58:13 +00:00
2022-03-21 13:38:19 +00:00
1. Install or update `node.js` so that your `node` is at least the current recommended LTS.
2019-03-12 11:06:57 +00:00
1. Install `yarn` if not present already.
2020-08-16 08:59:05 +00:00
1. Clone the repo: `git clone https://github.com/vector-im/element-web.git` .
1. Switch to the element-web directory: `cd element-web` .
2019-03-12 11:06:57 +00:00
1. Install the prerequisites: `yarn install` .
2021-08-01 15:05:33 +00:00
* If you're using the `develop` branch, then it is recommended to set up a
2019-10-29 10:37:36 +00:00
proper development environment (see [Setting up a dev
environment](#setting-up-a-dev-environment) below). Alternatively, you
2021-08-01 15:05:33 +00:00
can use < https: / / develop . element . io > - the continuous integration release of
2019-10-29 10:37:36 +00:00
the develop branch.
2016-10-20 15:54:30 +00:00
1. Configure the app by copying `config.sample.json` to `config.json` and
2019-06-27 18:04:06 +00:00
modifying it. See the [configuration docs ](docs/config.md ) for details.
2019-03-12 11:06:57 +00:00
1. `yarn dist` to build a tarball to deploy. Untaring this file will give
2016-06-14 14:12:35 +00:00
a version-specific directory containing all the files that need to go on your
web server.
2015-06-24 16:58:13 +00:00
2019-03-12 11:06:57 +00:00
Note that `yarn dist` is not supported on Windows, so Windows users can run `yarn build` ,
2020-07-17 11:18:01 +00:00
which will build all the necessary files into the `webapp` directory. The version of Element
2019-02-10 08:53:38 +00:00
will not appear in Settings without using the dist script. You can then mount the
2021-02-04 12:20:07 +00:00
`webapp` directory on your web server to actually serve up the app, which is
entirely static content.
2015-10-01 15:02:44 +00:00
2016-07-28 14:05:03 +00:00
Running as a Desktop app
========================
2020-07-17 11:18:01 +00:00
Element can also be run as a desktop app, wrapped in Electron. You can download a
2021-08-01 15:05:33 +00:00
pre-built version from < https: / / element . io / get-started > or, if you prefer,
2019-04-25 12:22:32 +00:00
build it yourself.
2016-07-28 14:05:03 +00:00
2021-08-01 15:05:33 +00:00
To build it yourself, follow the instructions at < https: / / github . com / vector-im / element-desktop > .
2016-07-28 14:05:03 +00:00
2019-05-24 10:27:48 +00:00
Many thanks to @aviraldg for the initial work on the Electron integration.
2016-12-09 19:05:25 +00:00
Other options for running as a desktop app:
2021-08-01 15:05:33 +00:00
* @asdf:matrix .org points out that you can use nativefier and it just works(tm)
2016-12-17 19:17:58 +00:00
2019-02-10 08:53:38 +00:00
```bash
2019-03-12 11:06:57 +00:00
yarn global add nativefier
2020-07-17 11:18:01 +00:00
nativefier https://app.element.io/
2016-12-17 19:17:58 +00:00
```
2016-12-09 19:05:25 +00:00
2019-06-27 18:04:06 +00:00
The [configuration docs ](docs/config.md#desktop-app-configuration ) show how to
override the desktop app's default settings if desired.
2019-03-01 08:01:26 +00:00
2019-04-10 21:47:12 +00:00
Running from Docker
===================
2020-08-16 08:59:05 +00:00
The Docker image can be used to serve element-web as a web server. The easiest way to use
2019-04-10 21:47:12 +00:00
it is to use the prebuilt image:
2021-08-01 15:05:33 +00:00
2019-04-10 21:47:12 +00:00
```bash
2020-10-28 14:32:25 +00:00
docker run -p 80:80 vectorim/element-web
2019-10-10 14:54:52 +00:00
```
2019-04-10 21:47:12 +00:00
2019-10-10 14:54:52 +00:00
To supply your own custom `config.json` , map a volume to `/app/config.json` . For example,
2020-08-16 08:59:05 +00:00
if your custom config was located at `/etc/element-web/config.json` then your Docker command
2019-04-10 21:47:12 +00:00
would be:
2021-08-01 15:05:33 +00:00
2019-04-10 21:47:12 +00:00
```bash
2020-10-28 14:32:25 +00:00
docker run -p 80:80 -v /etc/element-web/config.json:/app/config.json vectorim/element-web
2019-04-10 21:47:12 +00:00
```
To build the image yourself:
2021-08-01 15:05:33 +00:00
2019-04-10 21:47:12 +00:00
```bash
2020-08-16 08:59:05 +00:00
git clone https://github.com/vector-im/element-web.git element-web
cd element-web
2019-04-10 21:47:12 +00:00
git checkout master
2020-08-22 07:52:05 +00:00
docker build .
2019-04-10 21:47:12 +00:00
```
If you're building a custom branch, or want to use the develop branch, check out the appropriate
2020-08-16 08:59:05 +00:00
element-web branch and then run:
2021-08-01 15:05:33 +00:00
2019-04-10 21:47:12 +00:00
```bash
2020-08-22 07:52:05 +00:00
docker build -t \
2019-04-10 21:51:06 +00:00
--build-arg USE_CUSTOM_SDKS=true \
2019-04-10 21:47:12 +00:00
--build-arg REACT_SDK_REPO="https://github.com/matrix-org/matrix-react-sdk.git" \
--build-arg REACT_SDK_BRANCH="develop" \
--build-arg JS_SDK_REPO="https://github.com/matrix-org/matrix-js-sdk.git" \
--build-arg JS_SDK_BRANCH="develop" \
.
```
2021-03-23 10:55:11 +00:00
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.
2019-06-28 12:50:50 +00:00
config.json
===========
2020-07-17 11:18:01 +00:00
Element supports a variety of settings to configure default servers, behaviour, themes, etc.
2019-06-28 12:50:50 +00:00
See the [configuration docs ](docs/config.md ) for more details.
2019-03-22 14:49:44 +00:00
Labs Features
=============
2020-07-17 11:18:01 +00:00
Some features of Element may be enabled by flags in the `Labs` section of the settings.
2020-08-16 08:59:05 +00:00
Some of these features are described in [labs.md ](https://github.com/vector-im/element-web/blob/develop/docs/labs.md ).
2019-03-22 14:49:44 +00:00
2019-11-25 04:54:01 +00:00
Caching requirements
====================
2020-07-17 11:18:01 +00:00
Element requires the following URLs not to be cached, when/if you are serving Element from your own webserver:
2021-08-01 15:05:33 +00:00
2019-11-25 04:54:01 +00:00
```
/config.*.json
/i18n
/home
/sites
/index.html
```
2021-09-10 10:18:06 +00:00
We also recommend that you force browsers to re-validate any cached copy of Element on page load by configuring your
webserver to return `Cache-Control: no-cache` for `/` . This ensures the browser will fetch a new version of Element on
2021-09-29 12:14:03 +00:00
the next page load after it's been deployed. Note that this is already configured for you in the nginx config of our
Dockerfile.
2021-09-10 10:18:06 +00:00
2015-07-22 05:45:01 +00:00
Development
===========
2015-10-25 11:56:29 +00:00
2020-08-16 08:59:05 +00:00
Before attempting to develop on Element you **must** read the [developer guide
2020-05-12 11:07:43 +00:00
for `matrix-react-sdk` ](https://github.com/matrix-org/matrix-react-sdk#developer-guide), which
2020-07-17 11:18:01 +00:00
also defines the design, architecture and style for Element too.
2016-07-11 17:25:58 +00:00
2020-03-18 11:18:29 +00:00
Before starting work on a feature, it's best to ensure your plan aligns well
2020-08-16 08:59:05 +00:00
with our vision for Element. Please chat with the team in
2020-08-18 21:18:03 +00:00
[#element-dev:matrix.org ](https://matrix.to/#/#element-dev:matrix.org ) before you
2020-03-18 11:18:29 +00:00
start so we can ensure it's something we'd be willing to merge.
2019-02-10 08:53:38 +00:00
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.
2018-10-11 09:29:28 +00:00
2020-07-17 11:18:01 +00:00
The idea of Element is to be a relatively lightweight "skin" of customisations on
2016-07-11 17:25:58 +00:00
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.
2020-07-17 11:18:01 +00:00
Please note that Element is intended to run correctly without access to the public
2016-07-15 14:57:59 +00:00
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
2020-07-17 11:18:01 +00:00
into Element itself.
2016-07-11 17:25:58 +00:00
2021-08-18 15:39:27 +00:00
CSS hot-reload is available as an opt-in development feature. You can enable it
by defining a `CSS_HOT_RELOAD` environment variable, in a `.env` file in the root
of the repository. See `.env.example` for documentation and an example.
2021-08-01 15:05:33 +00:00
2016-07-11 17:25:58 +00:00
Setting up a dev environment
============================
2020-07-17 11:18:01 +00:00
Much of the functionality in Element is actually in the `matrix-react-sdk` and
2016-06-14 14:12:35 +00:00
`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.
2016-02-23 20:55:37 +00:00
First clone and build `matrix-js-sdk` :
2019-02-10 08:53:38 +00:00
``` bash
git clone https://github.com/matrix-org/matrix-js-sdk.git
pushd matrix-js-sdk
2019-03-12 11:06:57 +00:00
yarn link
yarn install
2019-02-10 08:53:38 +00:00
popd
```
2016-02-23 20:55:37 +00:00
Then similarly with `matrix-react-sdk` :
2019-02-10 08:53:38 +00:00
```bash
git clone https://github.com/matrix-org/matrix-react-sdk.git
pushd matrix-react-sdk
2019-03-12 11:06:57 +00:00
yarn link
yarn link matrix-js-sdk
yarn install
2019-02-10 08:53:38 +00:00
popd
```
2016-02-23 20:55:37 +00:00
2020-07-17 11:18:01 +00:00
Finally, build and start Element itself:
2016-02-23 20:55:37 +00:00
2019-02-10 08:53:38 +00:00
```bash
2020-08-16 08:59:05 +00:00
git clone https://github.com/vector-im/element-web.git
cd element-web
2019-03-12 11:06:57 +00:00
yarn link matrix-js-sdk
yarn link matrix-react-sdk
yarn install
yarn start
2019-02-10 08:53:38 +00:00
```
Wait a few seconds for the initial build to finish; you should see something like:
2021-08-01 15:05:33 +00:00
2019-02-10 08:53:38 +00:00
```
2021-03-23 10:55:11 +00:00
[element-js] < s > [webpack.Progress] 100%
[element-js]
2021-03-22 12:39:26 +00:00
[element-js] ℹ 「wdm」: 1840 modules
[element-js] ℹ 「wdm」: Compiled successfully.
2019-02-10 08:53:38 +00:00
```
2021-08-01 15:05:33 +00:00
2016-02-24 11:36:57 +00:00
Remember, the command will not terminate since it runs the web server
2016-06-14 14:12:35 +00:00
and rebuilds source files when they change. This development server also
disables caching, so do NOT use it in production.
2019-02-10 08:53:38 +00:00
2019-10-06 11:04:20 +00:00
Configure the app by copying `config.sample.json` to `config.json` and
modifying it. See the [configuration docs ](docs/config.md ) for details.
2021-08-01 15:05:33 +00:00
Open < http: / / 127 . 0 . 0 . 1:8080 / > in your browser to see your newly built Element.
2019-02-10 08:53:38 +00:00
2020-05-06 10:32:13 +00:00
**Note**: The build script uses inotify by default on Linux to monitor directories
2020-11-23 07:45:21 +00:00
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` .
2020-04-11 00:09:29 +00:00
2020-11-23 17:35:29 +00:00
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.
2020-11-23 07:45:21 +00:00
To set a new inotify watch and instance limit, execute:
2020-04-11 00:09:29 +00:00
```
2020-11-23 07:45:21 +00:00
sudo sysctl fs.inotify.max_user_watches=131072
sudo sysctl fs.inotify.max_user_instances=512
sudo sysctl -p
2020-04-11 00:09:29 +00:00
```
2020-11-23 07:45:21 +00:00
If you wish, you can make the new limits permanent, by executing:
2020-04-11 00:09:29 +00:00
```
2020-11-23 17:36:20 +00:00
echo fs.inotify.max_user_watches=131072 | sudo tee -a /etc/sysctl.conf
2020-11-23 07:45:21 +00:00
echo fs.inotify.max_user_instances=512 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
2020-04-11 00:09:29 +00:00
```
2020-11-23 07:45:21 +00:00
2019-02-10 08:53:38 +00:00
___
2016-02-23 20:55:37 +00:00
2018-09-17 23:46:13 +00:00
When you make changes to `matrix-react-sdk` or `matrix-js-sdk` they should be
automatically picked up by webpack and built.
2015-10-25 11:56:29 +00:00
2016-08-12 08:59:56 +00:00
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.
2020-07-17 11:18:01 +00:00
You'll need to do this in each new terminal you open before building Element.
2016-08-12 08:59:56 +00:00
2017-07-05 10:45:23 +00:00
Running the tests
-----------------
2017-05-23 13:12:53 +00:00
2017-07-05 10:45:23 +00:00
There are a number of application-level tests in the `tests` directory; these
2021-12-08 12:34:34 +00:00
are designed to run with Jest and JSDOM. To run them
2017-07-05 10:45:23 +00:00
2021-12-08 12:34:34 +00:00
```
yarn test
```
2017-05-24 13:23:34 +00:00
2019-10-10 14:54:52 +00:00
### End-to-End tests
2022-03-07 22:38:23 +00:00
See [matrix-react-sdk ](https://github.com/matrix-org/matrix-react-sdk/#end-to-end-tests ) for how to run the end-to-end tests.
2019-10-10 14:54:52 +00:00
2017-07-05 10:45:23 +00:00
Translations
============
2017-05-23 13:12:53 +00:00
2017-07-05 10:45:23 +00:00
To add a new translation, head to the [translating doc ](docs/translating.md ).
2017-05-23 13:12:53 +00:00
2017-07-05 10:45:23 +00:00
For a developer guide, see the [translating dev doc ](docs/translating-dev.md ).
2020-10-21 12:16:43 +00:00
[<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 )
2017-05-23 13:12:53 +00:00
2016-07-11 17:25:58 +00:00
Triaging issues
===============
2021-09-03 16:30:01 +00:00
Issues are triaged by community members and the Web App Team, following the [triage process ](https://github.com/vector-im/element-meta/wiki/Triage-process ).
2021-08-18 14:40:59 +00:00
2021-09-03 16:30:01 +00:00
We use [issue labels ](https://github.com/vector-im/element-meta/wiki/Issue-labelling ) to sort all incoming issues.