Common operations on X-as-a-Service


Ask @Timothée Floure for help if needed.

Contact customer for setup informations

Do not forget to replace $CUSTMER!


I will deploy your Matrix homeserver and need a few configuration details from
you. I do not know how familiar you are with Matrix or technical terms:
do not hesitate to tell me if I go to fast or to slow for you.

First of all, each Matrix homeserver is linked to domain name (you users will look
like `@username:domain.tld`) for federation. I can offer you two options here,
but remember that the chosen domain name cannot be changed afterward:

  * Your own domain (e.g. domain.tld).
  * One domain controlled by ungleich (e.g. $,

Secondly, I will deploy a Riot web matrix client for convenience (you can use
the desktop or smartphone clients as well) and need a domain for that as well:

  * Your own domain (e.g. matrix.domain.tld)
  * One domain controlled by ungleich (e.g. matrix.$

Lastly, I will configure the Matrix homeserver for you. You can ask us to set
any configuration option but we at least need to know your preferences in term
of registration:
  * Should it be backed by an existing user directory (LDAP)?
  * Should registrations be filtered by domain of email address? (e.g. anyone
    with a @domain.tld email address can register).
  * Should anyone be allowed to register?

Feel free to ask me any matrix-related question, as I am a heavy matrix user

Best Regards,


Deploy new MaaS instance

Note: synapse and riot extra parameters are documented in the __matrix_synapse and __matrix_riot types.

  • Contact customer to get configuration details (this might take some time => do it first).
  • Allocate VM in OpenNebula, based on Debian 10 (IPv6Only).
  • Attach HDD storage to created VM (Help: Common operations at DCLIPv6OnlyHosting).
    - Create EXT4 filesystem: mkfs.ext4 $DEVICE
    - Add FSTAB entry for /var on $DEVICE.
    - Get UUID with blkid.
    - Should look like: UUID=$MY_UUID /var ext4 errors=remount-ro 1 2
    - Mount data disk on /mnt.
    - Move content of /var to /mnt.
    - Unmount data disk from /mnt.
    - Mount data disk to /var with mount -a (uses configuration in /etc/fstab).
    - Reboot and make sure that /var is properly mounted.
  • Make sure VM is up-to-date (base image might be old).
    - apt update
    - apt upgrade
  • Once you get details from customer, configure DNS entries:
    - Main homeserver address: $
    - files/dns/ in dot-cdist.
    - Whatever is needed for Riot-web.
    - Do not forget to configure the IPv4-to-IPv6 proxy! See Common operations on IPv4-to-IPv6-Proxy.
  • Add VM to place6-monitoring LAN.
  • Add server to matrix-as-a-service manifest in dot-cdist. Deploy.
    - You can find the detailed parameters of synapse and riot in the __matrix_synapse and __matrix_riot.
  • Create initial admin user:
    - Register new user, either via riot (standard user to be promoted afterwards) or /usr/bin/register_new_matrix_user on server.
    - Any user can be promoted by a simple SQL query:
    + On server, open postgresql shell: sudo -u postgres psql matrix-synapse
    + List users: SELECT * FROM users;
    + Make user admin: UPDATE users SET admin = 1 WHERE name = '';
    - Once the initial admin user is created, you can access the web management UI: (use server FQDN as homeserver).
  • Configure federation:
    - Federation defaults to port 8448 and matrix server name. We have to redirect it to $ on port 443.
    - Delegation works with a well-known URL served on matrix server name: /.well-known/matrix/server returning {"m.server": "$"}.
    - While we are at it, also configure homeserver discovery for clients: /.wll-known/matrix/client returning { "m.homeserver": { "base_url": "" } }.
    - For a custom domain, either the client do it by himself or redirect the domain to the the matrix server. There are examples in the matrix-as-a-service manifest.
    - Check that everything looks good with the Federation tester:
  • Optional: customize hoster riot welcome page (--homepage riot extra parameter)

Upgrade a running MaaS instance

Always read synapse changelog first!
Always work and test on the staging instance first!

Unattended upgrade automatically apply security upgrades to the VM: you only have to update synapse (the matrix homserver) from time to time. It usually boils down to a simple apt update; apt upgrade.

Note: the matrix-synapse synapse comes from the debian (buster) backports repository. APT can be told/forced to use it with the -t buster-backports flag.

Deploy Matterbridge application service

You can directly use the __matterbridge type:

Updated by Timothée Floure almost 4 years ago · 13 revisions