@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Notifications User Guide: Setup and Configuration
2@group config
3
4Guide to setting up notifications.
5
6Overview
7========
8
9By default, Phorge delivers information about events (like users creating
10tasks or commenting on code reviews) through email and in-application
11notifications.
12
13Phorge can also be configured to deliver notifications in real time, by
14popping up a message in any open browser windows if something has happened or
15an object has been updated.
16
17To enable real-time notifications:
18
19 - Configure and start the notification server, as described below.
20 - Adjust `notification.servers` to point at it.
21
22This document describes the process in detail.
23
24
25Supported Browsers
26==================
27
28Notifications are supported for browsers which support WebSockets. This covers
29most modern browsers (Chrome, Firefox, Safari, Edge) and many mobile browsers.
30
31
32Installing Node and Modules
33===========================
34
35The notification server uses Node.js, so you'll need to install it first.
36
37To install Node.js, follow the instructions on
38[[ https://nodejs.org | nodejs.org ]].
39
40You will also need to install the dependencies for Node. This needs to be
41installed into the notification server directory:
42
43 phorge/ $ cd support/aphlict/server/
44 phorge/support/aphlict/server/ $ npm install
45
46Once Node.js and its dependencies are installed, you're ready to start the
47server.
48
49
50Running the Aphlict Server
51==========================
52
53After installing Node.js, you can control the notification server with the
54`bin/aphlict` command. To start the server:
55
56 phorge/ $ bin/aphlict start
57
58By default, the server must be able to listen on port `22280`. If you're using
59a host firewall (like a security group in EC2), make sure traffic can reach the
60server.
61
62The server configuration is controlled by a configuration file, which is
63separate from Phorge's configuration settings. The default file can
64be found at `phorge/conf/aphlict/aphlict.default.json`.
65
66To make adjustments to the default configuration, either copy this file to
67create `aphlict.custom.json` in the same directory (this file will be used if
68it exists) or specify a configuration file explicitly with the `--config` flag:
69
70 phorge/ $ bin/aphlict start --config path/to/config.json
71
72The configuration file has these settings:
73
74 - `servers`: //Required list.// A list of servers to start.
75 - `logs`: //Optional list.// A list of logs to write to.
76 - `cluster`: //Optional list.// A list of cluster peers. This is an advanced
77 feature.
78 - `pidfile`: //Required string.// Path to a PID file.
79 - `memory.hint`: //Optional int.// Suggestion to `node` about how much
80 memory to use, via `--max-old-stack-size`. In most cases, this can be
81 left unspecified.
82
83Each server in the `servers` list should be an object with these keys:
84
85 - `type`: //Required string.// The type of server to start. Options are
86 `admin` or `client`. Normally, you should run one of each.
87 - `port`: //Required int.// The port this server should listen on.
88 - `listen`: //Optional string.// Which interface to bind to. By default,
89 the `admin` server is bound to `127.0.0.1` (so only other services on the
90 local machine can connect to it), while the `client` server is bound
91 to `0.0.0.0` (so any client can connect).
92 - `ssl.key`: //Optional string.// If you want to use SSL on this port,
93 the path to an SSL key.
94 - `ssl.cert`: //Optional string.// If you want to use SSL on this port,
95 the path to an SSL certificate.
96 - `ssl.chain`: //Optional string.// If you have configured SSL on this
97 port, an optional path to a certificate chain file.
98
99Each log in the `logs` list should be an object with these keys:
100
101 - `path`: //Required string.// Path to the log file.
102
103Each peer in the `cluster` list should be an object with these keys:
104
105 - `host`: //Required string.// The peer host address.
106 - `port`: //Required int.// The peer port.
107 - `protocol`: //Required string.// The protocol to connect with, one of
108 `"http"` or `"https"`.
109
110Cluster configuration is an advanced topic and can be omitted for most
111installs. For more information on how to configure a cluster, see
112@{article:Clustering Introduction} and @{article:Cluster: Notifications}.
113
114The defaults are appropriate for simple cases, but you may need to adjust them
115if you are running a more complex configuration.
116
117Configuring Phorge
118=======================
119
120After starting the server, configure Phorge to connect to it by adjusting
121`notification.servers`. This configuration option should have a list of servers
122that Phorge should interact with.
123
124Normally, you'll list one client server and one admin server, like this:
125
126```lang=json
127[
128 {
129 "type": "client",
130 "host": "phorge.mycompany.com",
131 "port": 22280,
132 "protocol": "https"
133 },
134 {
135 "type": "admin",
136 "host": "127.0.0.1",
137 "port": 22281,
138 "protocol": "http"
139 }
140]
141```
142
143This definition defines which services the user's browser will attempt to
144connect to. Most of the time, it will be very similar to the services defined
145in the Aphlict configuration. However, if you are sending traffic through a
146load balancer or terminating SSL somewhere before traffic reaches Aphlict,
147the services the browser connects to may need to have different hosts, ports
148or protocols than the underlying server listens on.
149
150
151Verifying Server Status
152=======================
153
154After configuring `notification.servers`, navigate to
155{nav Config > Services > Notification Servers} to verify that things are
156operational.
157
158
159Troubleshooting
160===============
161
162You can run `aphlict` in the foreground to get output to your console:
163
164 phorge/ $ ./bin/aphlict debug
165
166Because the notification server uses WebSockets, your browser error console
167may also have information that is useful in figuring out what's wrong.
168
169The server also generates a log, by default in `/var/log/aphlict.log`. You can
170change this location by adjusting configuration. The log may contain
171information that is useful in resolving issues.
172
173
174SSL and HTTPS
175=============
176
177If you serve Phorge over HTTPS, you must also serve websockets over HTTPS.
178Browsers will refuse to connect to `ws://` websockets from HTTPS pages.
179
180If a client connects to Phorge over HTTPS, Phorge will automatically
181select an appropriate HTTPS service from `notification.servers` and instruct
182the browser to open a websocket connection with `wss://`.
183
184The simplest way to do this is configure Aphlict with an SSL key and
185certificate and let it terminate SSL directly.
186
187If you prefer not to do this, two other options are:
188
189 - run the websocket through a websocket-capable loadbalancer and terminate
190 SSL there; or
191 - run the websocket through `nginx` over the same socket as the rest of
192 your web traffic.
193
194See the next sections for more detail.
195
196
197Terminating SSL with a Load Balancer
198====================================
199
200If you want to terminate SSL in front of the notification server with a
201traditional load balancer or a similar device, do this:
202
203 - Point `notification.servers` at your load balancer or reverse proxy,
204 specifying that the protocol is `https`.
205 - On the load balancer or proxy, terminate SSL and forward traffic to the
206 Aphlict server.
207 - In the Aphlict configuration, listen on the target port with `http`.
208
209
210Terminating SSL with Nginx
211==========================
212
213If you use `nginx`, you can send websocket traffic to the same port as normal
214HTTP traffic and have `nginx` proxy it selectively based on the request path.
215
216This requires `nginx` 1.3 or greater. See the `nginx` documentation for
217details:
218
219> https://www.f5.com/company/blog/nginx/websocket-nginx
220
221This is very complex, but allows you to support notifications without opening
222additional ports.
223
224An example `nginx` configuration might look something like this:
225
226```lang=nginx, name=/etc/nginx/conf.d/connection_upgrade.conf
227map $http_upgrade $connection_upgrade {
228 default upgrade;
229 '' close;
230}
231```
232
233```lang=nginx, name=/etc/nginx/conf.d/websocket_pool.conf
234upstream websocket_pool {
235 ip_hash;
236 server 127.0.0.1:22280;
237}
238```
239
240```lang=nginx, name=/etc/nginx/sites-enabled/phorge.example.com.conf
241server {
242 server_name phorge.example.com;
243 root /path/to/phorge/webroot;
244
245 // ...
246
247 location = /ws/ {
248 proxy_pass http://websocket_pool;
249 proxy_http_version 1.1;
250 proxy_set_header Upgrade $http_upgrade;
251 proxy_set_header Connection "upgrade";
252 proxy_read_timeout 999999999;
253 }
254}
255```
256
257With this approach, you should make these additional adjustments:
258
259**Phorge Configuration**: The entry in `notification.servers` with type
260`"client"` should have these adjustments made:
261
262 - Set `host` to the Phorge host.
263 - Set `port` to the standard HTTPS port (usually `443`).
264 - Set `protocol` to `"https"`.
265 - Set `path` to `/ws/`, so it matches the special `location` in your
266 `nginx` config.
267
268You do not need to adjust the `"admin"` server.
269
270**Aphlict**: Your Aphlict configuration should make these adjustments to
271the `"client"` server:
272
273 - Do not specify any `ssl.*` options: `nginx` will send plain HTTP traffic
274 to Aphlict.
275 - Optionally, you can `listen` on `127.0.0.1` instead of `0.0.0.0`, because
276 the server will no longer receive external traffic.