diff --git a/docs/admin/00_index.rst b/docs/admin/00_index.rst new file mode 100644 index 0000000000000000000000000000000000000000..d92917a90c481d1d82ac1d3c3f0a6f718ba30ccf --- /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 0000000000000000000000000000000000000000..d78053d4ed3dcd14ee0a6a59bb19f55b933558c0 --- /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 38d08977e4ea1321e3ca419f75c94d5311a461a4..9f11bde089569f18ec3ad13a5485820bf93dbe7d 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 ==================