README.md 14 KB
Newer Older
1 2
Riot
====
3

Julien Jerphanion's avatar
Julien Jerphanion committed
4
Riot (formerly known as Vector) is a Matrix web client built using the [Matrix React SDK](https://github.com/matrix-org/matrix-react-sdk).
Brennan Novak's avatar
Brennan Novak committed
5

6
Riot is officially supported on the web in modern versions of Chrome, Firefox, and Safari. Other browsers may work, however
Travis Ralston's avatar
Travis Ralston committed
7 8
official support is not provided. For accessing Riot on an Android or iOS device, check out [riot-android](https://github.com/vector-im/riot-android)
and [riot-ios](https://github.com/vector-im/riot-ios) - riot-web does not support mobile devices.
9

David Baker's avatar
David Baker committed
10
Getting Started
David Baker's avatar
David Baker committed
11
===============
12

Julien Jerphanion's avatar
Julien Jerphanion committed
13 14 15
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
for those who like living dangerously.
16

17 18
To host your own copy of Riot, the quickest bet is to use a pre-built
released version of Riot:
David Baker's avatar
David Baker committed
19

20
1. Download the latest version from https://github.com/vector-im/riot-web/releases
David Baker's avatar
David Baker committed
21
1. Untar the tarball on your web server
Julien Jerphanion's avatar
Julien Jerphanion committed
22
1. Move (or symlink) the `riot-x.x.x` directory to an appropriate name
David Baker's avatar
David Baker committed
23
1. If desired, copy `config.sample.json` to `config.json` and edit it
24
   as desired. See the [configuration docs](docs/config.md) for details.
25
1. Enter the URL into your browser and log into Riot!
David Baker's avatar
David Baker committed
26

27
Releases are signed using gpg and the OpenPGP standard, and can be checked against the public key located
28
at https://packages.riot.im/riot-release-key.asc.
29

Richard van der Hoff's avatar
Richard van der Hoff committed
30 31 32 33
Note that Chrome does not allow microphone or webcam access for sites served
over http (except localhost), so for working VoIP you will need to serve Riot
over https.

34 35
To install Riot as a desktop application, see [Running as a desktop
app](#running-as-a-desktop-app) below.
36

37 38 39
Important Security Note
=======================

40 41 42 43 44
We do not recommend running Riot 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
malicious user generated content from a Matrix API which then had trusted
access to Riot (or other apps) due to sharing the same domain.
45

46 47
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
48
https://github.com/vector-im/riot-web/issues/1977 for more details.
49

50 51 52 53 54
The same applies for end-to-end encrypted content, but since this is decrypted
on the client, Riot needs a way to supply the decrypted content from a separate
origin to the one Riot is hosted on. This currently done with a 'cross origin
renderer' which is a small piece of javascript hosted on a different domain.
To avoid all Riot installs needing one of these to be set up, riot.im hosts
55 56 57
one on usercontent.riot.im which is used by default.
https://github.com/vector-im/riot-web/issues/6173 tracks progress on replacing
this with something better.
58

David Baker's avatar
David Baker committed
59 60 61
Building From Source
====================

62
Riot is a modular webapp built with modern ES6 and uses a Node.js build system.
63
Ensure you have the latest LTS version of Node.js installed.
64

65 66 67 68 69
Using `yarn` instead of `npm` is recommended. Please see the Yarn [install
guide](https://yarnpkg.com/docs/install/) if you do not have it already.

1. Install or update `node.js` so that your `node` is at least v10.x.
1. Install `yarn` if not present already.
70 71
1. Clone the repo: `git clone https://github.com/vector-im/riot-web.git`.
1. Switch to the riot-web directory: `cd riot-web`.
72
1. Install the prerequisites: `yarn install`.
73 74 75
1. If you're using the `develop` branch then it is recommended to set up a proper
   development environment ("Setting up a dev environment" below) however one can
   install the develop versions of the dependencies instead:
Julien Jerphanion's avatar
Julien Jerphanion committed
76
   ```bash
77
   scripts/fetch-develop.deps.sh
78
   ```
79
   Whenever you git pull on `riot-web` you will also probably need to force an update
80
   to these dependencies - the simplest way is to re-run the script, but you can also
81
   manually update and rebuild them:
Julien Jerphanion's avatar
Julien Jerphanion committed
82
   ```bash
83 84
   cd matrix-js-sdk
   git pull
85
   yarn install # re-run to pull in any new dependencies
86 87
   cd ../matrix-react-sdk
   git pull
88
   yarn install
89
   ```
90
   Or just use https://riot.im/develop - the continuous integration release of the
91 92
   develop branch. (Note that we don't reference the develop versions in git directly
   due to https://github.com/npm/npm/issues/3055.)
93
1. Configure the app by copying `config.sample.json` to `config.json` and
94
   modifying it. See the [configuration docs](docs/config.md) for details.
95
1. `yarn dist` to build a tarball to deploy. Untaring this file will give
David Baker's avatar
David Baker committed
96 97
   a version-specific directory containing all the files that need to go on your
   web server.
98

99
Note that `yarn dist` is not supported on Windows, so Windows users can run `yarn build`,
Julien Jerphanion's avatar
Julien Jerphanion committed
100 101 102
which will build all the necessary files into the `webapp` directory. The version of Riot
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.
David Baker's avatar
David Baker committed
103

104 105 106
Running as a Desktop app
========================

J. Ryan Stinnett's avatar
J. Ryan Stinnett committed
107
Riot can also be run as a desktop app, wrapped in Electron. You can download a
108 109
pre-built version from https://riot.im/download/desktop/ or, if you prefer,
build it yourself.
110

111
To build it yourself, follow the instructions below.
112

113
1. Follow the instructions in 'Building From Source' above, but run
114
   `yarn build` instead of `yarn dist` (since we don't need the tarball).
J. Ryan Stinnett's avatar
J. Ryan Stinnett committed
115
2. Install Electron and run it:
116

Julien Jerphanion's avatar
Julien Jerphanion committed
117
   ```bash
118
   yarn electron
119
   ```
120

J. Ryan Stinnett's avatar
J. Ryan Stinnett committed
121
To build packages, use `electron-builder`. This is configured to output:
Julien Jerphanion's avatar
Julien Jerphanion committed
122 123 124
 * `dmg` + `zip` for macOS
 * `exe` + `nupkg` for Windows
 * `deb` for Linux
125 126 127 128 129
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.
130

131
The only platform that can build packages for all three platforms is macOS:
Julien Jerphanion's avatar
Julien Jerphanion committed
132
```bash
133
brew install mono
134 135
yarn install
yarn build:electron
136 137
```

J. Ryan Stinnett's avatar
J. Ryan Stinnett committed
138 139
For other packages, use `electron-builder` manually. For example, to build a
package for 64 bit Linux:
140 141 142

 1. Follow the instructions in 'Building From Source' above
 2. `node_modules/.bin/build -l --x64`
143

J. Ryan Stinnett's avatar
J. Ryan Stinnett committed
144
All Electron packages go into `electron_app/dist/`
145

J. Ryan Stinnett's avatar
J. Ryan Stinnett committed
146
Many thanks to @aviraldg for the initial work on the Electron integration.
147 148 149

Other options for running as a desktop app:
 * @asdf:matrix.org points out that you can use nativefier and it just works(tm)
150

Julien Jerphanion's avatar
Julien Jerphanion committed
151
```bash
152
yarn global add nativefier
153 154
nativefier https://riot.im/app/
```
155

156 157
The [configuration docs](docs/config.md#desktop-app-configuration) show how to
override the desktop app's default settings if desired.
Michael Telatynski's avatar
Michael Telatynski committed
158

Travis Ralston's avatar
Travis Ralston committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
Running from Docker
===================

The Docker image can be used to serve riot-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
``` 

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
would be:
```bash
docker run -p 80:80 -v /etc/riot-web/config.json:/app/config.json vectorim/riot-web
```

To build the image yourself:
```bash
git clone https://github.com/vector-im/riot-web.git riot-web
cd riot-web
git checkout master
docker build -t vectorim/riot-web .
```

If you're building a custom branch, or want to use the develop branch, check out the appropriate
riot-web branch and then run:
```bash
docker build -t vectorim/riot-web:develop \
Travis Ralston's avatar
Travis Ralston committed
187
    --build-arg USE_CUSTOM_SDKS=true \
Travis Ralston's avatar
Travis Ralston committed
188 189 190 191 192 193 194
    --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" \
    .
```

195 196 197 198 199 200
config.json
===========

Riot supports a variety of settings to configure default servers, behaviour, themes, etc.
See the [configuration docs](docs/config.md) for more details.

201 202 203 204 205 206
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).

David Baker's avatar
David Baker committed
207 208
Development
===========
209

Julien Jerphanion's avatar
Julien Jerphanion committed
210 211
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
212
also defines the design, architecture and style for Riot too.
213

Julien Jerphanion's avatar
Julien Jerphanion committed
214 215 216
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.
Matthew Hodgson's avatar
Matthew Hodgson committed
217

218
The idea of Riot is to be a relatively lightweight "skin" of customisations on
219 220 221 222
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.

223
After creating a new component you must run `yarn reskindex` to regenerate
224
the `component-index.js` for the app (used in future for skinning).
225

226
Please note that Riot is intended to run correctly without access to the public
227 228
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
229
into Riot itself.
230 231 232 233

Setting up a dev environment
============================

234
Much of the functionality in Riot is actually in the `matrix-react-sdk` and
David Baker's avatar
David Baker committed
235 236 237
`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.
238 239 240

First clone and build `matrix-js-sdk`:

Julien Jerphanion's avatar
Julien Jerphanion committed
241 242 243 244
``` bash
git clone https://github.com/matrix-org/matrix-js-sdk.git
pushd matrix-js-sdk
git checkout develop
245 246
yarn link
yarn install
Julien Jerphanion's avatar
Julien Jerphanion committed
247 248
popd
```
249 250 251

Then similarly with `matrix-react-sdk`:

Julien Jerphanion's avatar
Julien Jerphanion committed
252 253 254 255
```bash
git clone https://github.com/matrix-org/matrix-react-sdk.git
pushd matrix-react-sdk
git checkout develop
256 257 258
yarn link
yarn link matrix-js-sdk
yarn install
Julien Jerphanion's avatar
Julien Jerphanion committed
259 260
popd
```
261

262
Finally, build and start Riot itself:
263

Julien Jerphanion's avatar
Julien Jerphanion committed
264 265 266 267
```bash
git clone https://github.com/vector-im/riot-web.git
cd riot-web
git checkout develop
268 269 270 271
yarn link matrix-js-sdk
yarn link matrix-react-sdk
yarn install
yarn start
Julien Jerphanion's avatar
Julien Jerphanion committed
272 273 274 275 276 277 278 279 280 281 282 283 284 285
```

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
```
David Baker's avatar
David Baker committed
286
   Remember, the command will not terminate since it runs the web server
David Baker's avatar
David Baker committed
287 288
   and rebuilds source files when they change. This development server also
   disables caching, so do NOT use it in production.
Julien Jerphanion's avatar
Julien Jerphanion committed
289 290 291 292

Open http://127.0.0.1:8080/ in your browser to see your newly built Riot.

___
293

294 295
When you make changes to `matrix-react-sdk` or `matrix-js-sdk` they should be
automatically picked up by webpack and built.
296

297
If you add or remove any components from the Riot skin, you will need to rebuild
298
the skin's index by running, `yarn reskindex`.
299

300 301
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.
302
You'll need to do this in each new terminal you open before building Riot.
303

304 305
Running the tests
-----------------
306

307 308 309 310 311 312 313
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
314
* `yarn test`
315 316

The above will run the tests under Chrome in a `headless` mode.
317

318
You can also tell karma to run the tests in a loop (every time the source
319
changes), in an instance of Chrome on your desktop, with `yarn
320 321
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.
322

323 324
Translations
============
325

326
To add a new translation, head to the [translating doc](docs/translating.md).
327

328 329 330
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)
331

332 333 334
Triaging issues
===============

Matthew Hodgson's avatar
Matthew Hodgson committed
335
Issues will be triaged by the core team using the below set of tags.
336

Matthew Hodgson's avatar
Matthew Hodgson committed
337 338 339 340
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?
Tom Lant's avatar
Tom Lant committed
341

Matthew Hodgson's avatar
Matthew Hodgson committed
342 343 344
priority: **compulsory**

* P1: top priority - i.e. pool of stuff which we should be working on next
Tom Lant's avatar
Tom Lant committed
345 346
* P2: still need to fix, but lower than P1
* P3: non-urgent
Matthew Hodgson's avatar
Matthew Hodgson committed
347
* P4: interesting idea - bluesky some day
Tom Lant's avatar
Tom Lant committed
348
* P5: recorded for posterity/to avoid duplicates. No intention to resolves right now.
349

Matthew Hodgson's avatar
Matthew Hodgson committed
350
bug or feature: **compulsory**
351

Tom Lant's avatar
Tom Lant committed
352 353 354
* bug
* feature

Matthew Hodgson's avatar
Matthew Hodgson committed
355
bug severity: **compulsory, if bug**
356

Tom Lant's avatar
Tom Lant committed
357 358 359
* critical - whole app doesn't work
* major - entire feature doesn't work
* minor - partially broken feature (but still usable)
Matthew Hodgson's avatar
Matthew Hodgson committed
360 361 362 363 364
* 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.
365

Matthew Hodgson's avatar
Matthew Hodgson committed
366
additional categories (self-explanatory):
367

Tom Lant's avatar
Tom Lant committed
368 369 370
* release blocker
* ui/ux (think of this as cosmetic)
* network (specific to network conditions)
Matthew Hodgson's avatar
Matthew Hodgson committed
371 372 373 374 375 376 377 378 379 380 381 382
* 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