diff --git a/src/docs/user/configuration/notifications.diviner b/src/docs/user/configuration/notifications.diviner index e1f5cacaed..960b931b66 100644 --- a/src/docs/user/configuration/notifications.diviner +++ b/src/docs/user/configuration/notifications.diviner @@ -1,262 +1,262 @@ @title Notifications User Guide: Setup and Configuration @group config Guide to setting up notifications. Overview ======== By default, Phabricator delivers information about events (like users creating tasks or commenting on code reviews) through email and in-application notifications. Phabricator 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 an object has been updated. To enable real-time notifications: - Configure and start the notification server, as described below. - Adjust `notification.servers` to point at it. This document describes the process in detail. Supported Browsers ================== Notifications are supported for browsers which support WebSockets. This covers most modern browsers (like Chrome, Firefox, Safari, and recent versions of Internet Explorer) and many mobile browsers. IE8 and IE9 do not support WebSockets, so real-time notifications won't work in those browsers. Installing Node and Modules =========================== The notification server uses Node.js, so you'll need to install it first. To install Node.js, follow the instructions on [[ http://nodejs.org | nodejs.org ]]. You will also need to install the `ws` module for Node. This needs to be installed into the notification server directory: phabricator/ $ cd support/aphlict/server/ phabricator/support/aphlict/server/ $ npm install ws Once Node.js and the `ws` module are installed, you're ready to start the server. Running the Aphlict Server ========================== After installing Node.js, you can control the notification server with the `bin/aphlict` command. To start the server: phabricator/ $ bin/aphlict start 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 server. The server configuration is controlled by a configuration file, which is separate from Phabricator's configuration settings. The default file can be found at `phabricator/conf/aphlict/aphlict.default.json`. 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 it exists) or specify a configuration file explicitly with the `--config` flag: phabricator/ $ bin/aphlict start --config path/to/config.json The configuration file has these settings: - `servers`: //Required list.// A list of servers to start. - `logs`: //Optional list.// A list of logs to write to. - `pidfile`: //Required string.// Path to a PID file. Each server in the `servers` list should be an object with these keys: - `type`: //Required string.// The type of server to start. Options are `admin` or `client`. Normally, you should run one of each. - `port`: //Required int.// The port this server should listen on. - `listen`: //Optional string.// Which interface to bind to. By default, the `admin` server is bound to localhost (so only other services on the local machine can connect to it), while the `client` server is bound to `0.0.0.0` (so any client can connect. - `ssl.key`: //Optional string.// If you want to use SSL on this port, the path to an SSL key. - `ssl.cert`: //Optional string.// If you want to use SSL on this port, the path to an SSL certificate. Each log in the `logs` list should be an object with these keys: - `path`: //Required string.// Path to the log file. The defaults are appropriate for simple cases, but you may need to adjust them if you are running a more complex configuration. Configuring Phabricator ======================= After starting the server, configure Phabricator to connect to it by adjusting `notification.servers`. This configuration option should have a list of servers that Phabricator should interact with. Normally, you'll list one client server and one admin server, like this: ```lang=json [ { "type": "client", "host": "phabricator.mycompany.com", "port": 22280, "protocol": "https" }, { "type": "admin", "host": "127.0.0.1", "port": 22281, "protocol": "http" } ] ``` This definition defines which services the user's browser will attempt to connect to. Most of the time, it will be very similar to the services defined in the Aphlict configuration. However, if you are sending traffic through a load balancer or terminating SSL somewhere before traffic reaches Aphlict, the services the browser connects to may need to have different hosts, ports or protocols than the underlying server listens on. Verifying Server Status ======================= After configuring `notification.servers`, navigate to {nav Config > Notification Servers} to verify that things are operational. Troubleshooting =============== You can run `aphlict` in the foreground to get output to your console: phabricator/ $ ./bin/aphlict debug Because the notification server uses WebSockets, your browser error console 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 change this location by adjusting configuration. The log may contain information that is useful in resolving issues. SSL and HTTPS ============= If you serve Phabricator over HTTPS, you must also serve websockets over HTTPS. Browsers will refuse to connect to `ws://` websockets from HTTPS pages. If a client connects to Phabricator over HTTPS, Phabricator will automatically select an appropriate HTTPS service from `notification.servers` and instruct the browser to open a websocket connection with `wss://`. The simplest way to do this is configure Aphlict with an SSL key and certificate and let it terminate SSL directly. If you prefer not to do this, two other options are: - run the websocket through a websocket-capable loadbalancer and terminate SSL there; or - - run the websokket through `nginx` over the same socket as the rest of + - run the websocket through `nginx` over the same socket as the rest of your web traffic. See the next sections for more detail. Terminating SSL with a Load Balancer ==================================== If you want to terminate SSL in front of the notification server with a traditional load balancer or a similar device, do this: - Point `notification.servers` at your load balancer or reverse proxy, specifying that the protocol is `https`. - On the load balancer or proxy, terminate SSL and forward traffic to the Aphlict server. - In the Aphlict configuration, listen on the target port with `http`. Terminating SSL with Nginx ========================== If you use `nginx`, you can send websocket traffic to the same port as normal HTTP traffic and have `nginx` proxy it selectively based on the request path. This requires `nginx` 1.3 or greater. See the `nginx` documentation for details: > http://nginx.com/blog/websocket-nginx/ This is very complex, but allows you to support notifications without opening additional ports. An example `nginx` configuration might look something like this: ```lang=nginx, name=/etc/nginx/conf.d/connection_upgrade.conf map $http_upgrade $connection_upgrade { default upgrade; '' close; } ``` ```lang=nginx, name=/etc/nginx/conf.d/websocket_pool.conf upstream websocket_pool { ip_hash; server 127.0.0.1:22280; } ``` ```lang=nginx, name=/etc/nginx/sites-enabled/phabricator.example.com.conf server { server_name phabricator.example.com; root /path/to/phabricator/webroot; // ... location = /ws/ { proxy_pass http://websocket_pool; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 999999999; } } ``` With this approach, you should make these additional adjustments: **Phabricator Configuration**: The entry in `notification.servers` with type `"client"` should have these adjustments made: - Set `host` to the Phabricator host. - Set `port` to the standard HTTPS port (usually `443`). - Set `protocol` to `"https"`. - Set `path` to `/ws/`, so it matches the special `location` in your `nginx` config. You do not need to adjust the `"admin"` server. **Aphlict**: Your Aphlict configuration should make these adjustments to the `"client"` server: - The `protocol` should be `"http"`: `nginx` will send plain HTTP traffic to Aphlict. - Optionally, you can `listen` on `127.0.0.1` instead of `0.0.0.0`, because the server will no longer receive external traffic.