Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/notifications.diviner
@title Notifications User Guide: Setup and Configuration | @title Notifications User Guide: Setup and Configuration | ||||
@group config | @group config | ||||
Guide to setting up notifications. | Guide to setting up notifications. | ||||
Overview | Overview | ||||
======== | ======== | ||||
By default, Phabricator delivers information about events (like users creating | By default, Phorge delivers information about events (like users creating | ||||
tasks or commenting on code reviews) through email and in-application | tasks or commenting on code reviews) through email and in-application | ||||
notifications. | notifications. | ||||
Phabricator can also be configured to deliver notifications in real time, by | Phorge can also be configured to deliver notifications in real time, by | ||||
popping up a message in any open browser windows if something has happened or | popping up a message in any open browser windows if something has happened or | ||||
an object has been updated. | an object has been updated. | ||||
To enable real-time notifications: | To enable real-time notifications: | ||||
- Configure and start the notification server, as described below. | - Configure and start the notification server, as described below. | ||||
- Adjust `notification.servers` to point at it. | - Adjust `notification.servers` to point at it. | ||||
Show All 17 Lines | |||||
The notification server uses Node.js, so you'll need to install it first. | The notification server uses Node.js, so you'll need to install it first. | ||||
To install Node.js, follow the instructions on | To install Node.js, follow the instructions on | ||||
[[ http://nodejs.org | nodejs.org ]]. | [[ http://nodejs.org | nodejs.org ]]. | ||||
You will also need to install the `ws` module for Node. This needs to be | You will also need to install the `ws` module for Node. This needs to be | ||||
installed into the notification server directory: | installed into the notification server directory: | ||||
phabricator/ $ cd support/aphlict/server/ | phorge/ $ cd support/aphlict/server/ | ||||
phabricator/support/aphlict/server/ $ npm install ws | phorge/support/aphlict/server/ $ npm install ws | ||||
Once Node.js and the `ws` module are installed, you're ready to start the | Once Node.js and the `ws` module are installed, you're ready to start the | ||||
server. | server. | ||||
Running the Aphlict Server | Running the Aphlict Server | ||||
========================== | ========================== | ||||
After installing Node.js, you can control the notification server with the | After installing Node.js, you can control the notification server with the | ||||
`bin/aphlict` command. To start the server: | `bin/aphlict` command. To start the server: | ||||
phabricator/ $ bin/aphlict start | phorge/ $ bin/aphlict start | ||||
By default, the server must be able to listen on port `22280`. If you're using | By default, the server must be able to listen on port `22280`. If you're using | ||||
a host firewall (like a security group in EC2), make sure traffic can reach the | a host firewall (like a security group in EC2), make sure traffic can reach the | ||||
server. | server. | ||||
The server configuration is controlled by a configuration file, which is | The server configuration is controlled by a configuration file, which is | ||||
separate from Phabricator's configuration settings. The default file can | separate from Phorge's configuration settings. The default file can | ||||
be found at `phabricator/conf/aphlict/aphlict.default.json`. | be found at `phorge/conf/aphlict/aphlict.default.json`. | ||||
To make adjustments to the default configuration, either copy this file to | To make adjustments to the default configuration, either copy this file to | ||||
create `aphlict.custom.json` in the same directory (this file will be used if | create `aphlict.custom.json` in the same directory (this file will be used if | ||||
it exists) or specify a configuration file explicitly with the `--config` flag: | it exists) or specify a configuration file explicitly with the `--config` flag: | ||||
phabricator/ $ bin/aphlict start --config path/to/config.json | phorge/ $ bin/aphlict start --config path/to/config.json | ||||
The configuration file has these settings: | The configuration file has these settings: | ||||
- `servers`: //Required list.// A list of servers to start. | - `servers`: //Required list.// A list of servers to start. | ||||
- `logs`: //Optional list.// A list of logs to write to. | - `logs`: //Optional list.// A list of logs to write to. | ||||
- `cluster`: //Optional list.// A list of cluster peers. This is an advanced | - `cluster`: //Optional list.// A list of cluster peers. This is an advanced | ||||
feature. | feature. | ||||
- `pidfile`: //Required string.// Path to a PID file. | - `pidfile`: //Required string.// Path to a PID file. | ||||
Show All 30 Lines | |||||
Cluster configuration is an advanced topic and can be omitted for most | Cluster configuration is an advanced topic and can be omitted for most | ||||
installs. For more information on how to configure a cluster, see | installs. For more information on how to configure a cluster, see | ||||
@{article:Clustering Introduction} and @{article:Cluster: Notifications}. | @{article:Clustering Introduction} and @{article:Cluster: Notifications}. | ||||
The defaults are appropriate for simple cases, but you may need to adjust them | The defaults are appropriate for simple cases, but you may need to adjust them | ||||
if you are running a more complex configuration. | if you are running a more complex configuration. | ||||
Configuring Phabricator | Configuring Phorge | ||||
======================= | ======================= | ||||
After starting the server, configure Phabricator to connect to it by adjusting | After starting the server, configure Phorge to connect to it by adjusting | ||||
`notification.servers`. This configuration option should have a list of servers | `notification.servers`. This configuration option should have a list of servers | ||||
that Phabricator should interact with. | that Phorge should interact with. | ||||
Normally, you'll list one client server and one admin server, like this: | Normally, you'll list one client server and one admin server, like this: | ||||
```lang=json | ```lang=json | ||||
[ | [ | ||||
{ | { | ||||
"type": "client", | "type": "client", | ||||
"host": "phabricator.mycompany.com", | "host": "phorge.mycompany.com", | ||||
"port": 22280, | "port": 22280, | ||||
"protocol": "https" | "protocol": "https" | ||||
}, | }, | ||||
{ | { | ||||
"type": "admin", | "type": "admin", | ||||
"host": "127.0.0.1", | "host": "127.0.0.1", | ||||
"port": 22281, | "port": 22281, | ||||
"protocol": "http" | "protocol": "http" | ||||
Show All 17 Lines | |||||
operational. | operational. | ||||
Troubleshooting | Troubleshooting | ||||
=============== | =============== | ||||
You can run `aphlict` in the foreground to get output to your console: | You can run `aphlict` in the foreground to get output to your console: | ||||
phabricator/ $ ./bin/aphlict debug | phorge/ $ ./bin/aphlict debug | ||||
Because the notification server uses WebSockets, your browser error console | Because the notification server uses WebSockets, your browser error console | ||||
may also have information that is useful in figuring out what's wrong. | may also have information that is useful in figuring out what's wrong. | ||||
The server also generates a log, by default in `/var/log/aphlict.log`. You can | The server also generates a log, by default in `/var/log/aphlict.log`. You can | ||||
change this location by adjusting configuration. The log may contain | change this location by adjusting configuration. The log may contain | ||||
information that is useful in resolving issues. | information that is useful in resolving issues. | ||||
SSL and HTTPS | SSL and HTTPS | ||||
============= | ============= | ||||
If you serve Phabricator over HTTPS, you must also serve websockets over HTTPS. | If you serve Phorge over HTTPS, you must also serve websockets over HTTPS. | ||||
Browsers will refuse to connect to `ws://` websockets from HTTPS pages. | Browsers will refuse to connect to `ws://` websockets from HTTPS pages. | ||||
If a client connects to Phabricator over HTTPS, Phabricator will automatically | If a client connects to Phorge over HTTPS, Phorge will automatically | ||||
select an appropriate HTTPS service from `notification.servers` and instruct | select an appropriate HTTPS service from `notification.servers` and instruct | ||||
the browser to open a websocket connection with `wss://`. | the browser to open a websocket connection with `wss://`. | ||||
The simplest way to do this is configure Aphlict with an SSL key and | The simplest way to do this is configure Aphlict with an SSL key and | ||||
certificate and let it terminate SSL directly. | certificate and let it terminate SSL directly. | ||||
If you prefer not to do this, two other options are: | If you prefer not to do this, two other options are: | ||||
▲ Show 20 Lines • Show All 43 Lines • ▼ Show 20 Lines | |||||
```lang=nginx, name=/etc/nginx/conf.d/websocket_pool.conf | ```lang=nginx, name=/etc/nginx/conf.d/websocket_pool.conf | ||||
upstream websocket_pool { | upstream websocket_pool { | ||||
ip_hash; | ip_hash; | ||||
server 127.0.0.1:22280; | server 127.0.0.1:22280; | ||||
} | } | ||||
``` | ``` | ||||
```lang=nginx, name=/etc/nginx/sites-enabled/phabricator.example.com.conf | ```lang=nginx, name=/etc/nginx/sites-enabled/phorge.example.com.conf | ||||
server { | server { | ||||
server_name phabricator.example.com; | server_name phorge.example.com; | ||||
root /path/to/phabricator/webroot; | root /path/to/phorge/webroot; | ||||
// ... | // ... | ||||
location = /ws/ { | location = /ws/ { | ||||
proxy_pass http://websocket_pool; | proxy_pass http://websocket_pool; | ||||
proxy_http_version 1.1; | proxy_http_version 1.1; | ||||
proxy_set_header Upgrade $http_upgrade; | proxy_set_header Upgrade $http_upgrade; | ||||
proxy_set_header Connection "upgrade"; | proxy_set_header Connection "upgrade"; | ||||
proxy_read_timeout 999999999; | proxy_read_timeout 999999999; | ||||
} | } | ||||
} | } | ||||
``` | ``` | ||||
With this approach, you should make these additional adjustments: | With this approach, you should make these additional adjustments: | ||||
**Phabricator Configuration**: The entry in `notification.servers` with type | **Phorge Configuration**: The entry in `notification.servers` with type | ||||
`"client"` should have these adjustments made: | `"client"` should have these adjustments made: | ||||
- Set `host` to the Phabricator host. | - Set `host` to the Phorge host. | ||||
- Set `port` to the standard HTTPS port (usually `443`). | - Set `port` to the standard HTTPS port (usually `443`). | ||||
- Set `protocol` to `"https"`. | - Set `protocol` to `"https"`. | ||||
- Set `path` to `/ws/`, so it matches the special `location` in your | - Set `path` to `/ws/`, so it matches the special `location` in your | ||||
`nginx` config. | `nginx` config. | ||||
You do not need to adjust the `"admin"` server. | You do not need to adjust the `"admin"` server. | ||||
**Aphlict**: Your Aphlict configuration should make these adjustments to | **Aphlict**: Your Aphlict configuration should make these adjustments to | ||||
the `"client"` server: | the `"client"` server: | ||||
- Do not specify any `ssl.*` options: `nginx` will send plain HTTP traffic | - Do not specify any `ssl.*` options: `nginx` will send plain HTTP traffic | ||||
to Aphlict. | to Aphlict. | ||||
- Optionally, you can `listen` on `127.0.0.1` instead of `0.0.0.0`, because | - Optionally, you can `listen` on `127.0.0.1` instead of `0.0.0.0`, because | ||||
the server will no longer receive external traffic. | the server will no longer receive external traffic. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0