Differential D15703 Diff 37833 src/docs/user/configuration/notifications.diviner

Changeset 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, Phabricator 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		Phabricator can also be configured to deliver notifications in real time, by
popping up a message in any open browser windows if something has		popping up a message in any open browser windows if something has happened or
happened or an object has been updated.		an object has been updated.

To enable real-time notifications:		To enable real-time notifications:

- Set `notification.enabled` in your configuration to true.		- Configure and start the notification server, as described below.
- Run the notification server, as described below.		- Adjust `notification.servers` to point at it.

This document describes the process in detail.		This document describes the process in detail.


Supported Browsers		Supported Browsers
==================		==================

Notifications are supported for browsers which support WebSockets. This covers		Notifications are supported for browsers which support WebSockets. This covers
▲ Show 20 Lines • Show All 70 Lines • ▼ Show 20 Lines

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 Phabricator
=======================		=======================

You may also want to adjust these settings:		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"
		}
		]
		```

- `notification.client-uri` Externally-facing host and port that browsers will		This definition defines which services the user's browser will attempt to
connect to in order to listen for notifications.		connect to. Most of the time, it will be very similar to the services defined
- `notification.server-uri` Internally-facing host and port that Phabricator		in the Aphlict configuration. However, if you are sending traffic through a
will connect to in order to publish notifications.		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		Verifying Server Status
=======================		=======================

Access `/notification/status/` to verify the server is operational. You should		After configuring `notification.servers`, navigate to
see a table showing stats like "uptime" and connection/message counts if the		{nav Config > Notification Servers} to verify that things are operational.
server is working. If it isn't working, you should see an error.

You can also send a test notification by clicking the button in the upper right
corner of this screen.


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		phabricator/ $ ./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 changing `notification.log` in your configuration. The		change this location by adjusting configuration. The log may contain
log may contain information useful in resolving issues.		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
		chadUnsubmitted Not Done Inline Actions websocket? chad: websocket?
		your web traffic.

		See the next sections for more detail.


Advanced Usage		Terminating SSL with a Load Balancer
==============		====================================

It is possible to route the WebSockets traffic for Aphlict through a reverse		If you want to terminate SSL in front of the notification server with a
proxy such as `nginx` (see @{article:Configuration Guide} for instructions on		traditional load balancer or a similar device, do this:
configuring `nginx`). In order to do this with `nginx`, you will require at
least version 1.3. You can read some more information about using `nginx` with
WebSockets at http://nginx.com/blog/websocket-nginx/.

There are a few benefits of this approach:

- SSL is terminated at the `nginx` layer and consequently there is no need to
configure `notificaton.ssl-cert` and `notification.ssl-key` (in fact, with
this approach you should //not// configure these options because otherwise
the Aphlict server will not accept HTTP traffic).
- You don't have to open up a separate port on the server.
- Clients don't need to be able to connect to Aphlict over a non-standard
port which may be blocked by a firewall or anti-virus software.

The following files show an example `nginx` configuration. Note that this is an		- Point `notification.servers` at your load balancer or reverse proxy,
example only and you may need to adjust this to suit your own setup.		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		```lang=nginx, name=/etc/nginx/conf.d/connection_upgrade.conf
map $http_upgrade $connection_upgrade {		map $http_upgrade $connection_upgrade {
default upgrade;		default upgrade;
'' close;		'' close;
}		}
```		```

Show All 16 Lines	location = /ws/ {
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 set `notification.client-uri` to		With this approach, you should make these additional adjustments:
`http://localhost/ws/`. Additionally, there is no need for the Aphlict server
to bind to `0.0.0.0` anymore (which is the default behavior), so you could		Phabricator Configuration: The entry in `notification.servers` with type
start the Aphlict server with `./bin/aphlict start --client-host=localhost`		`"client"` should have these adjustments made:
instead.
		- 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.