Improve doc for docker installations

changelog.d/305.doc

@@ -0,0 +1 @@
+Add some documentation about PostgreSQL, for installing with docker, fix typos

docs/datastores.md

@@ -2,7 +2,10 @@ Datastores
 ==========
 
 Version 1.0+ supports using PostgreSQL as a storage backend instead of the
-deprecated NeDB storage backend. 
+deprecated NeDB storage backend.
+The required version of PostgreSQL is at least 9.5, but we recommend using the lastest stable version
+available to you. Follow the installation instructions on the [official website](https://www.postgresql.org/download/)
+or pull a [docker container](https://hub.docker.com/_/postgres).
 
 Using PostgreSQL
 ----------------
@@ -28,6 +31,13 @@ db:
 
 Ensure that `dbdir` is not included in the config.
 
+Note: depending on your environment, the default PostgreSQL configuration might be set up such that it can be
+reached only from localhost. Make sure it is reachable from your bridge installation. If necessary, set up
+[`listen_addresses`](https://www.postgresql.org/docs/current/runtime-config-connection.html) and
+[authentication](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html) for your needs.
+
+Remember to choose conservative options to ensure security of your database!
+
 NeDB End-of-life
 --------
 

docs/getting_started.md

@@ -8,6 +8,7 @@ the `config.sample.yaml` file.
 
 These instructions assume you are using Synapse 1.4.0+. They should
 work for older releases and other homeservers, but configuration may vary.
+The bridge also requires a database, for more information see [datastores](datastores.md).
 
 ### From source
 
@@ -59,6 +60,9 @@ ever stuck, you can post a question in the
 3. Create a `config.yaml` file for global configuration. There is a sample
    one to begin with in `config/config.sample.yaml`. You should copy and
    edit as appropriate. The required and optional values are flagged in the config.
+
+   If using docker, put this file in a new `config` directory which we will later
+   mount to the container.
 
 4. See [datastores](datastores.md) on how to setup a database with the bridge.
 
@@ -72,16 +76,21 @@ ever stuck, you can post a question in the
    or with docker:
 
 ```sh
-$ docker run -v /path/to/config/:/config/ matrixdotorg/matrix-appservice-slack \ 
-    -r -c /config/config.yaml -u "http://$HOST:$MATRIX_PORT" -f /config/slack.yaml
+$ docker run --network=host -v /path/to/config/:/config/ matrixdotorg/matrix-appservice-slack \ 
+    -r -c /config/config.yaml -u "http://$HOST:$MATRIX_PORT" -f /config/slack-registration.yaml
 ```
 
 6. Start the actual application service:
 
     `$ npm start -c config.yaml -p $MATRIX_PORT`
    or with docker:
 
-    `$ docker run -v /path/to/config/:/config/ matrixdotorg/matrix-appservice-slack`
+    `$ docker run --network=host -d -v /path/to/config/:/config/ matrixdotorg/matrix-appservice-slack`
+
+    (Note: `--network=host` will expose the container directly to the host's network, i.e. you will be able to use
+    localhost just as if you're running the node app. If you want to use the default network bridge mode,
+    you will have to configure the config files, port forwarding, firewalls and your database server to
+    traverse the network bridge.)
 
 7. Copy the newly-generated `slack-registration.yaml` file to your Matrix
    homeserver. Add the registration file to your homeserver config (default

src/Main.ts

@@ -886,7 +886,7 @@ export class Main {
                 teamId = await this.clientFactory.upsertTeamByToken(opts.slack_bot_token);
                 log.info(`Found ${teamId} for token`);
             } catch (ex) {
-                log.error("Failed to action link because the token couldn't used:", ex);
+                log.error("Failed to action link because the token couldn't be used:", ex);
                 throw Error("Token did not work, unable to get team");
             }
         }