Update D4A Documentation to be A LOT better. (#272)

* Update D4A Documentation and add Config Example For Child Bots

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Move AS Inherited config into Docs instead of having example file.

* Integrate Review Feedback.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix spelling mistake and a few its vs it´s style cases.

* Integrate Second Round of Review Feedback

* Update docs/appservice.md

yeah just wack it in Cat

Co-authored-by: Catalan Lover <[email protected]>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Gnuxie <[email protected]>

docs/appservice.md

@@ -2,31 +2,67 @@ Draupnir can be run as an appservice, allowing users you trust or on your homese
 This module is currently alpha quality and is subject to rapid changes,
 it is not recommended currently and support will be limited.
 
+Usage of the [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook-bot-draupnir.md) role for Draupnir for all is recommended instead of trying to deploy Draupnir for all from scratch as much more support is offered when taking this route. Especially if not deviating from defaults.
+
 # Prerequisites
 
 This guide assumes you will be using Docker and that you are able to provide a postgres database for Draupnir to connect to in application service mode.
 
+Please note that Draupnir in appservice mode does not support E2EE nor support use of an E2EE proxy like [pantalaimon](https://github.com/matrix-org/pantalaimon) as there is currently no proxy for appservices like there is for /sync
+
 # Setup
 
-1. Create a new Matrix room that will act as a policy list for who can use the appservice.
+1. Create a new temporarily public Matrix room that will act as a combined Policy List and Management room for 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.
+   FIXME: Should ideally be an Admin Room and a separate Policy list, 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. We will call this port `$MATRIX_PORT` in the remaining instructions.
+2. Give the room from step 1 an alias that you put in your configuration that you will create later. `$MANAGEMENT_ALIAS` is how we will refer to this room in the remaining instructions.
+   FIXME: Make it so we can just invite the bot to the room and give the bot a room ID in it’s config instead. (Inviting the bot to the room makes the bot think you want to provision not just grant it access to it’s own management room.)
 
-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. To do this you could create a directory called `draupnir-data` so we can map it to a volume when we launch the container later on.
+3. 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. We will call this port `$MATRIX_PORT` in the remaining instructions.
 
-4. Generate the appservice registration file. This will be used by both the appservice and your homeserver.
+4. 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. To do this you could create a directory called `draupnir-data` so we can map it to a volume when we launch the container later on. The `$MANAGEMENT_ALIAS` created earlier on is added to this file under the `adminRoom` key in the config. Please note that the whole config is needed to keep Draupnir happy D4A happy. It will crash if any non-commented out in the template part is missing.
+
+5. 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 Homeserver 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 /your/path/to/draupnir-data:/data gnuxie/draupnir appservice -r -u "http://$HOST:$MATRIX_PORT" -f /data/config/draupnir-registration.yaml`
 
-5. Step 4 created an application service bot. This will be a bot iwth the mxid specified in `draupnir-registration.yaml` under `sender_localpart`. You now need to invite it in the access control room that you have created in Step 1.
+6. Create a `config/config.production.yaml` file that can be copied from the example in `config/default.yaml` just like in step 4. The file also needs to be accessible to the container so whatever path is used for `config/config.appservice.yaml` can be reused to also house this file.
 
-6. Start the application service `docker run -v /your/path/to/draupnir-data/:/data/ gnuxie/draupnir appservice -c /data/config/config.appservice.yaml -f /data/config/draupnir-registration.yaml -p $MATRIX_PORT`
+The provisioned Draupnirs only inherit a subset of the configuration options that are accessible to Bot mode Draupnir. Those are the following options. If there's `:` as a suffix to a config option that means there are sub options like how under commands in the default config you also find `additionalPrefixes:` with a value of `draupnir`.
+```
+logLevel
+syncOnStartup
+fasterMembershipChecks
+automaticallyRedactForReasons:
+protectAllJoinedRooms
+backgroundDelayMS
+commands:
+protections:
+```
+
+7. Start the application service `docker run -v /your/path/to/draupnir-data/:/data/ gnuxie/draupnir appservice -c /data/config/config.appservice.yaml -f /data/config/draupnir-registration.yaml -p $MATRIX_PORT --draupnir-config /data/config/production.yaml`
 
-7. Copy the `draupnir-registration.yaml` to your matrix homeserver and refer to it in `homeserver.yaml` like so:
+8. Copy the `draupnir-registration.yaml` to your matrix homeserver and refer to it in `homeserver.yaml` like so:
 ```
   app_service_config_files:
     - "/data/draupnir-registration.yaml"
 ```
+
+# Post Install Setup and Configuration.
+
+If you successfully followed Steps 1-8 or got to the point your running the bot through other means congratulations. Then there are some post install steps and configuration that you should apply to your appservice
+
+1. If your successfully at this point it’s assumed that your `draupnir-moderation` or `draupnir-main` bot is in the admin room (the room with designated by `$MANAGEMENT_ALIAS`). So go back up and follow those steps if you haven't got there yet.
+
+2. Set your appservice management room to private, if you didn't already. Anyone with access to this room can manage access to the appservice, so be careful who you share this with.
+
+3. Decide if you want to allow provisioning per homeserver or per user. If you choose to only provision per user skip to step 5.
+
+4. Allow provisioning per homeserver. To provision per homeserver you write in your control room /plain MXID_OF_APPSERVICE_HERE allow @*:homeserver_to_allow
+
+5. Allow provisioning per user. To Provision per user you write in your control room /plain MXID_OF_APPSERVICE_HERE allow MXID_TO_ALLOW
+FIXME: If the client is being dumb and adding escapes to lone instances of * in the command strip them out so you don't have to mandate /plain use to guarantee the client doesn’t screw the user over.
+
+6. Provisioning a Draupnir is done via inviting your main draupnir into a room. If the user who did it is allowed to Draupnir rejects the invite and provisions a Draupnir shortly and invites the user to the newly created policy list and control room for this Draupnir.