docs: Document the push notification forwarding service.

docs/index.rst

@@ -53,6 +53,7 @@ Contents:
    Installing a production server <prod-install>
    prod-troubleshooting
    prod-customize
+   prod-mobile-push-notifications
    prod-maintain-secure-upgrade
    security-model
    prod-authentication-methods

docs/prod-customize.md

@@ -1,75 +1,33 @@
 # Customize Zulip
 
 Once you've got Zulip setup, you'll likely want to configure it the
-way you like.  There are several things to focus on:
-
-1. [Integrations](#integrations)
-2. [Streams and Topics](#streams-and-topics)
-3. [Notification settings](#notification-settings)
-4. [Mobile and desktop apps](#mobile-and-desktop-apps)
-5. [Terms of service and Privacy policy](#terms-of-service-and-privacy-policy)
-
-Lastly, read about Zulip's other [great features](#all-other-features), and
-then [enjoy your Zulip installation](#enjoy-your-zulip-installation)!
-
-## Integrations
-
-We recommend setting up integrations for the major
-tools that your team works with.  For example, if you're a software
-development team, you may want to start with integrations for your
-version control, issue tracker, CI system, and monitoring tools.
-
-Spend time configuring these integrations to be how you like them --
-if an integration is spammy, you may want to change it to not send
-messages that nobody cares about (e.g., for the Trac integration, some
-teams find they only want notifications when new tickets are opened,
-commented on, or closed, and not every time someone edits the
-metadata).
-
-If Zulip doesn't have an integration you want, you can add your own!
-Most integrations are very easy to write, and even more complex
-integrations usually take less than a day's work to build.  We very
-much appreciate contributions of new integrations; see the brief
-[integration writing guide](integration-guide.html).
-
-
-It can often be valuable to integrate your own internal processes to
-send notifications into Zulip; e.g. notifications of new customer
-signups, new error reports, or daily reports on the team's key
-metrics; this can often spawn discussions in response to the data.
-
-## Streams and Topics
-
-If it feels like a stream has too much
-traffic about a topic only of interest to some of the subscribers,
-consider adding or renaming streams until you feel like your team is
-working productively.
-
-Second, most users are not used to topics.  It can require a bit of
-time for everyone to get used to topics and start benefitting from
-them, but usually once a team is using them well, everyone ends up
-enthusiastic about how much topics make life easier.  Some tips on
-using topics:
-
-* When replying to an existing conversation thread, just click on the
-  message, or navigate to it with the arrow keys and hit "r" or
-  "enter" to reply on the same topic
-* When you start a new conversation topic, even if it's related to the
-  previous conversation, type a new topic in the compose box
-* You can edit topics to fix a thread that's already been started,
-  which can be helpful when onboarding new batches of users to the platform.
-
-Third, setting default streams for new users is a great way to get new
-users involved in conversations before they've accustomed themselves
-with joining streams on their own.  You can do so on the
-`/#organization` page (get there from the gear menu).
-
-## Notification settings
-
-Zulip gives you a great deal of control
-over which messages trigger desktop notifications; you can configure
-these extensively in the `/#settings` page (get there from the gear
-menu).
+way you like.  Most configuration can be done by a realm administrator
+on the web (see
+[the documentation for realm administrators](https://zulipchat.com/help/getting-your-organization-started-with-zulip);
+this page discusses those additional configuration items that can be
+done by a system administrator.
+
+## Mobile and desktop apps
+
+The Zulip apps expect to be talking to to servers with a properly
+signed SSL certificate, in most cases and will not accept a
+self-signed certificate.  You should get a proper SSL certificate
+before testing the apps.
+
+Because of how Google and Apple have architected the security model of
+their push notification protocols, the Zulip mobile apps for
+[iOS](https://itunes.apple.com/us/app/zulip/id1203036395) and
+[Android](https://play.google.com/store/apps/details?id=com.zulip.android)
+can only receive push notifications from a single Zulip server.  We
+have configured that server to be `push.zulipchat.com`, and offer a
+[push notification forwarding service](prod-mobile-push-notifications.html) that
+forwards push notifications through our servers to mobile devices.
+Read the linked documentation for instructions on how to register for
+and configure this service.
+
+By the end of summer 2017, all of the Zulip apps will have full
+support for multiple accounts, potentially on different Zulip servers,
+with a convenient UI for switching between them.
 
 ## Terms of service and Privacy policy
 
@@ -81,29 +39,27 @@ support for included HTML).  A good approach is to use paths like
 `/etc/zulip/terms.md`, so that it's easy to back up your policy
 configuration along with your other Zulip server configuration.
 
-## Mobile and desktop apps
+## Miscellaneous server settings
 
-Currently, the Zulip Desktop app
-only supports talking to servers with a properly signed SSL
-certificate, so you may find that you get a blank screen when you
-connect to a Zulip server using a self-signed certificate.
+Zulip has dozens of settings documented in the comments in
+`/etc/zulip/settings.py`; you can review
+[the latest version of the settings.py template][settings-py-template]
+if you've deleted the comments or want to check if new settings have
+been added in more recent versions of Zulip.
 
-The iOS app currently available in the App Store doesn't support
-Google auth SSO against non-zulip.com servers; there's a design for
-how to fix that which wouldn't be a ton of work to implement.  If you
-are interested in helping out with the Zulip mobile apps, shoot an
-email to [email protected] and the maintainers can guide
-you on how to help.
+Since Zulip's settings file is a Python script, there are a number of
+other things that one can configure that are not documented; ask on
+[chat.zulip.org](https://zulip.readthedocs.io/en/latest/chat-zulip-org.html)
+if there's something you'd like to do but can't figure out how to.
 
-For announcements about improvements to the apps, make sure to join
-the [email protected] list so that you can receive the
-announcements when these become available.
+[settings-py-template]: https://github.com/zulip/zulip/blob/master/zproject/prod_settings_template.py
 
-## All other features
+## Zulip announcement list
 
-Hotkeys, emoji, search filters, @-mentions, etc.  Zulip has lots of
-great features; make sure your team knows they exist and how to use
-them effectively.
+If you haven't already, subscribe to the
+[zulip-announce](https://groups.google.com/forum/#!forum/zulip-announce)
+list so that you can receive important announces like new Zulip
+releases or major changes to the app ecosystem..
 
 ## Enjoy your Zulip installation!
 

docs/prod-mobile-push-notifications.md

@@ -0,0 +1,74 @@
+# Mobile push notification service
+
+Zulip's iOS and Android mobile apps support receiving push
+notifications from Zulip servers to let users know when new messages
+have arrived.  This is an important feature to having a great
+experience using the Zulip mobile apps.
+
+For technical reasons (explained below), in order to deliver mobile
+push notifications in the app store versions of our mobile apps, you
+will need to register your Zulip server with the Zulip mobile push
+notification service.  This service will forward push notifications
+generated by your server to the Zulip mobile app automatically.
+
+## How to sign up
+
+Starting with Zulip 1.6, Zulip servers support forwarding push
+notifications to a central push notification forwarding service.  You
+can enable this for your Zulip server as follows:
+
+1. First, contact [email protected] for instructions on
+   registering your server (we hope to have a nice web flow available
+   for this soon).
+
+2. Then, uncomment the `PUSH_NOTIFICATION_BOUNCER_URL =
+   https://push.zulipchat.com` line in your `/etc/zulip/settings.py`
+   file, and
+   [restart your Zulip server](prod-maintain-secure-upgrade.html#updating-settings).
+
+That should be all you need to do!
+
+To test whether you've configured it properly, just
+[configure mobile push notifications to always be sent][notification-settings],
+start the
+[Zulip Android app](https://play.google.com/store/apps/details?id=com.zulip.android),
+in the background, and then have another user send you private
+messages.  They should appear in the Android notification area.
+
+[notification-settings]: https://zulipchat.com/help/configure-mobile-notifications
+
+## Why this is necessary
+
+Both Google's and Apple's push notification services have a security
+model that does not support mutually untrusted self-hosted servers
+sending push notifications to the same app.  In particular, when an
+app is published to their respective app stores, one must compile into
+the app a secret corresponding to the server that will be able to
+publish push notifications for the app.  This means that it is
+impossible for a single app in their stores to receive push
+notifications from multiple, mutually untrusted, servers.
+
+Zulip's solution to this problem is to provide a central push
+notification forwarding service, which allows registered Zulip servers
+to send push notifications to the Zulip app indirectly (through the
+forwarding service).
+
+## Security and privacy implications
+
+We've designed this push notification bouncer service with security in
+mind:
+
+* All of the network requests (both from Zulip servers to the Push
+  Notification Service and from the Push Notification Service to the
+  relevant Google and Apple services) are encrypted over the wire with
+  SSL/TLS.
+* The code for the push notification forwarding service is 100% open
+  source and available as part of the
+  [Zulip server project on GitHub](https://github.com/zulip/zulip).
+  The service's logging is designed to protect the privacy of users of
+  Zulip servers that are using the forwarding service.
+* The push notification forwarding servers are professionally managed
+  by a small team.
+
+If you have any questions about the security model, contact
+[email protected].

zproject/prod_settings_template.py

@@ -133,6 +133,13 @@
 
 ### OPTIONAL SETTINGS
 
+# Support for mobile push notifications.  Setting controls whether
+# push notifications will be forwarded through a Zulip push
+# notification bouncer server to the mobile apps.  See
+# https://zulip.readthedocs.io/en/latest/prod-mobile-push-notifications.html
+# for information on how to sign up for and configure this.
+#PUSH_NOTIFICATION_BOUNCER_URL = https://push.zulipchat.com
+
 # Controls whether session cookies expire when the browser closes
 SESSION_EXPIRE_AT_BROWSER_CLOSE = False