Update README to RST. Update documentation.

README.rst

@@ -0,0 +1,161 @@
+SlackBridge
+===========
+
+SlackBridge bridges Slack.com #channels between companies.
+
+* *Does your company use Slack?*
+* *Does your customer/subcontractor also use slack?*
+
+Then, no more hard times of having to grant each others' workers access
+on both Slack teams: you can now form a union between two of your Slack
+#channels using this bridge.
+
+
+Configuration and setup
+-----------------------
+
+You'll need to run this as a daemon on a publicly reachable IP:
+
+* Test it in the foreground from the command line, to get a poor mans
+  builtin http server. You can use the nginx ``proxy_pass`` directive
+  (without path) to reach it.
+* Run it as a WSGI application. Has been tested with uWSGI; you can
+  use the nginx ``uwsgi_pass`` directive to reach it. Multiple workers
+  are allowed, as long as it is single-threaded.
+
+Configuration in Slack:
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* Create at least one `Incoming WebHook
+  <https://my.slack.com/services/new/incoming-webhook>`_ per Slack
+  team; record *the URL*.
+  (Tip: set the other relation's brand logo as default icon, or a
+  generic ``:speech_balloon:`` icon if you use it for multiple
+  channels.)
+* For *each* #channel that you want to bridge/share, create an
+  `Outgoing WebHook
+  <https://my.slack.com/services/new/outgoing-webhook>`_, record the
+  *token*. Set the WebHook POST URL to where this bridge is reachable
+  from the world, and append ``/outgoing`` to the path.
+* And, preferably, you'll also need at least one WebAPI token to
+  supply some info to the other end. You can do this by `creating a
+  bot user <https://my.slack.com/services/new/bot>`_ (call it
+  *@slackbridge*). Record the *API token*.
+  (Previously, the recommended token was a "user token", which is now
+  `legacy <https://api.slack.com/custom-integrations/legacy-tokens>`_.)
+
+Inifile configuration:
+~~~~~~~~~~~~~~~~~~~~~~
+
+Configuration using an inifile would look like this (skip if you're
+using Heroku)::
+
+    [yourcompany-othercompany]
+    A.webhook_out_token = <the-recorded-token>
+    A.webhook_in_url = <the-recorded-url>
+    A.channel = #<channel-you-wish-to-share>
+    A.peername = othercompany
+    A.webapi_token = <xoxb-bot-token-goes-here>
+
+The other side of the SlackBridge has to do the same "Configuration in
+Slack" steps as seen above. Those values should go into a second set of
+key-value pairs, starting with ``B``::
+
+    B.webhook_out_token = <the-peers-recorded-token>
+    B.webhook_in_url = <the-peers-recorded-url>
+    B.channel = #<channel-they-wish-to-share>
+    B.peername = yourcompany
+    B.webapi_token = <xoxb-their-bot-token-goes-here>
+
+The inifile will be searched as ``./slackbridge.ini`` or in the location
+supplied by the ``SLACKBRIDGE_INIFILE`` environment variable.
+
+You can add extra sections for more bridges. See the ``sample.ini``
+example configuration for more details.
+
+Environment variable (Heroku style) configuration:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of doing inifile config, you can use environment variables.
+
+In that case, instead of the ``A`` and ``B`` config as seen above, you'd
+set these for both ``A`` and ``B``::
+
+    PORTAL_1_SIDE_A_WEBHOOK_OUT_TOKEN=
+    PORTAL_1_SIDE_A_WEBHOOK_IN_URL=
+    PORTAL_1_SIDE_A_CHANNEL_NAME=
+    PORTAL_1_SIDE_A_GROUP_NAME=
+    PORTAL_1_SIDE_A_WEB_API_TOKEN=
+
+You can increment the number ``1`` for more bridges. See the
+``sample.env`` example configuration for more details.
+
+
+Inner workings
+--------------
+
+The SlackBridge works like this:
+
+* The Slack *Outgoing WebHook* -- from both teams -- posts messages to
+  the slackbridge on the supplied ``/outgoing`` URL.
+* The bridge posts the message to a subprocess, so the main process
+  can return immediately.
+* The subprocess translates the values from the *Outgoing WebHook* to
+  values for the *Incoming WebHook*, optionally overwriting the
+  #channel name and some other translations (channel name, avatars,
+  @mentions).
+* The translated values get posted to the *Incoming WebHook URL* so
+  they end up on the other end of the bridge.
+
+Supported commands by the bot -- type it in a bridged channel and get
+the response there:
+
+* ``!info`` lists the users on both sides of the bridge. Now you know
+  who you can @mention.
+
+
+Heroku
+------
+
+These instructions require `Heroku Command Line
+<https://devcenter.heroku.com/articles/heroku-command-line>`_::
+
+    heroku create
+    cp sample.env .env
+    # Properly set all environment variables in file
+    vim .env
+    # Test running the bridge locally
+    heroku local
+    # Push environment variables to Heroku
+    heroku config:push --overwrite
+    # Deploy to Heroku
+    git push heroku <my-branch>
+
+Things to note:
+
+* Free Heroku dynos can only run 18 hours per day. After that, the
+  slack bridge will simply not work. This can be very confusing. You
+  may wish to consider paying $7/month for a 24h dyno.
+* Please see ``sample.env`` for an example of how to set environment
+  variables.
+
+
+BUGS / CAVEATS
+--------------
+
+* You can skip the WebAPI token, but @mentions will look awkward and
+  ``!info`` won't give you all the info.
+* Message edits and snippet/file/image uploads will not get sent
+  across the bridge.
+
+
+TODO
+----
+
+* Clean up code (ugly globals). Too few subclasses.
+* Make more extensible. You may want to integrate your own
+  slackbot-style responses here.
+* Add default icon to CONFIG, so we can reuse the same incoming
+  webhook for more than one team, even if they don't supply the
+  wa_token.
+* Clean up the config. It's a horrible mess as it is.

requirements.txt

@@ -1 +1,2 @@
+# Needed for Heroku, not for regular uWSGI setup.
 gunicorn==19.6.0

sample.env

@@ -7,7 +7,7 @@ PORTAL_1_SIDE_A_WEBHOOK_OUT_TOKEN=xxxxxxxxxxx1
 PORTAL_1_SIDE_A_WEBHOOK_IN_URL=https://hooks.slack.com/services/xxxxxxxxxxx1
 PORTAL_1_SIDE_A_CHANNEL_NAME=portal-yowcivictech
 PORTAL_1_SIDE_A_GROUP_NAME=yowcivictech
-PORTAL_1_SIDE_A_WEB_API_TOKEN=xoxp-xxxxxxxxxxx1
+PORTAL_1_SIDE_A_WEB_API_TOKEN=xoxb-xxxxxxxxxxx1
 
 # YOWCivicTech Slack
 PORTAL_1_SIDE_B_WEBHOOK_OUT_TOKEN=xxxxxxxxxxx2

sample.ini

@@ -15,7 +15,7 @@
 ; [DEFAULT]
 ; WEBHOOK_IN_URL = https://hooks.slack.com/services
 ; WEBHOOK_IN_URL_OSSO = ${WEBHOOK_IN_URL}/X/Y/Z
-; WEBAPI_TOKEN_OSSO = xoxp-token-token-token
+; WEBAPI_TOKEN_OSSO = xoxb-token-token-token
 ;
 ; [company1-osso]
 ; A.webhook_in_url =

slackbridge/config/data.py

@@ -20,7 +20,7 @@ class BridgeEndConfig(object):
     #   'othercompany'
     PEERNAME = None
     # WebAPI token for information gathering:
-    #   'xoxp-0123456789-0123456789-0123456789-abcdef'
+    #   'xoxb-0123456789-0123456789-0123456789-abcdef'
     WEBAPI_TOKEN = None