Documentation for Zero Touch Deployment

Author: FSG-Cat

docs/configuring-playbook-appservice-draupnir-for-all.md

@@ -1,4 +1,5 @@
 <!--
+SPDX-FileCopyRightText: 2024,2026 Catalan Lover <catalanlover@protonmail.com>
 SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 MDAD project contributors
 
@@ -25,21 +26,43 @@ Draupnir for all does not support external tooling like [MRU](https://mru.rory.g
 
 ## Prerequisites
 
-### Create a main management room
+### Prerequisites for Zero Touch Deployment
 
-The playbook does not create a management room for your Main Draupnir. You **need to create the room manually** before setting up the bot.
+Zero Touch Deployment of Draupnir Appservice Mode (Draupnir for all) requires as of Draupnir 3.1.0 that you supply Draupnir the following:
+
+ - MXID of the the first person who gets invited to the admin room the bot creates for you.
+
+That is all. The appservice manages everything on its own after you provide it a MXID to invite.
+
+If proceeding with Zero Touch Deployment proceed to [Adjusting the playbook configuration](#adjusting-the-playbook-configuration)
+
+### Create a admin room (Optional)
+
+The playbook does not create a admin room for your Admin Draupnir. You **need to create the room manually** before setting up the bot.
 
 Note that the room must be unencrypted.
 
-The management room has to be given an alias, and your bot has to be invited to the room.
+The admin room has to be given an alias, and your bot has to be invited to the room.
 
-This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
+This admin room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
 
 > [!WARNING]
 > Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
 
 ## Adjusting the playbook configuration
 
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE`.
+
+```yaml
+matrix_appservice_draupnir_for_all_enabled: true
+
+matrxi_appservice_draupnir_for_all_zero_touch_deployment: true
+
+matrix_appservice_draupnir_for_all_config_initialManager: "INITIAL_MANAGER_MXID_HERE"
+```
+
+If opting out of Zero Touch deployment use the following configuration block instead.
+
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE`.
 
 ```yaml
@@ -105,7 +128,9 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
 If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have successfully installed Draupnir for All and can now start using it.
 
-The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
+If using Zero Touch Deployment the flow will be reversed and the success signal is the initial manager account being invited to the admin room.
+
+Draupnir for all installation via the playbook used to be alpha quality, but due to refinements it's now at production quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode, except that protections requiring homeserver admin access are not available, and the config file is shared between all bots so legacy protections like wordlist share a single global config.
 
 ### Granting Users the ability to use D4A
 
@@ -117,6 +142,10 @@ To allow users or whole homeservers you type /plain !admin allow `target` and ta
 
 ### How to provision a D4A once you are allowed to
 
-To provision a D4A, you need to start a chat with `@draupnir-main:example.com`. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
+Once someone is allowed to provision a bot. Simply provision them one with `!admin provision MXID`.
+Self Service Provisioning is disabled as a security feature due to it being bugged. Force Provisioning bypasses this disabled status.
+
+Please note that the reason you should always make sure there is an allow entry matching whoever is provisioned is that when
+self service gets fixed the bot of anyone who is not allowed to provision a bot will refuse to start.
 
 Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.

docs/configuring-playbook-bot-draupnir.md

@@ -1,4 +1,5 @@
 <!--
+SPDX-FileCopyRightText: 2023 - 2026 Catalan Lover <catalanlover@protonmail.com>
 SPDX-FileCopyrightText: 2023 - 2025 MDAD project contributors
 SPDX-FileCopyrightText: 2023 Kim Brose
 SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
@@ -19,7 +20,17 @@ If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [
 
 ## Prerequisites
 
-### Create a management room
+### Prerequisites for Zero Touch Deployment
+
+Zero Touch Deployment of Draupnir bot mode requires as of Draupnir 3.1.0 that you supply Draupnir the following:
+
+ - MXID of the the first person who gets invited to the management room the bot creates for you.
+ - Permanent access token for authentication. Instructions for obtaining one can be found at [obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl)
+ - User account for Draupnir
+
+Zero Touch Deployment is the officially preferred installation method for new deployments of Draupnir as of 3.1.0
+
+### Create a management room (optional)
 
 Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room.
 
@@ -28,6 +39,8 @@ Using your own account, create a new invite only room that you will use to manag
 
 It is possible to make the management room encrypted (E2EE). If doing so, then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
 
+E2EE Support for the management room is mutually exclusive with Zero Touch Deployment of Draupnir.
+
 Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
 
 ## End-to-End Encryption support
@@ -63,7 +76,23 @@ matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
 
 ## Adjusting the playbook configuration
 
-To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created earlier.
+To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE` with the MXID for whoever is to be invited to the management room first.
+
+
+```yaml
+# Enable Draupnir
+matrix_bot_draupnir_enabled: true
+
+matrix_bot_draupnir_zero_touch_deploy: true
+
+matrix_bot_draupnir_config_initialManager: "INITIAL_MANAGER_MXID_HERE"
+
+# Access token which the bot will use for logging in.
+# Comment out `matrix_bot_draupnir_login_native` when using this option.
+matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
+```
+
+If wanting to have the bot manage its own login at the cost of having to create a management room you can use login native and the config block below.
 
 ```yaml
 # Enable Draupnir
@@ -90,7 +119,7 @@ This is due to the conditional restart logic not being able to reliably tell whe
 
 Conditional restarts work correctly for all tags when running only one of these two operating modes.
 
-### Create and invite the bot to the management room
+### Create and invite the bot to the management room (if using login native and not using Zero Touch Deployment)
 
 Before proceeding to the next step, run the playbook with the following command to create the bot user.
 
@@ -102,6 +131,12 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
 
+### Creating user account for the bot
+
+Since Zero Touch Deployment is not validated with login native we will create the user account manually.
+
+Refer to [registering users](registering-users.md) for documentation on how to configure the user account.
+
 ### Make sure the account is free from rate limiting (optional, recommended)
 
 If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a highly recommended step. If you do not configure it, Draupnir performance will be degraded.**

roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml

@@ -1,6 +1,6 @@
 # SPDX-FileCopyrightText: 2024 David Mehren
 # SPDX-FileCopyrightText: 2024 MDAD project contributors
-# SPDX-FileCopyrightText: 2024 Catalan Lover <catalanlover@protonmail.com>
+# SPDX-FileCopyrightText: 2024, 2026 Catalan Lover <catalanlover@protonmail.com>
 # SPDX-FileCopyrightText: 2024 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2024 Suguru Hirahara
 #

roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2024 MDAD project contributors
-# SPDX-FileCopyrightText: 2024 Catalan Lover <catalanlover@protonmail.com>
+# SPDX-FileCopyrightText: 2024, 2026 Catalan Lover <catalanlover@protonmail.com>
 # SPDX-FileCopyrightText: 2024 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2025 Suguru Hirahara
 #