diff --git a/docs/src/fcm.md b/docs/src/fcm.md index 976c4e496..5fded66f0 100644 --- a/docs/src/fcm.md +++ b/docs/src/fcm.md @@ -1,3 +1,46 @@ -# Google GCM/FCM +# Configuring for Google GCM/FCM - \ No newline at end of file + + +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`. diff --git a/docs/src/index.md b/docs/src/index.md index 8f8320221..457ac5b37 100644 --- a/docs/src/index.md +++ b/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 ` before proceeding. +[running Autopush](running.md) before proceeding.
@@ -87,19 +87,25 @@ All source code is available on [github under autopush](https://github.com/mozilla-services/autopush-rs). -* 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 diff --git a/docs/src/running.md b/docs/src/running.md index 7702dfa36..693874f2a 100644 --- a/docs/src/running.md +++ b/docs/src/running.md @@ -29,7 +29,10 @@ can be run on separate hosts as well, or with AWS DynamoDB instead. - [ ] - [] define steps here -
+ ### Generate a Crypto-Key