Differential D11143 Diff 27104 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 an object has been updated.			happened or an object has been updated.

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

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

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

	= Running the Aphlict Server =

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

	- Install node.js.			Notifications are supported for browsers which support WebSockets. This covers
	- Run `bin/aphlict start` (this script must be run as root).			most modern browsers (like Chrome, Firefox, Safari, and recent versions of
				Internet Explorer) and many mobile browsers.

	The server must be able to listen on port 843 and port 22280 for Aphlict			IE8 and IE9 do not support WebSockets, so real-time notifications won't work in
	to work. You can change the latter port in the `notification.client-uri` config,			those browsers.
	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.

				joshuaspenceUnsubmitted Not Done Inline Actions There's only one port now. joshuaspence: There's only one port now.
	You may want to adjust these settings:
				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. After installing
				Node, run `npm install -g ws` to install it.

				name="(Option 1, Recommended) Install 'ws' Module Globally"
				$ npm install -g ws # Global Install

				If you prefer, you can also install it locally in the `support/aphlict/server/`
				directory:

				name="(Option 2) Install 'ws' Module Locally"
				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

				The server must be able to listen on port 22280 for Aphlict to work. In
				particular, if you're running in EC2, you need to unblock this port in the
				server's security group configuration. You can change this port in the
				`notification.client-uri` config.

				You may need to adjust these settings:

				- `notification.ssl-cert` Point this at an SSL certificate for secure
				WebSockets.
				- `notification.ssl-key` Point this at an SSL keyfile for secure WebSockets.

				In particular, if your server uses HTTPS, you must configure these options.
				Browsers will not allow you to use non-SSL websockets from an SSL web page.

				You may also want to adjust these settings:

	- `notification.client-uri` Externally-facing host and port that browsers will			- `notification.client-uri` Externally-facing host and port that browsers will
	connect to in order to listen for notifications.			connect to in order to listen for notifications.
	- `notification.server-uri` Internally-facing host and port that Phabricator			- `notification.server-uri` Internally-facing host and port that Phabricator
	will connect to in order to publish notifications.			will connect to in order to publish notifications.
	- `notification.log` Log file location for the server.			- `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			- `notification.pid` Pidfile location used to stop any running server when
	aphlict is restarted.			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 ==			Verifying Server Status
				=======================

	Access `/notification/status/` to verify the server is operational. You should			Access `/notification/status/` to verify the server is operational. You should
	see a table showing stats like "uptime" and connection/message counts if the			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.			server is working. If it isn't working, you should see an error.

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

	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.			Troubleshooting
				===============
	== Debugging Server Problems ==

	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/ $ sudo ./bin/aphlict debug			phabricator/ $ ./bin/aphlict debug

	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			Because the notification server uses WebSockets, your browser error console
	output in your browser.			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 changing `notification.log` in your configuration. The
	log may contain information useful in resolving issues.			log may contain information useful in resolving issues.