feat: improve the README

Closes #59

Author: pjenvey

README.md

@@ -1,21 +1,141 @@
-[![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) [![Test Status](https://travis-ci.org/mozilla-services/megaphone.svg?branch=master)](https://travis-ci.org/mozilla-services/megaphone) [![Build Status](https://circleci.com/gh/mozilla-services/megaphone.svg?style=shield&circle-token=074ae89011d1a7601378c41a4351e1e03f1e8177)](https://circleci.com/gh/mozilla-services/megaphone)
+[![License: MPL 2.0][mpl-svg]][mpl] [![Test Status][travis-badge]][travis] [![Build Status][circleci-badge]][circleci]
 
 # Megaphone
-**A rust based real-time update broadcast server for Firefox**
 
-See [API doc](https://docs.google.com/document/d/1Wxqf1a4HDkKgHDIswPmhmdvk8KPoMEh2q6SPhaz4LNE)
+## What is it?
 
+Megaphone is an internal Mozilla system providing global broadcasts for Firefox.
 
-***NOTE***: This will require:
+Traditionally Firefox has polled (e.g. every 24 hours) various services to check for updates. Megaphone serves as an alternative, delivering updates to user agents in near real time over the [WebPush WebSocket protocol].
 
- * rust nightly. See [rocket.rs Getting
-   Started](https://rocket.rs/guide/getting-started/) for additional steps.
-   To set nightly as the default for only megaphone, from the
-   megaphone directory run: rustup override set nightly
- * mysql
- * libmysqlclient installed (brew install mysql on macOS, apt-get install
-   libmysqlclient-dev on Ubuntu)
+This repository provides a Rust based Megaphone Endpoint (API). New Broadcasts are created via the Megaphone Endpoint. The [autopush-rs service] polls the endpoint as the source of truth for the current broadcasts, ultimately delivering them to user agents.
 
-Run:
-  * export ROCKET_DATABASE_URL=mysql://scott:tiger@mydatabase/megaphone
-  * cargo run
+Also see the [API doc].
+
+
+## Requirements
+
+ * Rust nightly as specified in the **rust-toolchain** file (recognized by cargo) in the root of the project (recognized by cargo).
+ * MySQL 5.7 (or compatible)
+ * libmysqlclient (brew install mysql on macOS, apt-get install libmysqlclient-dev on Ubuntu)
+
+ * *For running the docker image locally: docker-compose v1.21.0 or later
+
+## Setting Up
+
+1) [Install Rust]
+
+2) Create a `megaphone` user/database
+
+3) Run:
+
+  $ export ROCKET_DATABASE_URL=mysql://scott:tiger@mydatabase/megaphone
+  $ cargo run
+
+## Running the Docker Image
+
+1) [Install docker-compose]
+
+2) From a dedicated screen (or tmux window)
+
+$ `docker-compose up`
+
+This will create two intertwined docker images:
+
+***db_1*** - the database image. This image is a local test image. The database can be accessed via `mysql -umegaphone -ptest -h localhost --port 4306 megaphone`.
+
+***app_1*** - the **megaphone** application. This is accessible via port 8000.
+
+
+# API
+
+Megaphone is normally called via a HTTP interface using Authorized calls. Responses are generally JSON objects with appropriate HTTP status codes to indicate success/failure.
+
+## Authorization
+
+All calls to Megaphone (minus the Dockerflow Status Checks) require authorization. Authorization is specified by the `Authorization` header via Bearer tokens specified in the application's configurtion.
+
+e.g.
+
+```
+export ROCKET_BROADCASTER_AUTH={test="foobar"}
+export ROCKET_READER_AUTH={autopush="quux"}
+```
+
+The *test* broadcaster would specify:
+
+```
+Authorization: Bearer foobar
+```
+
+The *autopush* reader would specify:
+
+```
+Authorization: Bearer quux
+```
+
+
+## PUT /v1/broadcasts/< broadcaster_id > /< bchannel_id >
+
+Broadcast a new version.
+
+The body of the PUT request becomes the new version value.
+
+The return value is a JSON structure including the HTTP status of the result: successful results either being a `201` code for newly created broadcasts or `200` for an update to an existing broadcast.
+
+```javascript
+{
+   "code": 200
+}
+```
+
+
+## GET /v1/broadcasts
+
+Read the current broadcasts.
+
+The return value is a JSON structure including the HTTP status of the result and a `broadcasts` object consisting of broadcastIDs and their current versions.
+
+```javascript
+{
+   "code": 200,
+   "broadcasts": {
+      "test/broadcast1": "v3",
+      "test/broadcast2": "v0"
+   }
+}
+```
+
+## Dockerflow Status Checks:
+
+## GET /__heartbeat__
+
+Return the status of the server.
+
+This call is only used for server status checks.
+
+
+## GET /__lbheartbeat__
+
+Return a light weight status check (200 OK).
+
+This call is only used for the Load Balancer's check.
+
+
+## GET /__version__
+
+Return a JSON response of the version information of the server.
+
+
+[mpl-svg]: https://img.shields.io/badge/License-MPL%202.0-blue.svg
+[mpl]: https://opensource.org/licenses/MPL-2.0
+[travis-badge]: https://travis-ci.org/mozilla-services/megaphone.svg?branch=master
+[travis]: https://travis-ci.org/mozilla-services/megaphone
+[circleci-badge]: https://circleci.com/gh/mozilla-services/megaphone.svg?style=shield&circle-token=074ae89011d1a7601378c41a4351e1e03f1e8177
+[circleci]: https://circleci.com/gh/mozilla-services/megaphone
+
+[WebPush WebSocket protocol]: https://mozilla-push-service.readthedocs.io/en/latest/design/#simplepush-protocol
+[autopush-rs service]: https://github.com/mozilla-services/autopush-rs
+[API doc]: https://docs.google.com/document/d/1Wxqf1a4HDkKgHDIswPmhmdvk8KPoMEh2q6SPhaz4LNE
+[Install Rust]: https://rustup.rs/
+[Install docker-compose]: https://docs.docker.com/compose/install/