Page MenuHomePhorge
Differential D25007 Diff 21 src/docs/user/configuration/notifications.diviner

Changeset View

Standalone View

View Options

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