@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:

  - Set `notification.enabled` in your configuration to true.
  - Run the notification server, as described below.

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`: A list of servers to start.

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.

The defaults are appropriate for simple cases, but you may need to adjust them
if you are running a more complex configuration.


Configuring Phabricator
=======================

You may also want to adjust these settings:

  - `notification.client-uri` Externally-facing host and port that browsers will
    connect to in order to listen for notifications.
  - `notification.server-uri` Internally-facing host and port that Phabricator
    will connect to in order to publish notifications.
  - `notification.log` Log file location for the server.
  - `notification.pidfile` Pidfile location used to stop any running server when
    aphlict is restarted.


Verifying Server Status
=======================

Access `/notification/status/` to verify the server is operational. You should
see a table showing stats like "uptime" and connection/message counts if the
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
===============

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 changing `notification.log` in your configuration. The
log may contain information useful in resolving issues.


Advanced Usage
==============

It is possible to route the WebSockets traffic for Aphlict through a reverse
proxy such as `nginx` (see @{article:Configuration Guide} for instructions on
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
example only and you may need to adjust this to suit your own setup.

```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 set `notification.client-uri` to
`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
start the Aphlict server with `./bin/aphlict start --client-host=localhost`
instead.