Add some introductory docs for deploying the appservice.

Author: Gnuxie

docs/appservice.md

@@ -0,0 +1,28 @@
+Mjolnir can be run as an appservice, allowing users you trust or on your homeserver to run their own Mjolnir without hosting anything themselves.
+This module is currently alpha quality and is subject to rapid changes,
+it is not recommended currently and support will be limited.
+
+# Prerequisites
+
+This guide assumes you will be using Docker and that you are able to provide a postgres database for Mjolnir to connect to in application service mode.
+
+# Setup
+
+1. Create a new Matrix room that will act as a policy list for who can use the appservice.
+   FIXME: Currently required to be aliased.
+   FIXME: Should really be created and managed by the admin room, but waiting for command refactor before doing that. 
+
+2. Decide on a spare local TCP port number to use that will listen for messages from the matrix homeserver. Take care to configure firewalls appropriately. This port will be notated as `$MATRIX_PORT` in the remaining instructions.
+
+3. Create a config/config.appservice.yaml file that can be copied from the example in `src/appservice/config/config.example.yaml`. Your config file needs to be accessible to the docker container later on.
+
+4. Generate the appservice registration file. This will be used by both the appservice and your homeserver.
+   Here, you must specify the direct link the Matrix Homserver can use to access the appservice, including the Matrix port it will send messages through (if this bridge runs on the same machine you can use localhost as the $HOST name):
+   
+   `docker run -rm -v /mjolnir/data/path:/data matrixdotorg/mjolnir appservice -r -u "http://$HOST:$MATRIX_PORT" -f /data/config/mjolnir-registration.yaml`
+
+5. Invite the application service bot (specified in the registration) to the access control room you made earlier.
+   
+6. Start the application service `docker run -v /path/to/data/:/data/ matrixdotorg/mjolnir appservice -c /data/config/config.appservice.yaml -f /data/config/mjolnir-registration.yaml -p $MATRIX_PORT`
+
+7. Copy the `mjolnir-registration.yaml` to your matrix homeserver and refer to it in `homeserver.yaml`.

src/appservice/AppService.ts

@@ -35,11 +35,11 @@ export class MjolnirAppService {
         this.api = new Api(config.homeserver.url, mjolnirManager);
     }
 
-    public static async makeMjolnirAppService(config: IConfig, dataStore: DataStore) {
+    public static async makeMjolnirAppService(config: IConfig, dataStore: DataStore, registrationFilePath: string) {
         const bridge = new Bridge({
             homeserverUrl: config.homeserver.url,
             domain: config.homeserver.domain,
-            registration: "mjolnir-registration.yaml",
+            registration: registrationFilePath,
             // We lazily initialize the controller to avoid null checks
             // It also allows us to combine constructor/initialize logic
             // to make the code base much simpler. A small hack to pay for an overall less hacky code base.
@@ -112,10 +112,10 @@ export class MjolnirAppService {
         callback(reg);
     }
 
-    public static async run(port: number, config: IConfig) {
+    public static async run(port: number, config: IConfig, registrationFilePath: string) {
         const dataStore = new PgDataStore(config.db.connectionString);
         await dataStore.init();
-        const service = await MjolnirAppService.makeMjolnirAppService(config, dataStore);
+        const service = await MjolnirAppService.makeMjolnirAppService(config, dataStore, registrationFilePath);
         // Can't stress how important it is that listen happens last.
         await service.start(port);
     }

src/appservice/cli.ts

@@ -17,7 +17,7 @@ const cli = new Cli({
         if (config === null) {
             throw new Error("Couldn't load config");
         }
-        await MjolnirAppService.run(port, config);
+        await MjolnirAppService.run(port, config, cli.getRegistrationFilePath());
     }
 });
 

src/appservice/config/config.example.yaml

@@ -0,0 +1,19 @@
+
+homeserver:
+  # The Matrix server name, this will be the name of the server in your matrix id.
+  domain: "localhost:9999"
+  # The url for the appservice to call the client server API from.
+  url: http://localhost:8081
+
+# Database configuration for storing which Mjolnirs have been provisioned.
+db:
+  engine: "postgres"
+  connectionString: "postgres://mjolnir-tester:mjolnir-test@localhost:8083/mjolnir-test-db"
+
+# A room you have created that scopes who can access the appservice.
+# See docs/access_control.md
+accessControlList: "#access-control-list:localhost:9999"
+
+# This is a web api that the widget connects to in order to interact with the appservice.
+webAPI:
+  port: 9001

test/appservice/utils/harness.ts

@@ -16,7 +16,7 @@ export async function setupHarness(): Promise<MjolnirAppService> {
     await ensureAliasedRoomExists(utilityUser, config.accessControlList);
     const dataStore = new PgDataStore(config.db.connectionString);
     await dataStore.init();
-    const appservice = await MjolnirAppService.makeMjolnirAppService(config, dataStore);
+    const appservice = await MjolnirAppService.makeMjolnirAppService(config, dataStore, "mjolnir-registration.yaml");
     await appservice.start(9000);
     return appservice;
 }