Moodle course rooms with Matrix

The flow starts with three values in Moodle's Matrix communication provider: the homeserver name, the homeserver URL and an access token. The URL is what Moodle uses to connect to the homeserver and create accounts. The access token belongs to the account that performs actions on the homeserver, so whoever controls that account controls what Moodle can do there. The homeserver name is the part that appears after the colon in Matrix IDs, such as @user:example.com. Before rollout, check the exact wording and behavior of these settings in the communication_matrix language strings for the Moodle version your client runs, and decide which account will hold the token and how its credentials are stored and rotated.

Moodle 4.3 introduced the Matrix integration, which makes Matrix available for use in courses and gives administrators controls for room creation. Teachers receive moderation capabilities in the rooms that Moodle manages, so the practical decisions are which roles may create or moderate a room and whether moderation follows the teacher role in the course. Confirm in your version whether a room is created when a course is set up, on first use, or on demand, and whether the rooms sit in the course context or are created by a site-level action. Write these answers down as a permissions matrix, because the room model is what your teachers and auditors will ask about first.

Membership is the part most likely to differ from what your teams expect. Confirm whether a new enrolment adds the user to the course room automatically, whether an unenrolment or role change removes or downgrades membership, and whether any of this flows in one direction only, from Moodle to Matrix. Also confirm how long these changes take to appear and whether a user needs a Matrix account created through the homeserver URL before they can join. Test this on a non-production homeserver with a test course: enrol, change roles and unenrol a set of test users, then compare Moodle enrolments with Matrix membership and moderator rights after each step.

Course end is the other behavior to confirm in writing. Find out whether the room is archived, left open, emptied of members or deleted, and whether message history and files remain accessible to teachers or administrators afterward. The answer determines your retention and export plan, so include a step to check how records are kept before the first live course closes. On the Matrix side, Synapse uses server_name to identify users and rooms, so treat that value as fixed once the homeserver is in use and settle it before any course room is created. If you enable federation, the federation_domain_whitelist setting and firewalling of the federation listener should be part of the same test plan.

The homeserver is the first decision in this design, because Moodle's Matrix communication provider can only work with the server you point it at. The main candidates named in the Matrix ecosystem are Synapse, written in Python and licensed AGPL-3.0-or-later by Element; Dendrite, written in Go and also AGPL-3.0-or-later; and Conduit with its Rust forks Continuwuity and Tuwunel, which are Apache-2.0. Synapse is the most widely documented of these. For a course-chat design, that depth matters because your administrators will need upgrade notes, troubleshooting references and configuration guidance. Documentation depth does not replace a check against the features your course rooms depend on, so test those features on the candidate you select.

Licensing deserves the same attention as features. On December 13, 2023, Element announced that future Synapse contributions would be licensed under AGPLv3 instead of Apache 2.0, moved the repositories from matrix-org to element-hq on GitHub, and began selling AGPL exceptions, with contributors signing a contributor license agreement. AGPL is a copyleft licence with obligations that can apply when users interact with a modified program over a network. Element also offers commercial licences for Synapse. Whether your organization's hosting, internal changes or distribution create obligations is a question for your counsel, and the answer should be in hand before the server stores any course conversations.

Plan for PostgreSQL as the production database. The Synapse documentation recommends PostgreSQL for production and also supports SQLite, but a deployment that serves many courses and staff should not depend on SQLite. The current version floors are firm: Synapse 1.143.0 and later require PostgreSQL 14 or newer, and Synapse 1.142.0 and later require Python 3.10 or newer. Confirm that the operating system packages you intend to use meet both floors. Synapse also drops support for Python and PostgreSQL versions once they reach upstream end of life, so these floors will move during the life of the deployment. The upgrade notes warn that rolling back can be difficult because of database schema changes between releases, so take and test a database backup before every upgrade.

Decide whether the server federates before you configure it. Synapse federates on port 8448 by default, and delegation can serve user IDs such as @user:example.com from another host on port 443. The server_name setting determines how users and rooms are identified, so choose the domain with care. An empty federation_domain_whitelist disables federation, and the configuration documentation recommends firewalling the federation listener as well. For a chat used only by enrolled students and staff, closing federation is a reasonable choice to record with your security team. Confirm with the provider's documentation that this setting does not affect the account and room operations it performs.

Before you fix a version, confirm which homeserver and version Moodle's Matrix provider has been tested against. The provider needs a homeserver name, a homeserver URL for connecting and creating accounts, and an access token for the account that performs actions on the server. A successful test against one homeserver tells you little about another, so ask the Moodle provider's maintainers or your implementation partner for the tested combination. Record the Synapse version, PostgreSQL version, Python version, Moodle version and the provider settings in your design record. Then run a test course against that exact combination before any student is enrolled.

Test the Matrix course rooms in a sandbox course before any student or teacher uses them. Create a sandbox course in a non-production Moodle site connected to a non-production Synapse homeserver, and create at least one teacher account and one student account in the sandbox. Give the teacher account the capability that allows room moderation, and enrol the student through the same method your production courses will use. Keep a written record of the Moodle version, the homeserver name and the account that holds the access token, because those are the settings the Matrix communication provider depends on. Run the core checks in order. First, confirm that a room is created for the sandbox course and that its name and identifiers match what the provider expects. Second, enrol the student and confirm that the student is invited and joins. Third, unenrol the student and confirm that membership is removed on the homeserver, not only hidden in Moodle. Check this from a Matrix client or the Synapse admin API, not from the Moodle interface alone. Fourth, use the teacher account to perform moderator actions such as removing a message or a member, and confirm the results on the homeserver. Finally, confirm that message history is retained for the period your records policy requires, and that a removed student cannot read new messages after unenrolment.

The homeserver needs its own recovery test. Take a backup that covers the PostgreSQL database, the media store and the configuration files, including the signing key material. Restore that backup to a separate host and confirm that the restored server starts, that rooms and memberships appear, and that message history is complete for a sample of rooms. Then point a test Moodle site at the restored homeserver and confirm that the provider can still create rooms with the existing access token. Record how long the restore took on your hardware, because that figure, not a vendor estimate, is what you will plan against for a real incident. Upgrades need a rehearsal on a copy of the database. Restore a recent database dump to a staging Synapse running the same release as production, then apply the upgrade notes for the target release in order. Check the database and runtime requirements before you start. For example, Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer. Repeat the room, invitation, removal and history checks after the upgrade, and time the steps so the production maintenance window is based on measured steps.

Plan rollback before the first upgrade, because the Synapse upgrade notes warn that rolling back can be difficult when database schema changes are involved. Rolling back by installing the previous package is not a reliable recovery path. Take a snapshot of the homeserver host or virtual machine, plus a logical database dump, immediately before each upgrade. Store both where they can be restored independently of the upgraded system. Write down who approves a rollback, which snapshot restores which version, and how Moodle users will be told that course rooms are unavailable during the restore. Before the institution-wide rollout, run a pilot with one department. Pick a department with a small number of active courses, a teacher group willing to report problems, and a named administrator who can check homeserver state. Agree exit criteria in writing before the pilot starts. These should cover membership accuracy after enrolment changes, moderation support, history retention and the restore test. The pilot shows you how many courses are provisioned in practice, what moderators need to be trained on and which policy questions the homeserver settings must answer. Ask any implementation partner to state in the written scope which of these tests they run, which they hand over, and what evidence they provide at the end.