From 44db172cdeda303c0f399c69b065d505a4201f24 Mon Sep 17 00:00:00 2001
From: magicfelix <felix@felix-zauberer.de>
Date: Tue, 21 Jun 2022 15:36:59 +0200
Subject: [PATCH] [Docs] Add config instructions

---
 docs/admin/00_index.rst         |  7 ++++
 docs/admin/10_configuration.rst | 57 +++++++++++++++++++++++++++++++++
 docs/index.rst                  |  2 ++
 3 files changed, 66 insertions(+)
 create mode 100644 docs/admin/00_index.rst
 create mode 100644 docs/admin/10_configuration.rst

diff --git a/docs/admin/00_index.rst b/docs/admin/00_index.rst
new file mode 100644
index 0000000..d92917a
--- /dev/null
+++ b/docs/admin/00_index.rst
@@ -0,0 +1,7 @@
+Setting up Matrix synchronization
+=================================
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/docs/admin/10_configuration.rst b/docs/admin/10_configuration.rst
new file mode 100644
index 0000000..d78053d
--- /dev/null
+++ b/docs/admin/10_configuration.rst
@@ -0,0 +1,57 @@
+Configuring Matrix connection
+=============================
+
+To connect AlekSIS to Matrix, an Account on a Matrix homeserver is required.
+Most homeservers of schools will not have open registration, so the process of
+creating an account depends on the school's setup.
+
+Extracting the access token from Element Web
+--------------------------------------------
+
+Log in to the Matrix account intended to use for AlekSIS synchronization and
+open the settings via ``Profile picture → All Settings``.
+Go to the tab ``Help & About`` and expand ``Access Token`` in the ``Advanced`` section.
+The access token will be displayed and can be copied.
+
+Creating a new user via open registration
+-----------------------------------------
+
+To create rooms and spaces and manage their participants,
+AlekSIS needs to have a Matrix user that can be created using ``curl``::
+
+  curl -XPOST -d '{"username":"aleksis", "password":"randomlygenerated", "auth": {"type":"m.login.dummy"}}' "https://example.org/_matrix/client/r0/register"
+
+When the registration succeeds, a Matrix ID (user_id) and an access token will be returned::
+
+  {
+    "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.AqdSzFmFYrLrTmteXc",
+    "home_server": "example.org",
+    "user_id": "@aleksis:example.org"
+  }
+
+Connecting AlekSIS to the Matrix user
+-------------------------------------
+
+In AlekSIS, go to ``Admin → Configuration → Matrix``.
+Fill in the URL of the Matrix homeserver and the previously extracted access token.
+
+Setting up auto-generated Matrix IDs for AlekSIS users
+------------------------------------------------------
+
+For dedicated Matrix homeservers that use AlekSIS as a SSO provider
+or use the same SSO provider or user database, e.g. LDAP, AlekSIS can
+automatically generate Matrix IDs for its users based on the username.
+
+To enable this feature, provide a value for ``Name of Matrix homeserver user for auto-generating Matrix IDs``.
+
+Configuring synchronization
+---------------------------
+
+AlekSIS' Matrix synchronization creates Matrix rooms for every group and invites the respective users.
+Details of the synchronization can be customized with the remaining config options:
+
+* **Disambiguate room aliases**: Room aliases are built from the group's short name or name. To avoid name collisions, a suffix will be added when this option is enabled.
+* **Use Spaces**: Matrix supports grouping of rooms in so-called spaces. In a school context that can be used to create a space for each class containg rooms for all their subjects, i.e. child groups in AlekSIS.
+* **Power level for owners**: Specifies the Matrix room power level for group owners.
+* **Power level for members**: Specifies the Matrix room power level for group members.
+* **Reduce existing power levels**: For existing Matrix rooms that are going to be managed by AlekSIS, power levels can be overwritten by AlekSIS to match the previously defined power levels.
diff --git a/docs/index.rst b/docs/index.rst
index 38d0897..9f11bde 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,8 @@ Welcome to AlekSIS-App-Matrix' documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   admin/00_index
+
 Indices and tables
 ==================
 
-- 
GitLab