The way Aphlict (the real-time notification server) is configured has changed.
What Has Changed
===============
Previously, configuration was controlled primarily by these config values in Phabricator:
- `notification.enabled`
- `notification.log`
- `notification.client-uri`
- `notification.server-uri`
- `notification.pidfile`
- `notification.ssl-key`
- `notification.ssl-cert`
Some additional configuration was provided via flags to `bin/aphlict`:
- `--client-host`
- `--client-port`
**All of these options and flags have been removed.** They have been replaced with two new configuration sources:
- On the Phabricator/frontend side, the new `notification.servers` configuration option now provides a comprehensive description of notification services from a client/frontend viewpoint.
- On the Aphlict/backend, Aphlict is now configured with a JSON file, which provides a comprehensive description of notification services from a server/backend viewpoint.
How to Upgrade
============
After you update, you'll probably receive setup warnings about the removed configuration options. Copy the values down if they aren't self-evident, then remove them according to the instructions. That should clear the setup warnings.
When you start Aphlict, it now reads a configuration file. The default file it reads is `phabricator/conf/aphlict/aphlict.default.json`. Here's what the file looks like:
```lang=json
{
"servers": [
{
"type": "client",
"port": 22280,
"listen": "0.0.0.0",
"ssl.key": null,
"ssl.cert": null
},
{
"type": "admin",
"port": 22281,
"listen": "127.0.0.1",
"ssl.key": null,
"ssl.cert": null
}
],
"logs": [
{
"path": "/var/log/aphlict.log"
}
],
"pidfile": "/var/tmp/aphlict/pid/aphlict.pid"
}
```
If your setup was fairly similar to the old defaults, it's possible you don't need to change this file at all. However, if you changed ports, added SSL, moved logfiles, etc., you'll need to update this file for those customizations.
You can either copy it into `phabricator/conf/aphlict/aphlict.custom.json` (this path is `.gitignored`, and read instead of `aphlict.default.json` if it exists) and modify it, or put it somewhere else and use `bin/aphlict --config path/to/config.json` to specify the file explicitly when starting Aphlict.
If you had customized `notification.pidfile` or `notification.log`, copy the values into `pidfile` or the `path` value in the `log` list respectively.
If you had customized `notification-ssl-key` or `notification.ssl-cert`, update the appropriate keys in the `"client"` server definition (the `"admin"` server did not previously support or use SSL keys, so don't touch those if you're just updating).
If you had customized ports, adjust them in the corresponding `"port"` keys. The old `client-uri` corresponds to the `"client"` server, and the old `server-uri` corresponds to the `"admin"` server.
Once you've updated the file, run `bin/aphlict debug` to check it. You should get output confirming your logfiles and servers are set up reasonably, or useful messages if you have configuration errors.
If things look good, use `bin/aphlict start` (possibly with a `--config` flag) to start the server.
Now, you need to configure `notification.servers` in Phabricator. This will have similar values, except from a client/frontend perspective. Here's the default value suggested as an example:
```lang=json
[
{
"type": "client",
"host": "phabricator.mycompany.com",
"port": 22280,
"protocol": "https"
},
{
"type": "admin",
"host": "127.0.0.1",
"port": 22281,
"protocol": "http"
}
]
```
Generally, you'll specify a `"client"` server that has the same values as your old `notification.client-uri`, and a `"admin"` server that has the same values as your old `notification.server-uri`.
Note that these frontend/client values no longer have to match the backend/server Aphlict values and are free to vary in whatever way you desire. Suppose you want a setup like this:
- Browsers connect to `loadbalancer.com:1234` over SSL.
- The load balancer strips SSL.
- The load balancer forwards the traffic to `backend.com:6789`.
Previously, this was difficult to configure, but it is now straightforward: put `loadbalancer.com`, `1234` and `https` in the Phabricator frontend configuration. Set up your load balancer. Put `6789` and no SSL in the backend configuration.
Why Things Changed
================
T10697 has more technical details about this change. The major motivating factors were:
**More Explicit Configuration**: Users frequently had difficulty configuring Aphlict. A major source of confusion and difficulty was its use of a single set of configuration options to define both the frontend and backend behaviors.
The original intent of having less configuration was to make things easier, but in practice there was widespread interest in routing websocket requests through some sort of middle layer which meant that the client and server views of the world were often not the same. The old method took too many shortcuts, had two many weird pieces of implicit magic, and frequently led users astray (tasks merged into T10697 are a boneyard of these issues).
**Preparation for Clustering**: We plan to allow multiple Aphlict servers on different hosts to work together soon, discussed in T6915, so that Phabricator can transparently survive the loss of some subset of the notification hosts. This wouldn't have worked with the old configuration, since Phabricator needs to know about multiple nodes -- it can't reasonably survive the loss of a node if that's the only node it knows about. We could have added new configuration on top of the old configuration, but given the other problems it seemed better in the long run to rewrite everything.
**More Flexibility**: There are some additional configuration options (like log verbosity and Node memory tweaks) that I'd like to add at some point. Beyond clustering, turning everything into lists of dictionaries gives us more options to add these features in the future without needing to fill top-level configuration up with a ton of new options.