notifications.diviner

@title Notifications User Guide: Setup and Configuration
@group userguide

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.

= Running the Aphlict Server =

Phabricator implements realtime notifications using a Node.js server called
"Aphlict". To run it:

  - Install node.js.
  - Run `bin/aphlict` (this script must be run as root).

The server must be able to listen on port **843** and port **22280** for Aphlict
to work. You can change the latter port in the `notification.client-uri` config,
but port 843 is used by Flash and can not be changed. In particular, if you're
running in EC2, you need to unblock both of these ports in the server's security
group configuration.

You may 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.user` Non-root user to drop permissions to after binding to
    privileged ports.
  - `notification.pid` Pidfile location used to stop any running server when
    aphlict is restarted.

In most cases, the defaults are appropriate, except that you should set
`notification.user` to some valid system user so Aphlict isn't running as root.

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

== Testing the Server ==

The easiest way to test the server is to have two users login and comment on
the same Maniphest Task or Differential Revision. They should receive in-browser
notifications about the other user's activity.

NOTE: This is cumbersome. There will be better testing tools at some point.

== Debugging Server Problems ==

You can run `aphlict` in the foreground to get output to your console:

  phabricator/ $ sudo ./bin/aphlict --foreground

You can run `support/aphlict/client/aphlict_test_client.php` to connect to the
Aphlict server from the command line. Messages the client receives will be
printed to stdout.

You can set `notification.debug` in your configuration to get additional
output in your browser.

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.