matrix #16

Supports: bionic xenial
Add to new model

Description

Synapse is a reference "homeserver" implementation of Matrix, from the core
development team at matrix.org. 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. matrix.org) - 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

Matrix

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

Deployment

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.

Configuration

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.

TODO

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

Author

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.


Configuration

allow-public-rooms-federated
(boolean) When true, public rooms are available by default via federation
allow-public-rooms-unauthed
(boolean) When true, public rooms can be queried without authenticating
cache-factor
(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.
2
default-room-version
(int) The default room version to advertise for new rooms
5
enable-federation
(boolean) Enable federation, enabled by default. When enabled, port 8448 will listen, including via reverse proxy.
True
enable-ircd
(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.
enable-non-admin-invites
(boolean) When set to true, invites are enabled for non-admin users
enable-registration
(boolean) Enable public new user registration, disabled by default
enable-reporting-stats
(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.
True
enable-tls
(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.
enable-user-directory
(boolean) Enable the user directory
external-domain
(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.
federation-domain-whitelist
(string) A comma separated list of domains to whitelist for federation
federation-ip-range-blacklist
(string) A comma seperated list of IP ranges to blacklist from federation
prefer-internal-ip
(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
require-auth-profile-requests
(boolean) When true, requires authentication to request profile information
True
server-name
(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.
shared-secret
(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.
smtp-host
(string) The SMTP host to use when sending notifications.
smtp-pass
(string) The password, if required, used when logging in to the SMTP host provided.
smtp-port
(string) Customise the SMTP port to use when sending notifications.
25
smtp-sender
(string) The email address to send notifications from.
smtp-user
(string) The user account, if required, used when logging in to the SMTP host provided.
snap_proxy
(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.
snap_proxy_url
(string) DEPRECATED. Use snap-store-proxy model configuration setting. The address of a Snap Store Proxy to use for snaps e.g. http://snap-proxy.example.com
snapd_refresh
(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: https://forum.snapcraft.io/t/system-options/87
track-presence
(boolean) Enable or disable presence tracking in synapse.