Vastly improve README

.gitignore

@@ -1,3 +1,7 @@
 node_modules/
 lib/
+
 config.yml
+*.pem
+registration.yml
+tsconfig.tsbuildinfo

README.md

@@ -1,6 +1,63 @@
 matrix-github
 =============
 
-Come chat to us in ![#github-bridge:half-shot.uk](https://matrix.to/#/#github-bridge:half-shot.uk)
+[![#github-bridge:half-shot.uk](https://img.shields.io/matrix/github-bridge:half-shot.uk.svg?server_fqdn=matrix.half-shot.uk&label=%23github-bridge:half-shot.uk&logo=matrix)](https://matrix.to/#/#github-bridge:half-shot.uk)
 
-This needs a description
+
+This bridge enables users to join Github issues and PRs through Matrix and collaborate using rooms.
+
+## Setup
+
+To set up the bridge, simply clone this repository.
+
+` git clone git@github.com:Half-Shot/matrix-github.git`
+
+then you will need to install dependencies
+
+```bash
+cd matrix-github
+npm i # Or "yarn"
+```
+
+Then you will need to copy the `config.sample.yml` to a new file called `config.yml`. You should fill this in. Pay **close** attention to settings like `passkey` which are required for the bridge to function.
+
+For the GitHub tokens, you will need to create a new [GitHub App](https://github.com/settings/apps/new)
+
+You will need to allow access to your bridge instance via a public URL, and fill in the Webhook URL option on GitHub. You will need to also generate a secret key which can be anything, but should be long and unique.
+
+Additionally, you will need to setup some permissions in "Permissions & events".
+
+Largely, these need to be:
+
+- Repository contents: "Read-only"
+- Issues: "Read-only"
+- Pull-requests: "Read-only"
+
+You will also need to subscribe to, at a minimum:
+
+- Issues
+- Label
+- Issue comment
+- Pull request
+- Pull request review
+- Pull request review comment
+
+Once that is setup, you will need to create a registration file for the bridge. Copy `registration.sample.yml` into `registration.yml` and fill in. You are nearly done! Copy or link the registration.yml file to your homeserver in some way, and reconfigure your homeserver to use it. Ensure you have restarted your homeserver if needed (Synapse needs this).
+
+## Running
+
+You can run `npm run start:app` to start the app.
+
+
+## Running in multi-process mode.
+
+If you are running as a non-monolith, then you should also run `npm run start:webhooks`. In the case of the latter, ensure a Redis instance is running. 
+
+You can quickly setup a redis by either installing it from your system package manager, or just running
+
+`docker run --name github-bridge-redis -p 6379:6379 -d redis`
+
+in Docker.
+## Contact
+
+TODO...

config.sample.yml

@@ -3,8 +3,25 @@ github:
   webhook:
     secret: webhooksecret
     port: 7775
+    bindAddress: 0.0.0.0
+  userTokens: 
+    # If you want to hardcode a users token in the config
+    - "@hardcoded:localhost": "foobarbaz"
+  # This is used to securely store passwords.
+  # Run openssl genpkey -out passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:4096
+  passFile: "passkey.pem"
 bridge:
+  # Homeserver servername
   domain: example.com
+  # Homeserver (internal) url
   url: http://localhost:8008
+  # This is your public facing url where media is served from
+  mediaUrl: http://example.com/
   port: 9993 # Port the appservice is binding to
-  bindAddress: 127.0.0.1 # Not the port the appservice is binding to
+  bindAddress: 127.0.0.1 # Address to bind to
+queue:
+  monolithic: true # If this is false, use a Redis server as a queue.
+  port: 6379 # Port for the redis server, omit for 6379
+  host: localhost # Port for the redis server, omit for localhost
+logging:
+  level: "info" # One of "debug", "info", "warn", "error"

registration.sample.yml

@@ -0,0 +1,15 @@
+id: matrix-github # This can be anything, but must be unique within your homeserver
+as_token: aaaaaaaaaa # This again can be a random string
+hs_token: aaaaaaaaaa # ..as can this
+namespaces:
+  rooms: []
+  users:
+    - regex: "@_github_.*:foobar" # Where foobar is your homeserver's domain
+      exclusive: true
+  aliases:
+    - regex: "#github_.+_.+_\\d+:foobar"  # Where foobar is your homeserver's domain
+      exclusive: true
+
+sender_localpart: github
+url: "http://localhost:9993" # This should match the bridge.port in your config file
+rate_limited: false