README.md 7.47 KB
Newer Older
1
# Rocket.Chat Desktop App
2

3
4
[![Travis CI Build Status](https://img.shields.io/travis/RocketChat/Rocket.Chat.Electron/master.svg?logo=travis)](https://travis-ci.org/RocketChat/Rocket.Chat.Electron)
[![AppVeyor Build Status](https://img.shields.io/appveyor/ci/RocketChat/rocket-chat-electron/master.svg?logo=appveyor)](https://ci.appveyor.com/project/RocketChat/rocket-chat-electron)
Tasso Evangelista's avatar
Tasso Evangelista committed
5
6
7
8
9
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/3a87141c0a4442809d9a2bff455e3102)](https://www.codacy.com/app/tassoevan/Rocket.Chat.Electron?utm_source=github.com&utm_medium=referral&utm_content=RocketChat/Rocket.Chat.Electron&utm_campaign=Badge_Grade)
[![Project Dependencies](https://david-dm.org/RocketChat/Rocket.Chat.Electron.svg)](https://david-dm.org/RocketChat/Rocket.Chat.Electron)
[![GitHub All Releases](https://img.shields.io/github/downloads/RocketChat/Rocket.Chat.Electron/total.svg)](https://github.com/RocketChat/Rocket.Chat.Electron/releases/latest)
![GitHub](https://img.shields.io/github/license/RocketChat/Rocket.Chat.Electron.svg)

10
11
Desktop application for [Rocket.Chat][] available for macOS, Windows and Linux
using [Electron][].
12

13
![Rocket.Chat Desktop App](https://user-images.githubusercontent.com/2263066/91490997-c0bd0c80-e889-11ea-92c7-2cbcc3aabc98.png)
Alex Brazier's avatar
Alex Brazier committed
14

15
---
Alex Brazier's avatar
Alex Brazier committed
16

17
## Engage with us
18

19
20
21
22
23
24
25
26
27
28
29
30
31
### Share your story
We’d love to hear about [your experience][] and potentially feature it on our
[Blog][].

### Subscribe for Updates
Once a month our marketing team releases an email update with news about product
releases, company related topics, events and use cases. [Sign Up!][]

---

## Download

You can download the latest version from the [Releases][] page.
32

33
[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/rocketchat-desktop)
34

35
## Install
36

37
38
Launch the installer and follow the instructions to install.

39
### Windows Options
40

41
42
On Windows you can run a silent install by adding the `/S` flag. You can also
add the options below:
43
44
45

- `/S` - Silent install
- `/allusers` - Install for all users (requires admin)
46
47
- `/currentuser` - Install only the for current user (default)
- `/disableAutoUpdates` - Disable automatic updates
48

49
## Development
50

51
### Quick start
52

Alex Brazier's avatar
Alex Brazier committed
53
Prerequisites:
54

55
56
57
58
- [Git](http://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Node.js](https://nodejs.org)
- [node-gyp](https://github.com/nodejs/node-gyp#installation)
- [Yarn](http://yarnpkg.com/) is recommended instead of npm.
Alex Brazier's avatar
Alex Brazier committed
59
60
61
62
63
64

Now just clone and start the app:

```sh
git clone https://github.com/RocketChat/Rocket.Chat.Electron.git
cd Rocket.Chat.Electron
Alex Brazier's avatar
Alex Brazier committed
65
66
yarn
yarn start
Jakub Szwacz's avatar
Jakub Szwacz committed
67
```
68

69
### Structure of the project
Jakub Szwacz's avatar
Jakub Szwacz committed
70

71
72
The source is located in the `src` folder. Everything in this folder will be
built automatically when running the app with `yarn start`.
Jakub Szwacz's avatar
Jakub Szwacz committed
73

74
75
76
The build process compiles all stuff from the `src` folder and puts it into the
`app` folder, so after the build has finished, your `app` folder contains the
full, runnable application.
77

78
### TypeScript
Jakub Szwacz's avatar
Jakub Szwacz committed
79

80
81
Following the [ongoing changes in Rocket.Chat codebase][], the app was
rewritten in TypeScript 4 to address issues regarding maintainability.
Jakub Szwacz's avatar
Jakub Szwacz committed
82

83
### The build pipeline
Jakub Szwacz's avatar
Jakub Szwacz committed
84

Guilherme Gazzo's avatar
Guilherme Gazzo committed
85
86
The build process is founded upon [rollup][] bundler. There are three entry files
for your code:
Jakub Szwacz's avatar
Jakub Szwacz committed
87

Guilherme Gazzo's avatar
Guilherme Gazzo committed
88
- `src/main.ts`, the script running at the main Electron process, orchestrating
89
  the whole application;
Jakub Szwacz's avatar
Jakub Szwacz committed
90

Guilherme Gazzo's avatar
Guilherme Gazzo committed
91
- `src/rootWindow.ts`, the script that renders the UI of the *root window*, the
92
  app's main window;
93

94
95
- and `src/preload.ts`, which runs in a privileged mode to connect the app and
  the webviews rendering Rocket.Chat's web client.
Jakub Szwacz's avatar
Jakub Szwacz committed
96

97
#### Adding Node.js modules
Alex Brazier's avatar
Alex Brazier committed
98

99
100
101
Remember to respect the split between `dependencies` and `devDependencies` in
`package.json` file. Only modules listed in `dependencies` will be included into
distributable app.
Jakub Szwacz's avatar
Jakub Szwacz committed
102

103
### Troubleshooting
104

105
#### node-gyp
106

107
Follow the installation instruction on [node-gyp readme][].
108

109
#### Ubuntu
110
111
112

You will need to install the following packages:

113
114
115
116
117
```sh
build-essential
libevas-dev
libxss-dev
```
118

119
#### Fedora
120
121
122

You will need to install the following packages:

Aaron Ogle's avatar
Aaron Ogle committed
123
124
125
126
127
```sh
libX11
libXScrnSaver-devel
gcc-c++
```
128

129
#### Windows 7
130

131
132
On Windows 7 you may have to follow option 2 of the [node-gyp install guide]
and install Visual Studio.
133

134
### Testing
135

136
#### Unit tests
Jakub Szwacz's avatar
Jakub Szwacz committed
137

138
```sh
Alex Brazier's avatar
Alex Brazier committed
139
yarn test
Jakub Szwacz's avatar
Jakub Szwacz committed
140
```
Jakub Szwacz's avatar
Jakub Szwacz committed
141

142
We use [Jest][] testing framework with the [Jest electron runner][]. It searches
143
144
for all files in `src` directory that match the glob pattern
`*.(spec|test).{js,ts,tsx}`.
145

146
### Making a release
Jakub Szwacz's avatar
Jakub Szwacz committed
147

Jakub Szwacz's avatar
Jakub Szwacz committed
148
To package your app into an installer use command:
Jakub Szwacz's avatar
Jakub Szwacz committed
149

150
```sh
Alex Brazier's avatar
Alex Brazier committed
151
yarn release
Rodrigo Nascimento's avatar
Rodrigo Nascimento committed
152
153
```

154
155
It will start the packaging process for operating system you are running this
command on. Ready for distribution file will be outputted to `dist` directory.
156

157
158
All packaging actions are handled by [electron-builder][]. It has a lot of
[customization options][].
159

160
## Default servers
161

162
The `servers.json` file will define what servers the client will connect to and
163
will populate the server list in the sidebar. It contains a list of default
164
165
servers which will be added the first time the user runs the app (or when all
servers are removed from the list).
Gabriel Delavald's avatar
Gabriel Delavald committed
166
The file syntax is as follows:
167
168

```json
169
{
170
171
  "Demo Rocket Chat": "https://demo.rocket.chat",
  "Open Rocket Chat": "https://open.rocket.chat"
172
173
174
}
```

175
### Pre-Release Configuration
176

177
178
179
180
181
You can bundle a `servers.json` with the install package, the file should be
located in the root of the project application (same level as the
`package.json`). If the file is found, the initial "Connect to server" screen
will be skipped and it will attempt to connect to the first server in the array
that has been defined and drop the user right at the login screen. Note that the
182
`servers.json` will only be checked if no other servers have already been added,
183
184
even if you uninstall the app without removing older preferences, it will not be
triggered again.
185

186
### Post-Install Configuration
Gabriel Delavald's avatar
Gabriel Delavald committed
187

188
189
190
If you can't (or don't want to) bundle the file inside the app, you can create a
`servers.json` in the user preferences folder which will overwrite the packaged
one. The file should be located in the `%APPDATA%/Rocket.Chat/` folder or the
191
installation folder in case of an installation for all users (Windows only).
Gabriel Delavald's avatar
Gabriel Delavald committed
192

193
For Windows, the full paths are:
194

195
196
- `~\Users\<username>\AppData\Roaming\Rocket.Chat\`
- `~\Program Files\Rocket.Chat\Resources\`
197

198
On macOS, the full paths are:
199

200
201
- `~/Users/<username>/Library/Application Support/Rocket.Chat/`
- `~/Applications/Rocket.Chat.app/Contents/Resources/`
202

203
On Linux, the full paths are:
Alex Brazier's avatar
Alex Brazier committed
204

205
206
- `/home/<username>/.config/Rocket.Chat/`
- `/opt/Rocket.Chat/resources/`
Gabriel Engel's avatar
Gabriel Engel committed
207

208
## License
Jakub Szwacz's avatar
Jakub Szwacz committed
209

210
Released under the MIT license.
211

212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
[Rocket.Chat]: https://rocket.chat

[Electron]: https://electronjs.org/

[your experience]: https://survey.zohopublic.com/zs/e4BUFG

[Blog]: https://rocket.chat/case-studies/?utm_source=github&utm_medium=readme&utm_campaign=community

[Sign Up!]: https://rocket.chat/newsletter/?utm_source=github&utm_medium=readme&utm_campaign=community

[Releases]: https://github.com/RocketChat/Rocket.Chat.Electron/releases/latest

[ongoing changes in Rocket.Chat codebase]: https://forums.rocket.chat/t/moving-away-from-meteor-and-beyond/3270

[rollup]: https://github.com/rollup/rollup

[node-gyp readme]: https://github.com/nodejs/node-gyp#installation
Júlia Grala's avatar
Júlia Grala committed
229

230
[Jest]: https://jestjs.io/
Júlia Grala's avatar
Júlia Grala committed
231

232
233
234
235
236
237
238
[Jest electron runner]: https://github.com/facebook-atom/jest-electron-runner

[electron-builder]: https://github.com/electron-userland/electron-builder

[customization options]: https://github.com/electron-userland/electron-builder/wiki/Options

[node-gyp install guide]: https://github.com/nodejs/node-gyp#installation