matrix #16

Supports: bionic xenial


Synapse is a reference "homeserver" implementation of Matrix, from the core development team at It is written in Python/Twisted and is intended to showcase the concept of Matrix.

In Matrix, every user runs one or more Matrix clients, which connect through to a Matrix homeserver. The homeserver stores all their personal chat history and user account information - much as a mail client connects through to an IMAP/SMTP server.

Just like email, you can either run your own Matrix homeserver and control and own your own communications and history or use one hosted by someone else (e.g. - there is no single point of control or mandatory service provider in Matrix, unlike WhatsApp, Facebook, Hangouts, etc.

This charm is designed to be used in conjunction with Matterbridge in order to integrate with 3rd party chat systems, such as Mattermost, IRC, Slack, etc.

pipeline status
coverage report


This charm will deploy a Matrix homeserver, running synapse, and optionally supporting the following bridges - * matrix-appservice-irc


This charm currently relies on the following snaps being built locally and then deployed as resources: snap-matrix-synapse - merged upstream (ensure PR #6315 and #6317 are also merged into your local branch) snap-matrix-appservice-irc - in review

None of these charms are currently published to to store, pending further discussions upstream. There is nothing preventing them from being hosted on the store, however the most sensible namespaces are already registered, and working with the upstream project to get them pushing automatically on merge is the desired outcome. In the meantime, layer-snap provides the ability to upload the built charms as resources, where they will be deployed locally. This means the level of confinement is lower (devmode instead of strict), and updates need to be controlled by updating the uploaded snap resource, so getting these published on the store is definitely on the roadmap for this charm.


This charm supports a number of configuration items for customising the behaviour of the homeserver. These are documented in the config.yaml file, however the following are the most important:

  • enable-registration controls whether or not public users can register an account.
  • server-name controls the FQDN of the server used in federation and other client operations.
  • shared-secret allows you to provide a shared secret which is used when registering users, if enabled.
  • enable-irc installs and configures the IRC bridge when set to true.

Do ensure you review the remainder of the configuration items, as they control security and privacy related aspects of Synapse, and the defaults might not suit your needs, erring on the side of privacy.


  • matrix-appservice-slack support (WIP)
  • matrix-puppet-slack support (WIP)


This charm and the related snap work has been written by James Hebden of the Alchemy Charmers group.

Primary development is done on the Alchemy Charmers GitLab, and mirrored to GitHub.


(boolean) When true, public rooms are available by default via federation
(boolean) When true, public rooms can be queried without authenticating
(float) The cache factor influences the amount of system memory used for caching room information. Reducing this number will reduce the amount of memory used for caching, at the expense of performance for common API queries.
(int) The default room version to advertise for new rooms
(boolean) Enable federation, enabled by default. When enabled, port 8448 will listen, including via reverse proxy.
(boolean) Enable connecting to this homeserver via IRC, using the matrix-ircd snap. Will use port 6667 for non-TLS and 6697 if TLS is enabled, per RFC7194.
(boolean) When set to true, invites are enabled for non-admin users
(boolean) Enable public new user registration, disabled by default
(boolean) Enable reporting of anonymous stastics to the Matrix project
(boolean) Enable searching the room list
(boolean) When set to true, indexing and search is enabled.
(boolean) Enable TLS via ACME. When a reverse proxy is related, this will tell the related reverse proxy to prefer port 443 for the frontend listener.
(boolean) Enable the user directory
(string) This external domain name the server will be accessed from. Defaults to server name. This can be set to a different domain to the server name, for example a subdomain of the server name's domain.
(string) A comma separated list of domains to whitelist for federation
(string) A comma seperated list of IP ranges to blacklist from federation
(boolean) Prefer the use of IP addresses for reverse proxy and matrix IRCd when contacting the home server, useful if you have non-functional internal DNS
(boolean) When true, requires authentication to request profile information
(string) The public server name. This value needs to be set, and once set, can not be changed. This name forms the @domain portion of all matrix users on the home server.
(string) The shared secret used during registration. Leave blank for it to be autogenerated. The secret can be retrieved via the get-shared-secret action.
(string) The SMTP host to use when sending notifications.
(string) The password, if required, used when logging in to the SMTP host provided.
(string) Customise the SMTP port to use when sending notifications.
(string) The email address to send notifications from.
(string) The user account, if required, used when logging in to the SMTP host provided.
(string) DEPRECATED. Use snap-http-proxy and snap-https-proxy model configuration settings. HTTP/HTTPS web proxy for Snappy to use when accessing the snap store.
(string) DEPRECATED. Use snap-store-proxy model configuration setting. The address of a Snap Store Proxy to use for snaps e.g.
(string) How often snapd handles updates for installed snaps. The default (an empty string) is 4x per day. Set to "max" to check once per month based on the charm deployment date. You may also set a custom string as described in the 'refresh.timer' section here:
(boolean) Enable or disable presence tracking in synapse.