Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: further clean up #399

Merged
merged 14 commits into from
Oct 23, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 45 additions & 2 deletions docs/src/fcm.md
Original file line number Diff line number Diff line change
@@ -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`.
14 changes: 10 additions & 4 deletions docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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">

Expand Down Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion docs/src/running.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -57,6 +60,7 @@ have the Autopush daemons use other ports.
sure you have appropriate free-space before proceeding.

</div>
-->

### Generate a Crypto-Key

Expand Down