This project provides a Docker Compose-based deployment for a Matrix homeserver, refactoring the setup originally derived from the Matrix Ansible Docker Deploy project. We leverage the upstream project as a submodule for historical tracking and its robust configuration capabilities, while specifically translating its established functionality into a simplified Docker Compose architecture.
The goal is to streamline the deployment process and enhance the user experience for setting up a Matrix homeserver with a more direct Docker-native approach via Docker Compose.
The primary purpose of this project is to transition running Matrix homeserver from systemd to docker compose.
Important Note: This repository is a specialized derivative of the general-purpose matrix-docker-ansible-deploy project. While it uses the upstream project for initial configuration generation, this repository specifically provides Docker Compose files tailored for a particular set of services, rather than supporting all the options in the entire matrix-docker-ansible-deploy project.
This project is licensed under the AGPL-3.0 license. You are free to use, modify, and distribute this project under the terms of the AGPL-3.0 license. Please refer to the LICENSE file for more details.
To get started with this Docker Compose deployment of the Matrix homeserver, follow these steps:
-
Clone the Repository:
git clone [https://github.com/qtpi-bonding/matrix-docker-compose-deploy.git](https://github.com/qtpi-bonding/matrix-docker-compose-deploy.git) cd matrix-docker-compose-deploy -
Clone and Configure the Upstream Ansible Playbook: This project relies on the
matrix-docker-ansible-deployrepository to generate the necessary configuration files for your Matrix homeserver components.-
First, clone the upstream repository to a sibling directory and check out the specific commit this project is based on:
cd .. # Go up one directory from matrix-docker-compose-deploy git clone [https://github.com/spantaleev/matrix-docker-ansible-deploy.git](https://github.com/spantaleev/matrix-docker-ansible-deploy.git) cd matrix-docker-ansible-deploy git checkout 2a9cf7de9748177809352f5d253d440f849dbf60 # Check out the specific tested commit
-
Configure the Ansible playbook using the upstream project's comprehensive documentation. You will primarily interact with the
inventory/host_vars/matrix.{DOMAIN_NAME}/vars.ymlfile: Refer to the official configuration guide: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md -
Crucially, note that this Docker Compose setup currently supports only the following Matrix services:
matrix-coturnmatrix-client-elementmatrix-postgresmatrix-synapsematrix-static-filesmatrix-sygnalmatrix-synapse-adminmatrix-traefik-certs-dumpermatrix-traefikmatrix-container-socket-proxy
Ensure your
vars.ymlconfiguration (especiallymatrix_homeserver_services_enabledand similar options) aligns with these supported services to avoid generating unnecessary configurations for components not included in this Docker Compose setup.
-
-
Replace placeholder in docker-compose.yml with your domain name
- Replace
{DOMAIN_NAME}with your domain (e.g.example.com).sed -i 's/{DOMAIN_NAME}/example.com/' docker-compose.yml
- Replace
All the necessary Ansible configuration generation and systemd cleanup steps are automated in the matrix-docker-compose-setup.sh script provided in this repository.
-
Run the Setup Script:
./matrix-docker-compose-setup.sh
This script will perform the following actions:
- Run
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-createdto generate all configuration files and ensure necessary host users are created. - Run
ansible-playbook -i inventory/hosts setup.yml --tags=stopto stop any Matrix services that Ansible might have started or left running. - Remove all
matrix*.{service,timer}unit files from/etc/systemd/system/to preventsystemdfrom interfering with Docker Compose. - Run
systemctl daemon-reloadto reload thesystemddaemon.
- Run
-
Deploy with Docker Compose:
- Finally, run
docker compose up -dto start your Matrix homeserver stack using Docker Compose.
- Finally, run
-
Monitor Your Deployment: Once the script finishes, you can check the status of your services with:
docker compose ps
And view their logs with:
docker compose logs -f
This README provides an overview of the Matrix Docker Compose Deployment project, ensuring compliance with the AGPL-3.0 license while guiding users through the setup and usage of the project.
Tested on commit: 2a9cf7de9748177809352f5d253d440f849dbf60