matrix-docker-ansible-deploy: An Ansible Playbook for a Full Matrix Homeserver Stack

What the Playbook Does: One Command to Stand Up a Matrix Stack

A Matrix homeserver is not a single application. At minimum it needs a homeserver process, a reverse proxy, TLS certificates, and a database. A complete installation for a team typically adds a web client, one or more bridges to other platforms, a bot, media storage, and monitoring. Assembling all of these by hand and keeping them updated is significant operational work.

This Ansible playbook encodes that work as a set of roles that can be applied to a target server in a single run. The README describes its purpose as helping you run your own Matrix homeserver, along with the various services related to that. The result is a predictable, reproducible setup across the supported Linux distributions and architectures (x86/amd64 recommended, with alternative architectures documented in docs/alternative-architectures.md).

All services run in Docker containers. The README notes that this gives a predictable and up-to-date setup. Container images are listed in docs/container-images.md. Ansible handles installation, configuration, and maintenance tasks including upgrades.

How Ansible and Docker Work Together Here

Ansible's role in this playbook is configuration management and orchestration. The roles in the roles/ directory generate Docker Compose or systemd service files for each component, write configuration files, and run the containers. Docker provides the runtime isolation between services.

The directory layout shows roles/custom/ for playbook-specific roles and roles/galaxy/ for external Ansible Galaxy roles pulled via requirements.yml. The justfile and Makefile both expose a roles target for pulling these dependencies:

make roles

Or using just:

just roles

The justfile notes that agru (an Ansible Galaxy role updater) is used when available to pin new role versions in requirements.yml. Without agru, the standard ansible-galaxy command is used instead. This two-path design means contributors can update role versions precisely without manually editing requirements.yml.

Ansible's idempotency means re-running the playbook after a configuration change or after an upstream image update converges the server to the desired state without tearing it down and rebuilding from scratch.

Getting Started: Prerequisites and First Run

The README describes two guides for new installations. The quick-start guide at docs/quick-start.md targets beginners who want opinionated defaults and do not have an existing Matrix server to migrate. The full installation guide starts at docs/prerequisites.md and covers custom configurations and data imports.

Adding a new host to the Ansible inventory uses the add-inventory-host script:

just add-inventory-host example.com 1.2.3.4

Or with make:

make add-inventory-host domain=example.com ip=1.2.3.4

The examples/ directory contains sample inventory files (examples/hosts) and a sample variables file (examples/vars.yml) that show the expected structure. The result of following the prerequisites and running the playbook is a Matrix homeserver where users have IDs of the form @alice:example.com, as shown in the README.

The playbook also integrates with ACME DNS-01 challenges for TLS certificates through the acme-dns-01-sandcats integration visible in the repository root.

Homeserver Choices: Synapse, Conduit, and Others

The playbook supports five homeserver implementations. Synapse is the default and is the most established Matrix homeserver. The README lists four alternatives: Conduit, described as lightweight with easy setup and low system requirements; continuwuity; Tuwunel, described as the official successor to conduwuit; and Dendrite, described as a second-generation homeserver written in Go.

The choice of homeserver determines resource consumption, federation behavior, and the set of Matrix features available. Synapse is the most complete implementation but uses more memory and CPU than the Rust-based or Go-based alternatives. Small deployments with constrained resources may prefer Conduit or Tuwunel. The README recommends sticking with defaults (Synapse) for new installations and switching homeservers only if there is a specific reason.

Each supported homeserver has a corresponding documentation file in docs/, such as docs/configuring-playbook-synapse.md, docs/configuring-playbook-conduit.md, and docs/configuring-playbook-dendrite.md. The playbook's design means the homeserver choice is expressed in a group_vars variable; switching later requires careful migration of user data, which the README's full installation guide addresses under data import.

The Scope of Optional Services

The README states that its list of supported services is exhaustive and includes optional and advanced components that most deployments will not need. The playbook can configure web clients including Element Web (the default), Hydrogen, Cinny, Sable, SchildiChat Web, FluffyChat Web, and Commet.

Beyond clients, the playbook covers bridges to other platforms, bots, media storage backends, monitoring, and administrative tools. The README explicitly notes that deprecated or unmaintained services are not listed in the current table but their documentation remains at docs/configuring-playbook.md.

This breadth is a significant operational consideration. A playbook that can manage dozens of services also creates a large surface for things to break during upgrades. The recommended approach in the README is to start with the basics and add services incrementally rather than enabling everything at once.

Maintenance Overhead and the Upgrade Path

Running any Matrix homeserver requires ongoing maintenance. The playbook handles upgrades by re-running against the target server; Ansible's idempotency means only changed components are affected. The CHANGELOG.md in the root and the YEAR-IN-REVIEW.md file provide records of changes and annual summaries of the project's evolution.

The repository has no GitHub releases. Tracking changes requires watching the repository or reading CHANGELOG.md. The last push was on 2026-09-26, and the playbook is actively maintained.

For teams who want the benefits of this playbook without managing the Ansible overhead themselves, the README mentions etke.cc as a managed Matrix server service built on top of this playbook. etke.cc operates on a subscription model and does not offer a one-time setup option, per the README's note.

When This Playbook Is the Wrong Choice

This playbook is a poor fit for teams that want a containerized service in an existing Kubernetes cluster. The playbook manages systemd services and Docker Compose stacks on a target host; it does not produce Helm charts or Kubernetes manifests. A separate project, Matrix-Synapse Helm chart, covers Kubernetes deployments.

Teams that only need a simple chat server and have no interest in federation, bridges, or a large catalog of services may find the playbook more complex than necessary. A single Synapse Docker Compose file manually written covers the core use case with fewer moving parts.

The playbook also assumes Ansible knowledge. Engineers unfamiliar with inventory files, group_vars, and role execution will need to learn those concepts before the playbook is useful. The quick-start guide reduces this barrier but does not eliminate it entirely. The AGENTS.md file in the repository root is a further pointer to contributor context that may help new users understand how the project structures its roles.

Editorial conclusion

This playbook suits engineers who want to operate a Matrix homeserver and are comfortable writing Ansible inventory files and running playbooks when services need updates. It is not the right choice for teams who want a point-and-click setup or who expect zero ongoing maintenance: running a homeserver means applying playbook updates when Synapse, the bridges, or the auxiliary services release security fixes. Before starting, confirm that the target server meets the prerequisites documented in docs/prerequisites.md, because the playbook does not handle misconfigured DNS, missing ports, or unsupported Linux distributions.

Frequently asked questions

Official sources

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