docs: further clean up (#399)

* fill out the FCM doc a bit more
* add pointer to API docs
* clean up `running` doc a bit

docs/src/fcm.md

@@ -1,3 +1,46 @@
-# Google GCM/FCM
+# Configuring for Google GCM/FCM
 
-<!-- TODO: finish this doc --> 
+<!-- TODO: finish this doc -->
+
+Google's [Firebase Cloud
+Messaging](https://firebase.google.com/docs/cloud-messaging/) (FCM)
+superceded Google Cloud Messaging (GCM). The server setup [process is well documented](https://firebase.google.com/docs/cloud-messaging/server), with autopush using the [FTM HTTP v1 API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages) protocol.
+
+## Authorization
+
+FCM requires a server authentication key. These keys are specified in the `autoendpoint` configuration as the environment variable `AUTOEND__FCM__CREDENTIALS` (or configuration file option `[fcm] server_credentials`) as a serialized JSON structure containing the bridge project ID and either the contents of the credential file generated by the [Service Account generated key](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually), or a path to the file containing the credentials
+
+As an example, let's assume we create a Push recipient application with a Google Cloud Project ID of `random-example-123`. Since our clients could be using various alternative bridges (for testing, stage, etc.) we would use an alternate identifier for the `instance_id`
+
+If we saved the sample credentials we received from Google to `./keys/credentials.json`, it might look like:
+
+```json
+{
+    "type": "service_account",
+    "project_id":"random-example-123",
+    "private_key_id": "abc...890",
+    "private_key": "---... ---",
+    "client_email": "...",
+    "client_id": "...",
+    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    "token_uri": "https://oauth2.googleapis.com/token",
+    "auth_provider_x509_cert_url": "https://www.googleapis.com/...",
+    "client_x509_cert_url": "..."
+}
+```
+
+## Autoendpoint Configuration
+
+If we wished to "in-line" the credentials for an instance_id of `default`, our environment variable would look like:
+
+```bash
+AUTOEND__FCM__CREDENTIALS='{"default":{"project_id":"random-example-123","credential":"{\"type\": \"service_account\",\"project_id\":\"random-example-123\",\"private_key_id\": \"abc..890\",\"private_key\": \"---...---\",\"client_email\": \"...\",\"client_id\": \"...\",\"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\"token_uri\": \"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\": \"https://www.googleapis.com/...\",\"client_x509_cert_url\":\"...\"}"}'
+```
+
+We could also just point to the relative path of the file using:
+
+```bash
+AUTOEND__FCM__CREDENTIALS='{"default":{"project_id":"random-example-123","credential":"keys/credentials.json"}'
+```
+
+Only `autoendpoint` uses the bridge interface, so you do not need to specify this configuration for `autoconnect`.

docs/src/index.md

@@ -57,7 +57,7 @@ or to deploy autopush to a production environment for Firefox.
 
 For developers wishing to work with the latest autopush source code,
 it's recommended that you first familiarize yourself with
-`running Autopush <running-autopush>` before proceeding.
+[running Autopush](running.md) before proceeding.
 
 <div class="toctree" maxdepth="2">
 
@@ -87,19 +87,25 @@ All source code is available on [github under
 autopush](https://github.com/mozilla-services/autopush-rs).
 
 <!-- TODO -->
-* Code Documentation
+* [autoconnect](api/autoconnect) - WebSocket server for desktop UAs
+  * [autoconnect_common](api/autoconnect_common) - Common functions for autoconnect
+  * [autoconnect_settings](api/autoconnect_settings) - Settings and configuration
+  * [autoconnect_web](api/autoconnect_web) - HTTP functions
+  * [autoconnect_ws](api/autoconnect_ws) - WebSocket functions
+  * [autoconnect_ws_sm](api/autoconnect_ws_sm) - WebSocket state machine
+* [autoendpoint](api/autoendpoint) - HTTP server for publication and mobile
+* [autopush_common](api/autopush_common) - Common functions for autoconnect and autoendpoint
 
 We are using [rust](https://rust-lang.org) for a number of optimizations
 and speed improvements. These efforts are ongoing and may be subject to
 change. Unfortunately, this also means that formal documentation is not
 yet available. You are, of course, welcome to review the code located in
-`./autopush-rs`.
+[`autopush-rs`](https://github.com/mozilla-services/autopush-rs).
 
 ## Changelog
 
 [Changelog](https://github.com/mozilla-services/autopush-rs/blob/master/CHANGELOG.md)
 
-
 ## Bugs/Support
 
 Bugs should be reported on the [autopush github issue

docs/src/running.md

@@ -29,7 +29,10 @@ can be run on separate hosts as well, or with AWS DynamoDB instead.
   - [ ]
 - [] define steps here
 
-<div style="text-decoration:line-through">
+<!-- The following block needs to be updated. The docker instructions are no
+     longer correct. Please ignore.
+
+<div style="text-decoration:line-through;display:none">
 These instructions will yield a locally running Autopush setup with the
 connection node listening on localhost port `8080`, with the endpoint
 node listening on localhost port `8082`. Make sure these ports are
@@ -57,6 +60,7 @@ have the Autopush daemons use other ports.
 sure you have appropriate free-space before proceeding.
 
 </div>
+-->
 
 ### Generate a Crypto-Key