This Ansible playbook is meant to help you run your own Matrix homeserver, along with the various services related to that.
That is, it lets you join the Matrix network using your own
@<username>:<your-domain>identifier, all hosted on your own server (see prerequisites).We run all services in Docker containers (see the container images we use), which lets us have a predictable and up-to-date setup, across multiple supported distros (see prerequisites) and architectures (x86/amd64 being recommended).
Installation (upgrades) and some maintenance tasks are automated using Ansible (see our Ansible guide).
The Matrix server, originally set up using Ansible and Docker, operates efficiently on servers with public IPv4 addresses. However, in my experience, Matrix federation fails on IPv6-only servers (without public IPv4). This issue likely stems from the server's foundation on Docker, as the official Docker platform lacks built-in IPv6 NAT support, to the best of my knowledge. Therefore, we can potentially resolve this issue by configuring the IPv6 network settings of Docker.
- Security: The container's network needs to be private, and its behavior should align with Docker IPv4. Only specific ports can be accessed.
- The host machine is in a small range of subnets (with a prefix greater than /80), such as xxx::xx/128, and there are no extra IPv6 addresses available for allocation to containers.
The official Docker does not have built-in IPv6 NAT. If you want to use IPv6 NAT, you need to install an external IPv6 startup. see docker-ipv6nat.
Using the following command, start IPv6 NAT in the background (configured to start automatically on boot using --restart always).
docker run -d --name matrix-ipv6nat --privileged --network host --restart always -v /var/run/docker.sock:/var/run/docker.sock:ro -v /lib/modules:/lib/modules:ro robbertkl/ipv6nat
Customize network support for IPv6, create a bridge network matrix that supports IPv6. The --subnet parameter is a subnet of fe80::/10.
docker network create matrix --subnet="fd00:1::1/80" --gateway="fd00:1::1"
Check if it is effective by using the command docker network inspect my-net-ipv6. If it is effective, then the value of EnableIPv6 should be true.
I have incorporated an IPv6 setup process into the original project, using the docker-ipv6nat container.
- Added the docker-ipv6nat container to the path
/roles/custom/matrix-ipv6natand set IPv6 NAT to be enabled by default. - Added IPv6 listening configuration
listen [::]:<port>to severalmatrix-*.conffiles located in the path/roles/custom/matrix-nginx-proxy/templates/nginx/conf.d.
For setup instructions, please refer to the original project's Installation Guide: Matrix server setup using Ansible and Docker.
-
All containers after
ansible-playbookdeployment, We can see thatipv6natstarted successfully. -
ipv6 test inside the docker container
matrix-nginx-proxy