matrix-compose is a collection of scripts and config files intended to make setting up and configuring a small/personal Matrix homeserver easier.
Included in the docker-compose services are, along with a working homeserver (Synapse) setup, various social media bridges (IRC, Discord, Facebook, Google Messages, Google Chat, Instagram, LinkedIn, Signal, Slack, Steam, Telegram, Twitter, WhatsApp), as well as utilitarian bots such as Hookshot, Draupnir
As someone with very basic docker-compose experience who wanted to get into the matrix "ecosystem", I found it difficult to find easy setups such as this available.
For this reason (and because constructing my own docker-compose with ~35 services for my own HS took weeks), I wanted to provide a slightly easier way to selfhost your own Matrix HS without needing a sysadmin bachelor's degree.
The goals of matrix-compose are not to be a full-fledged and perfect production HS, but more-so a personal, small HS that people can experiment with, and learn about the matrix ecosystem with.
If you are trying to host a production-grade large matrix HS, this is the wrong place!
-
A Linux Server with at least 10Gb free disk space and ~2Gb RAM (Resource usage will mostly depend on your usage)
-
A available domain behind a reverse proxy such as Cloudflare
-
Linux, Docker, Docker-Compose and Git experience or willingness to google issues that arise
You need to install all the relevant tooling for the setup process, though the bulk of the services run on Docker, your host requires some setup.
install git, openssl, dig, curl
sudo apt-get update
sudo apt-get install -y openssl dig curl gitBefore you proceed, it's best to decide how your DNS/Reverse Proxying will connect to your matrix HS.
matrix-compose was designed to be put behind a reverse proxy and will NOT be secure at all if not behind one.
Note
If you do not wish to run it behind a reverse proxy, make sure to rework X-Forwarded-For headers and such in data/nginx/nginx.conf.
Cloudflare Tunnels are recommended and supported for high flexibility and secure environments.
If using Cloudflare Tunnels, simply create a new tunnel, copy the token shown on the "Install Connector" page and save it for later.
Add a single public hostname of HTTPS:// nginx:443 for the URL you are configuring your matrix HS to be available at.
Make sure to enable "No TLS Verify" on the tunnel settings (or replace the self-signed generated certs at the end of the setup with Cloudflare Certs), otherwise the tunnel will refuse to connect to your Nginx backend.
Set the following DNS records on your domain's DNS management dashboard:
-
A
example.org.- ipv4 (if not using tunnels) -
A
turn.example.org.- your server's IPv4 address (for VoIP) -
AAAA
turn.example.org.- your server's IPv6 address (for VoIP)
git clone https://github.com/metal0/matrix-compose.gitRefer to the following guide on how to install these for your OS/Distro: [https://docs.docker.com/engine/install/#server]
Make sure to test your docker installation as mentioned in the guides before proceeding!
Copy the .env file
cp .env.example .envThen edit it with your favorite text editor, making sure to ONLY filling in DOMAIN_NAME (and TUNNEL_TOKEN if using Cloudflare Tunnels).
nano .envFinally, you need to run the initialization script init.sh which will setup everything else for you automatically.
sh init.shThis will take several minutes to run and fully setup all services, don't panic.
Important
Some bridges/bots require additional setup post-install, refer to the guides below after everything is functional
It's highly recommended to use matrix's federation testing tool after finishing the setup to verify that everything is working.
Nginx needs only port 443 allowed (if not using cloudflare tunnels)
If you wish to use VoIP with Eturnal, you will need to allow the following ports:
3478534949152-65535In addition, you should add your server's IPv6 address to/data/eturnal/eturnal.yml, and verify that VoIP is working using a tool such as [https://test.voip.librepush.net/]
In order to customize the web-client to your liking, please refer to Element Web's Documentation.
(Relevant config file is @ /data/web-client/web-client.config.json)
Synapse's config is found @ /data/synapse/config.yaml
The included config shouldn't need any major changes.
In order to safely enable public registration you will likely want to add either recaptcha or email verification (to prevent abuse).
Caution
The Mautrix bridges are configured for a single-user use-case (though they will allow anyone registered on your HS to use them) For this reason it's highly recommended to review your Mautrix bridge bots' configuration before enabling public registration, as the mautrix bridges can easily leak private data due to how they are currently setup (with multi-users).
- Discord:
@mautrix-discordbot:example.org - Draupnir:
@draupnir:example.org - Facebook:
@mautrix-facebookbot:example.org - Gmessages:
@mautrix-gmessagesbot:example.org - Googlechat:
@mautrix-googlechatbot:example.org - Heisenbridge:
@heisenbridge:example.org - Hookshot:
@hookshot:example.org - Instagram:
@mautrix-instagrambot:example.org - LinkedIn:
@beeper-linkedinbot:example.org - Signal:
@mautrix-signalbot:example.org - Slack:
@mautrix-slackbot:example.org - Steam:
@_steampuppet_bot:example.org - Telegram:
@mautrix-telegrambot:example.org - Twitter:
@mautrix-twitterbot:example.org - WhatsApp:
@mautrix-whatsappbot:example.org
Draupnir is a Moderation bot for Matrix, useful if you want to run & secure a public room against spam.
Create a management room for Draupnir, make sure it's set to invite-only. (As anyone who joins the room can use the bot)
Give it the local alias #draupnir
Invite the bot to the room (@draupnir:example.org)
Restart the draupnir docker container docker restart draupnir
You should see it join the room!
Hookshot is a bridge between multiple project management services (Github, Gitlab, Jira, etc) as well as a webhooks provider and rss feeds tracker. By default Hookshot is only configured to handle generic webhooks and RSS/Atom feeds, anything else needs to be configured manually.
Bot: @hookshot:example.org
Check hookshot documentation for usage/configuration guides.
Check the mautrix bridge docs to learn how to use & configure each mautrix bridge
Create API keys at https://my.telegram.org/apps and optionally create a bot account for relaying at https://t.me/BotFather
Input the respective values @ data/bridges/telegram/config.yaml (telegram.api_id, telegram.api_hash, telegram.bot_token)
If using the bot relay, also add yourself to the relaybot.whitelist array in the config file.
After configuring, uncomment the line on synapse's config app_service_config_files relevant to the telegram registration file.
All contributions are welcome!