{"id":14975867,"url":"https://github.com/metal0/matrix-compose","last_synced_at":"2025-10-27T14:31:19.481Z","repository":{"id":207244670,"uuid":"677084466","full_name":"metal0/matrix-compose","owner":"metal0","description":"Easy Matrix HS Setup with docker compose","archived":false,"fork":false,"pushed_at":"2025-01-26T11:10:01.000Z","size":162,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-26T11:22:14.601Z","etag":null,"topics":["docker","dockercompose","matrix","synapse"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metal0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-10T17:41:48.000Z","updated_at":"2024-12-30T11:18:30.000Z","dependencies_parsed_at":"2024-09-18T18:00:35.483Z","dependency_job_id":null,"html_url":"https://github.com/metal0/matrix-compose","commit_stats":{"total_commits":16,"total_committers":1,"mean_commits":16.0,"dds":0.0,"last_synced_commit":"d934b92a871b2bf7b6cdadd15ffba669182eb530"},"previous_names":["metal0/matrix-compose"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal0%2Fmatrix-compose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal0%2Fmatrix-compose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal0%2Fmatrix-compose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal0%2Fmatrix-compose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metal0","download_url":"https://codeload.github.com/metal0/matrix-compose/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238508865,"owners_count":19484215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","dockercompose","matrix","synapse"],"created_at":"2024-09-24T13:52:47.310Z","updated_at":"2025-10-27T14:31:19.093Z","avatar_url":"https://github.com/metal0.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# matrix-compose\n\n## What is it?\n\nmatrix-compose is a collection of scripts and config files intended to make setting up and configuring a small/personal [Matrix](https://matrix.org/) homeserver easier.\n\n\nIncluded 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](https://github.com/matrix-org/matrix-hookshot), [Draupnir](https://github.com/the-draupnir-project/Draupnir)\n\n## Motivation and goals of this project\n\nAs 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.\n\nFor 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.\n\nThe 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.\n\n**If you are trying to host a production-grade large matrix HS, this is the wrong place!**\n\n\n\n# Setup Guide\n\n## Pre-requisites\n\n* A Linux Server with at least 10Gb free disk space and ~2Gb RAM\n(Resource usage will mostly depend on your usage)\n\n* A available domain behind a reverse proxy such as Cloudflare\n\n* Linux, Docker, Docker-Compose and Git experience or willingness to google issues that arise\n\n\n## Getting everything ready\n\n\n### Dependencies\n\nYou 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.\n\ninstall git, openssl, dig, curl\n```sh\nsudo apt-get update\nsudo apt-get install -y openssl dig curl git\n```\n\n### Setup DNS and Routing\n\nBefore you proceed, it's best to decide how your DNS/Reverse Proxying will connect to your matrix HS.\n\nmatrix-compose was designed to be put behind a reverse proxy and will NOT be secure at all if not behind one.\n\n\u003e [!NOTE]\n\u003e 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`.\n\n[Cloudflare Tunnels](https://www.cloudflare.com/products/tunnel/) are recommended and supported for high flexibility and secure environments.\n\n#### Cloudflare Tunnels Setup\n\nIf using Cloudflare Tunnels, simply create a new tunnel, copy the token shown on the \"Install Connector\" page and save it for later.\n\nAdd a single public hostname of `HTTPS://` `nginx:443` for the URL you are configuring your matrix HS to be available at.\n\n__**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.\n\n#### DNS Records\n\nSet the following DNS records on your domain's DNS management dashboard:\n\n* **A** `example.org.` - ipv4 (if not using tunnels)\n\n* **A** `turn.example.org.` - your server's IPv4 address (for VoIP)\n\n* **AAAA** `turn.example.org.` - your server's IPv6 address (for VoIP)\n\n\n\n\n## Installation\n\n### Clone the repo\n\n```sh\ngit clone https://github.com/metal0/matrix-compose.git\n```\n\n### Install Docker Engine (and Docker Compose)\n\n\nRefer to the following guide on how to install these for your OS/Distro:\n[https://docs.docker.com/engine/install/#server]\n\n__Make sure to test your docker installation as mentioned in the guides before proceeding!__\n\n### Setup Env Variables\n\nCopy the `.env` file\n```sh\ncp .env.example .env\n```\n\n\nThen edit it with your favorite text editor, making sure to ONLY filling in `DOMAIN_NAME` (and `TUNNEL_TOKEN` if using Cloudflare Tunnels).\n```bash\nnano .env\n```\n\n### Run the Initialization Script\n\nFinally, you need to run the initialization script `init.sh` which will setup everything else for you automatically.\n\n\n```bash\nsh init.sh\n```\n\nThis will take several minutes to run and fully setup all services, don't panic.\n\n\u003e [!IMPORTANT]\n\u003e Some bridges/bots require additional setup post-install, refer to the guides below after everything is functional\n\nIt's highly recommended to use [matrix's federation testing tool](https://federationtester.matrix.org/) after finishing the setup to verify that everything is working.\n\n\n## Firewalling\n\n### Nginx\n\nNginx needs only port `443` allowed (if not using cloudflare tunnels)\n\n### Eturnal (VoIP)\n\nIf you wish to use VoIP with Eturnal, you will need to allow the following ports:\n\u003e `3478`\n\u003e `5349`\n\u003e `49152-65535`\nIn 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/]\n\n\n## Customizing the Web Client\n\nIn order to customize the web-client to your liking, please refer to [Element Web's Documentation](https://github.com/vector-im/element-web/blob/develop/docs/config.md).\n(Relevant config file is @ `/data/web-client/web-client.config.json`)\n\n## Synapse Configuration\n\nSynapse's config is found @ `/data/synapse/config.yaml`\n\nThe included config shouldn't need any major changes.\n\n### Enabling Public Registration\n\nIn order to safely enable public registration you will likely want to add either recaptcha or email verification (to prevent abuse).\n\n\u003e [!CAUTION]\n\u003e The Mautrix bridges are configured for a single-user use-case (though they will allow anyone registered on your HS to use them)\n\u003e 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).\n\n\n## Bot Setup\n\n### Bot Localparts\n\n* Discord: `@mautrix-discordbot:example.org`\n* Draupnir: `@draupnir:example.org`\n* Facebook: `@mautrix-facebookbot:example.org`\n* Gmessages: `@mautrix-gmessagesbot:example.org`\n* Googlechat: `@mautrix-googlechatbot:example.org`\n* Heisenbridge: `@heisenbridge:example.org`\n* Hookshot: `@hookshot:example.org`\n* Instagram: `@mautrix-instagrambot:example.org`\n* LinkedIn: `@beeper-linkedinbot:example.org`\n* Signal: `@mautrix-signalbot:example.org`\n* Slack: `@mautrix-slackbot:example.org`\n* Steam: `@_steampuppet_bot:example.org`\n* Telegram: `@mautrix-telegrambot:example.org`\n* Twitter: `@mautrix-twitterbot:example.org`\n* WhatsApp: `@mautrix-whatsappbot:example.org`\n\n\n### Draupnir\n\nDraupnir is a Moderation bot for Matrix, useful if you want to run \u0026 secure a public room against spam.\n\nCreate a management room for Draupnir, make sure it's set to invite-only. (As anyone who joins the room can use the bot)\n\nGive it the local alias `#draupnir`\n\nInvite the bot to the room (`@draupnir:example.org`)\n\nRestart the draupnir docker container `docker restart draupnir`\n\nYou should see it join the room!\n\n[Quick-start guide](https://github.com/the-draupnir-project/Draupnir#quickstart-guide)\n\n\n### Hookshot\n\nHookshot is a bridge between multiple project management services (Github, Gitlab, Jira, etc) as well as a webhooks provider and rss feeds tracker.\nBy default Hookshot is only configured to handle generic webhooks and RSS/Atom feeds, anything else needs to be configured manually.\n\nBot: `@hookshot:example.org`\n\nCheck [hookshot documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) for usage/configuration guides.\n\n\n### Bridges\n\nCheck the [mautrix bridge docs](https://docs.mau.fi/bridges/) to learn how to use \u0026 configure each mautrix bridge\n\n\n#### Telegram Bridge\n\nCreate API keys at https://my.telegram.org/apps and optionally create a bot account for relaying at https://t.me/BotFather\nInput the respective values @ `data/bridges/telegram/config.yaml` (`telegram.api_id`, `telegram.api_hash`, `telegram.bot_token`)\n\nIf using the bot relay, also add yourself to the `relaybot.whitelist` array in the config file.\n\nAfter configuring, uncomment the line on synapse's config `app_service_config_files` relevant to the telegram registration file.\n\n\n# Contributing\n\nAll contributions are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal0%2Fmatrix-compose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetal0%2Fmatrix-compose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal0%2Fmatrix-compose/lists"}