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