From 44f2195eec218c3166d7a935d3b2bec80775d2cd Mon Sep 17 00:00:00 2001
From: Joshua Spence <josh@joshuaspence.com>
Date: Fri, 9 Jan 2015 18:03:15 +1100
Subject: [PATCH] Add documentation for routing WebSockets through a reverse
 proxy

Summary: This is a little rough and should be considered an "advanced" option. Having said that, this works well in my install and I imagine that other installs will find this beneficial.

Test Plan: Eyeball it.

Reviewers: #blessed_reviewers, epriestley

Reviewed By: #blessed_reviewers, epriestley

Subscribers: Korvin, epriestley

Differential Revision: https://secure.phabricator.com/D11293
---
 .../user/configuration/notifications.diviner  | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/src/docs/user/configuration/notifications.diviner b/src/docs/user/configuration/notifications.diviner
index 71609826c9..ae973f9938 100644
--- a/src/docs/user/configuration/notifications.diviner
+++ b/src/docs/user/configuration/notifications.diviner
@@ -108,3 +108,63 @@ 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.