From 84d32ca1e398e9e4354bf4b07882ba3f222cb457 Mon Sep 17 00:00:00 2001
From: Catalan Lover <catalanlover@protonmail.com>
Date: Tue, 5 May 2026 11:45:12 +0200
Subject: [PATCH] Documentation for Zero Touch Deployment

---
 ...ng-playbook-appservice-draupnir-for-all.md | 55 +++++++++++++++----
 docs/configuring-playbook-bot-draupnir.md     | 46 +++++++++++++---
 .../tasks/setup_install.yml                   |  2 +-
 .../tasks/validate_config.yml                 |  2 +-
 4 files changed, 84 insertions(+), 21 deletions(-)

diff --git a/docs/configuring-playbook-appservice-draupnir-for-all.md b/docs/configuring-playbook-appservice-draupnir-for-all.md
index 36e85eafd..6ded40b99 100644
--- a/docs/configuring-playbook-appservice-draupnir-for-all.md
+++ b/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
 
@@ -13,33 +14,55 @@ Appservice mode can be used together with the regular [Draupnir bot](configuring
 
 ## Draupnir Appservice mode compared to Draupnir bot mode
 
-The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
+The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode.
 
-Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All (Even though the commands do show up in help).
+Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All.
 
 Draupnir for all in the playbook is rate-limit-exempt automatically as its appservice configuration file does not specify any rate limits.
 
-Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as D4A even on the branch with the Avatar command (To be Upstreamed to Mainline Draupnir) that command is clunky as it requires the use of things like Element Web devtools. In normal Draupnir this is a quick operation where you login to Draupnir with a normal client and set Avatar and Display name normally.
+Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as the avatar command is clunky as it requires the use of things like Element Web devtools. In normal Draupnir this can be done while logged in to the Draupnir account with a normal client and set Avatar and Display name normally.
 
-Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
+Draupnir for all only has limited support for external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
 
 ## Prerequisites
 
-### Create a main management room
+### Prerequisites for Zero Touch Deployment (Recomended)
 
-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 but the appservice it self can do this. You **can create 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,18 +128,26 @@ 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.
+
+The installation of Draupnir for all in Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
+
+Draupnir for all installation via this playbook is very much Alpha 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
 
 Draupnir for all includes several security measures like that it only allows users that are on its allow list to ask for a bot. To add a user to this list we have 2 primary options. Using the chat to tell Draupnir to do this for us or if you want to automatically do it by sending `m.policy.rule.user` events that target the subject you want to allow provisioning for with the `org.matrix.mjolnir.allow` recommendation. Using the chat is recommended.
 
-The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
+The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297)) This issue is mittigated in large part by Zero Touch Deployment workflows that got introduced in Draupnir 3.1.0
 
-To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
+To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to provision a bot. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
 
 ### 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.
diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md
index 28806adf0..91d4c0589 100644
--- a/docs/configuring-playbook-bot-draupnir.md
+++ b/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 (Recomended)
+
+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.**
@@ -115,6 +150,7 @@ The APIs can also be accessed via [Ketesa](https://github.com/etkecc/ketesa), a
 #### Add the configuration
 
 To expose the APIs publicly, add the following configuration to your `vars.yml` file:
+This is automatically done if Ketesa is enabled.
 
 ```yaml
 matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
@@ -167,11 +203,7 @@ matrix_bot_draupnir_admin_api_enabled: true
 
 These protections need to be manually activated and consulting the [enabling protections](#enabling-built-in-protections) guide can be helpful or consulting upstream documentation.
 
-<!--
-NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
-
 The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
--->
 
 ### Extending the configuration
 
diff --git a/roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml b/roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml
index b594d30ba..d411b7299 100644
--- a/roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml
+++ b/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
 #
diff --git a/roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml b/roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml
index 1afe3d891..4d9b46c99 100644
--- a/roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml
+++ b/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
 #