diff --git a/docs/_static/sync.png b/docs/_static/sync.png new file mode 100644 index 0000000000000000000000000000000000000000..bc38a629d7ee56efa609ec83eab1ea2d17363946 Binary files /dev/null and b/docs/_static/sync.png differ 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/01_intro.rst b/docs/admin/01_intro.rst new file mode 100644 index 0000000000000000000000000000000000000000..37cf3e1d670b5408e7f36d138ac151b8808968b9 --- /dev/null +++ b/docs/admin/01_intro.rst @@ -0,0 +1,16 @@ +Matrix and Element +================== + +`Matrix`_ is "an open network for secure, decentralized communication". +Being an open protocol, it allows independent implementations of servers +and clients to communicate with each other. +Users create their account on a server they choose and are then able to +chat with everyone in the network, just like the e-mail system works. + +The popular reference client `Element`_ with its team communication friendly +user interface is a good choice for schools. +It is available as a mobile app for Android and iOS, and as a web client, +that can be used in a web browser. + +.. _Matrix: https://www.matrix.org/ +.. _Element: https://https://element.io/ diff --git a/docs/admin/02_concepts.rst b/docs/admin/02_concepts.rst new file mode 100644 index 0000000000000000000000000000000000000000..6b54927de0a0f83b790e2027eeabdc9179254937 --- /dev/null +++ b/docs/admin/02_concepts.rst @@ -0,0 +1,14 @@ +Concepts of rooms and spaces +============================ + +In Matrix, every chat is organized as a room, where people can join +to send and receive messages. +Schools can map their real structure to Matrix rooms to provide each +group or course a place to communicate. + +A Space is an organizational layer, that contains multiple rooms and +can even contain other spaces. This is useful for representing child +and parent group relationships. + +When the Spaces feature is enabled, AlekSIS will create a space for +e.g. class 5a that contains the rooms 5a English, 5a Maths etc.. diff --git a/docs/admin/10_configuration.rst b/docs/admin/10_configuration.rst new file mode 100644 index 0000000000000000000000000000000000000000..21f8080e35ee6eddee122878dc188d17f8814799 --- /dev/null +++ b/docs/admin/10_configuration.rst @@ -0,0 +1,60 @@ +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. + +After that, do not log out of Element, because that would invalidate the access token. +You might want to use a private tab in your browser or clear session data afterwards. + +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/admin/20_syncing.rst b/docs/admin/20_syncing.rst new file mode 100644 index 0000000000000000000000000000000000000000..0273133e634ffb4a575e6206e015ee0612cae019 --- /dev/null +++ b/docs/admin/20_syncing.rst @@ -0,0 +1,17 @@ +Synchronizing with Matrix +========================= + +To initially start the synchronization of groups in AlekSIS to rooms, +and optionally spaces, to Matrix, go to ``Matrix → Groups and Rooms``. + +Select the groups to be synchronized and click ``Execute``. +This process can take some time. +All group members that have a Matrix profile in AlekSIS, that may be automatically +created when a ``Name of Matrix homeserver user for auto-generating Matrix IDs`` is set, +get invited to the respective rooms. + +.. image:: ../_static/sync.png + :alt: Synchronizing AlekSIS with Matrix + +After this initial synchronization, every change in a ``Group``, ``Matrix room`` or +``Matrix profile`` will be refleceted in Matrix. 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 ==================