Update documentation (#1129)

I wrote a new readme and contributing guidelines, and took a rough pass through the rest of the documentation.

doc/gh-badges.md

@@ -0,0 +1,51 @@
+Format
+------
+
+The format is the following:
+
+```js
+{
+  text: [ 'build', 'passed' ],  // Textual information shown, in order
+
+  format: 'svg',  // Also supports json
+
+  colorscheme: 'green',
+  // or ...
+  colorA: '#555',
+  colorB: '#4c1',
+
+  // See templates/ for a list of available templates.
+  // Each offers a different visual design.
+  template: 'flat',
+}
+```
+
+### See also
+
+- [colorscheme.json](lib/colorscheme.json) for the `colorscheme` option
+- [templates/](templates) for the `template` option
+
+
+Defaults
+--------
+
+If you want to add a colorscheme, head to `lib/colorscheme.json`. Each scheme
+has a name and a [CSS/SVG color][] for the color used in the first box (for the
+first piece of text, field `colorA`) and for the one used in the second box
+(field `colorB`).
+
+[CSS/SVG color]: http://www.w3.org/TR/SVG/types.html#DataTypeColor
+
+```js
+"green": {
+  "colorB": "#4c1"
+}
+```
+
+Both `colorA` and `colorB` have default values. Usually, the first box uses the
+same dark grey, so you can rely on that default value by not providing a
+`"colorA"` field (such as above).
+
+You can also use the `"colorA"` and `"colorB"` fields directly in the badges if
+you don't want to make a color scheme for it. In that case, remove the
+`"colorscheme"` field altogether.

doc/production-hosting.md

@@ -0,0 +1,38 @@
+Production hosting
+==================
+
+Server secrets
+--------------
+
+Some services require the use of secret tokens or passwords. Those are stored
+in `private/secret.json` which is not checked into the repository.
+
+These settings are currently set on the production server:
+
+- bintray_apikey
+- bintray_user
+- gh_client_id
+- gh_client_secret
+- gh_token
+- gitter_dev_secret
+- shieldsIps
+- shieldsSecret
+- sl_insight_apiToken
+- sl_insight_userUuid
+
+(Gathered from `cat private/secret.json | jq keys | grep -o '".*"' | sed 's/"//g'`.)
+
+The `secret.tpl.json` is a template file used by the Docker container to set the secrets based on
+environment variables.
+
+Main Server Sysadmin
+--------------------
+
+- Servers in DNS round-robin:
+  - s0: 192.99.59.72 (vps71670.vps.ovh.ca)
+  - s1: 51.254.114.150 (vps244529.ovh.net)
+  - s2: 149.56.96.133 (vps117870.vps.ovh.ca)
+- Self-signed TLS certificates, but `img.shields.io` is behind CloudFlare, which provides signed certificates.
+- Using systemd to automatically restart the server when it crashes.
+
+See https://github.com/badges/ServerScript for helper admin scripts.

doc/self-hosting.md

@@ -0,0 +1,106 @@
+Hosting your own Shields server
+===============================
+
+Installation
+------------
+
+You will need version 6 of Node.js, which you can install using a
+[package manager][].
+
+On Ubuntu / Debian:
+
+```sh
+curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -; sudo apt-get install -y nodejs
+```
+
+```sh
+git clone https://github.com/badges/shields.git
+cd shields
+npm install  # You may need sudo for this.
+```
+
+[package manager]: https://nodejs.org/en/download/package-manager/
+
+
+Build the index
+---------------
+
+Build the "real" index page:
+
+```sh
+make website
+```
+
+
+Start the server
+----------------
+
+```sh
+sudo node server
+```
+
+The server uses port 80 by default, which requires `sudo` permissions.
+
+There are two ways to provide an alternate port:
+
+```sh
+PORT=8080 node server
+node server 8080
+```
+
+The root gets redirected to https://shields.io.
+
+For testing purposes, you can go to `http://localhost/try.html`.
+
+
+Heroku
+------
+
+Once you have installed the [Heroku Toolbelt][]:
+
+```bash
+heroku login
+heroku create your-app-name
+heroku config:set BUILDPACK_URL=https://github.com/mojodna/heroku-buildpack-multi.git#build-env
+cp /path/to/Verdana.ttf .
+make deploy
+heroku open
+```
+
+[Heroku Toolbelt]: https://toolbelt.heroku.com/
+
+
+Docker
+------
+
+You can build and run the server locally using Docker. First build an image:
+
+```console
+$ docker build -t shields .
+Sending build context to Docker daemon 3.923 MB
+…
+Successfully built 4471b442c220
+```
+
+Optionally, create a file called `shields.env` that contains the needed
+configuration. See [shields.example.env][shields.example.env] for an example.
+
+Then run the container:
+
+```console
+$ docker run --rm -p 8080:80 --env-file shields.env --name shields shields
+
+> gh-badges@1.1.2 start /usr/src/app
+> node server.js
+
+http://[::1]:80/try.html
+```
+
+Assuming Docker is running locally, you should be able to get to the
+application at http://localhost:8080/try.html.
+
+If you run Docker in a virtual machine (such as boot2docker or Docker Machine)
+then you will need to replace `localhost` with the IP address of that virtual
+machine.
+
+[shields.example.env]: ../shields.example.env