Self-hosted service
spantaleev/matrix-docker-ansible-deploy avatar
spantaleev/matrix-docker-ansible-deploy

matrix-docker-ansible-deploy chooses between five homeservers before it installs anything

🐳 Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker

6,527 stars1,179 forksJinjaAGPL-3.0

At a glance

What is it?
This Ansible playbook runs a Matrix homeserver and its surrounding services in Docker. Synapse is the default, four other homeservers are supported, and the README's own advice is to install a subset on the first run and re-run the playbook later.
Who is it for?
This playbook fits someone who wants a complete Matrix deployment with federation, a web client and the surrounding services without assembling each container by hand, and who is prepared to read the documentation rather than accept a single command. It does not fit someone who wants a one-time setup and no ongoing maintenance, since the README states plainly that running any service smoothly requires knowledge, time and effort.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Jinja, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • spantaleev/matrix-docker-ansible-deploy6,527 ★ · +34
Star history
Repository2026-09-232026-11-15
spantaleev/matrix-docker-ansible-deploy6.5k6.5k

34 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Synapse is a default, not a requirement

The homeserver table is the first decision the playbook asks you to make, and it is a real choice rather than a formality.

Five implementations are listed. Synapse is marked as the default, described as storing your data and managing your presence in the Matrix network. Conduit is offered as a lightweight open-source server with a focus on easy setup and low system requirements. continuwuity appears as another option. Tuwunel is described as the official successor to conduwuit. Dendrite is called a second-generation homeserver written in Go and positioned as an alternative to Synapse.

Four of the five are marked as not default, which means the playbook knows how to configure each but expects most people to leave the choice alone.

The Conduit entry matters most for anyone on a small machine, since its description points at low system requirements. Choosing one means reading its own configuration page.

The table also links a dedicated documentation page per homeserver.

The supported services list is exhaustive by design

The README is unusually candid that its list of supported services is exhaustive, and that it includes optional and advanced components you will most likely not need.

The advice that follows is to stick with the defaults, which install a subset, and to treat that as the best choice for a new installation. You can re-run the playbook later to add or remove components. That is an unusual recommendation in a project of this size, and it is there because the full component list covers more than a typical deployment needs.

Deprecated and unmaintained services are excluded from the list, with their documentation kept on a separate page in the configuring-playbook document. So the set of things you can install has narrowed over time, and the removed ones are still documented rather than deleted.

The client list follows the same pattern. Element Web is the default, configured to connect to your own Synapse server. Hydrogen is a lightweight client with legacy and mobile browser support. Cinny, Sable and SchildiChat Web are alternatives, with FluffyChat Web and Commet also listed. Only Element Web is marked as default, so you get a working web client out of the box and everything else is opt-in.

One detail worth catching: the default client is described as connecting to Synapse specifically, which is another reason to check your homeserver choice before assuming the default pairing still holds.

Two installation guides, chosen by whether you have existing data

Getting started offers two paths, and the split is not about skill level alone.

The quick start guide is for beginners and is described as the option for those without an existing Matrix server who want to start quickly with opinionated defaults. The full installation guide is for advanced users, and its stated trigger is different: you need it if you want to import an existing Matrix server's data into the new server, or if you want to learn while setting the server up. The path into it starts at the prerequisites page.

So the decision variable is whether data has to move. A fresh install goes the quick path; a migration goes the full path from prerequisites, because migrating a homeserver is where the complexity lives.

The README also states you do not need to read the whole documentation set, which is fair given the size of the supported services list, and points to a FAQ for configuration problems before offering help and support as the fallback.

The documentation lives in `docs/` with a table of contents in its own README. Individual service configuration pages follow a naming pattern of `configuring-playbook-<service>.md`, so the file names are predictable enough to jump straight to one.

The Makefile holds three targets, and roles are the important one

The playbook's own developer tooling is compact enough to read in full, and one target matters for anyone installing from source.

External Ansible roles are not committed. They are pulled from Galaxy, pinned by a requirements file:

bash
ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force

That line sits under a target that first removes `roles/galaxy`, so it is a clean reinstall every time. So what lands in roles/galaxy is decided by the pinned list in requirements.yml.

The other two targets are `lint`, which runs ansible-lint against the custom roles:

bash
ansible-lint roles/custom

and `add-inventory-host`, which takes a domain and an IP and calls a shell script to create or extend the inventory files.

The repository supports both Make and just workflows. There is a `justfile` alongside the Makefile, and the justfile calls the same underlying script for adding a host. It also contains an `update` recipe that reinstalls the pinned roles and, with a `-u` flag, updates the pinned versions in `requirements.yml` itself.

That flag is the difference between upgrading a deployment and upgrading the pins. Without it you get the versions the playbook expects; with it you adopt whatever is newer, which is a deliberate choice rather than a side effect.

Reverse proxies are an example, not an afterthought

Federation on Matrix depends on how your server is reachable, and this repository treats that as configuration you supply rather than something it decides.

The example files include `examples/reverse-proxies/`, alongside `examples/vars.yml`, `examples/host.yml` and `examples/hosts`. So the supported topologies are shipped as examples you adapt, and the example hosts file is where your server address goes.

The README is clear about scope elsewhere: it runs all supported services in Docker containers, which gives a predictable and up-to-date setup across multiple supported distributions and architectures, with x86 or amd64 recommended. Other architectures have their own documentation page.

The licensing setup is worth noting because it is unusual: the repository carries `REUSE.toml`, `LICENSES/`, and `.license` sidecar files for individual assets such as the README, the setup playbook and the examples. That is the REUSE specification for machine-readable licensing, and its presence means individual files carry their own license headers rather than inheriting from a single LICENSE file.

The main playbook itself is `setup.yml`, also with a `.license` companion.

Managed hosting is the escape hatch, and it is a subscription

The README does something most playbooks do not: it tells you when not to use it.

The stated position is that the playbook tries to make self-hosting and maintaining a Matrix server fairly easy, but that running any service smoothly still requires knowledge, time and effort. That sentence is the honest summary of what any such automation can promise.

For anyone who wants the FOSS approach but not the responsibility, the recommendation is etke.cc, described as a service built on top of this very playbook with additional components and services. Both hosted and on-premises options are mentioned, along with separate pages for extras and for services.

The warning attached to it is the part worth keeping: the service operates on a subscription basis, and there is no option to set up a server once and be finished with it.

That caveat is also the honest description of running the playbook yourself. This is infrastructure with a long tail of maintenance: upgrades, certificate renewal, domain changes and service updates all arrive as work. The playbook automates the mechanics; it does not remove the obligation.

The funding and community links at the top of the README point to a Matrix room and a donation page, so the project also relies on community rather than on a vendor relationship.

No releases means you track a branch, not a version

The repository publishes no GitHub releases. There are no releases to pin a deployment to in the usual way, and no release notes page on GitHub to diff before an upgrade.

What exists instead is `CHANGELOG.md` with a `CHANGELOG.md.license` companion, and a `YEAR-IN-REVIEW.md`. So the history is written up in the repository rather than in release metadata.

The upgrade path is therefore: pull the default branch, then re-run the playbook. The README frames installation and upgrades as the same automated operation, with maintenance tasks handled the same way, which is what an Ansible playbook gives you. There is no separate upgrade procedure to learn.

What you lose is the ability to say which version you are running. If something breaks after an upgrade, the diff you care about is between two commits, and the changelog is the only description of what changed between them.

The last push to the default branch was 2026-11-02, and the repository is not archived.

For a long-lived Matrix server that users depend on, that is the practical thing to plan around: take your own copy of the changelog before each pull, so you can reconstruct what your server gained.

Editorial conclusion

This playbook fits someone who wants a complete Matrix deployment with federation, a web client and the surrounding services without assembling each container by hand, and who is prepared to read the documentation rather than accept a single command. It does not fit someone who wants a one-time setup and no ongoing maintenance, since the README states plainly that running any service smoothly requires knowledge, time and effort. Before starting, pick your homeserver deliberately rather than accepting the default, because the supported list includes implementations with very different resource profiles, including Conduit described as lightweight with low system requirements. Note that the repository publishes no GitHub releases, so upgrades arrive as commits to the default branch and there is no released version to pin to. Check `examples/reverse-proxies/` before you commit to a topology, and remember that the documented reverse proxy is part of getting federation right.

Frequently asked questions

Which Matrix homeservers does matrix-docker-ansible-deploy support?

Five are listed: Synapse as the default, plus Conduit, continuwuity, Tuwunel and Dendrite. Conduit is described as a lightweight implementation focused on easy setup and low system requirements, Tuwunel as the official successor to conduwuit, and Dendrite as a second-generation homeserver written in Go.

Does matrix-docker-ansible-deploy use Docker and Ansible together?

Yes. All supported services run in Docker containers, giving a predictable setup across multiple distributions and architectures, while installation, upgrades and some maintenance tasks are automated with Ansible. The playbook also ships a Makefile and a justfile for its own developer tasks.

How do I get the external Ansible roles matrix-docker-ansible-deploy needs?

They are not committed. The `roles` target in the Makefile runs `ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force` after removing the directory, and the justfile has a matching `roles` recipe.

Does matrix-docker-ansible-deploy publish versioned releases?

No. The repository has no GitHub releases, so there is no release to pin to. Change history lives in `CHANGELOG.md` and `YEAR-IN-REVIEW.md`, and the upgrade path is to pull the default branch and re-run the playbook.

Official sources

  1. Issues
  2. License: AGPL-3.0
  3. README
  4. spantaleev/matrix-docker-ansible-deploy on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/spantaleev-matrix-docker-ansible-deploy.svg)](https://hysenlabs.com/projects/spantaleev-matrix-docker-ansible-deploy)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/spantaleev-matrix-docker-ansible-deploy.svg)](https://hysenlabs.com/projects/spantaleev-matrix-docker-ansible-deploy)

Was this useful?