Установка и настройка сервера Matrix Synapse с использованием Ansible и Docker

Нужна установка под ключ? Смотрите услугу настройка Matrix / Element.

Данная инструкция предполагает полную установку Synapse на собственный сервер (или VPS) и базовую настройку всех его функций. Для установки Synapse используется множество Docker контейнеров разворачиваемых совместно с cистемой управления конфигурациями Ansible. Официальную документацию по данному методу установки и ссылки на неё, вы можете найти на Github и Matrix.org.

Synapse — это домашний сервер для общения через Matrix с открытым исходным кодом, написанный и поддерживаемый Matrix.org Foundation. Для общения через Matrix используются следующие мессенджеры https://matrix.org/clients/

Метод установки Synapse с помощью Ansible и Docker я выбрал в связи с тем что он наиболее легкий в плане установки и настройки дополнительных зависимостей и расширений Synapse, а также данный способ предполагает автоматическую установку Traefik (reverse-proxy), SSL (Let’s Encrypt), PostgreSQL и Element Web.

Вкратце, Matrix — это открытый стандарт для связи в Интернете используемый для мессенджеров, поддерживающий федерацию, шифрование, голосовую и видео связь, видеоконференции. Также возможны интеграции с Telegram, Discord, Whatsapp и т.д., полный список возможных интеграций вы найдете тут: https://github.com/spantaleev/matrix-docker-ansible-deploy#bridges

На текущий момент Matrix возможно использовать как для Приватного общения между друзьями и близкими, так и для полноценной замены Whatsapp, Telegram и т.д., или вообще для корпоративной связи, но с одним большим отличием от популярных мессенджеров, а именно:

1. Вы можете использовать для связи собственный сервер с собственным ключом шифрования и усиленной защитой перехвата данных. У популярных централизованных мессенджеров серверы и метаданные под контролем оператора сервиса; на своём сервере вы сами решаете, где хранятся аккаунты, медиа и логи
2. Несмотря на использование собственного сервера, вы можете коммуницировать с пользователями других серверов Matrix (функционал федерации)
3. Вы можете настроить мост и общаться с пользователями любого другого мессенджера, к примеру Telegram или Whatsapp
4. Меньше зависимости от чужой инфраструктуры: аккаунты и история комнат живут на вашем сервере (при E2EE содержимое комнат недоступно серверу в открытом виде)
5. Качественная и максимально стабильная аудио и видео связь при достаточных характеристиках сервера на который установлен Synapse
6. Контроль над данными: вы выбираете хостинг, бэкапы и политику регистрации
7. Минимальная верификация в сети, вы можете не использовать свой номер телефона или почту для регистрации (кроме некоторых публичных серверов, часто требуется ввод электронной почты) Как начать с публичного сервера — в руководстве Join Matrix, а подобрать сервер можно в списке публичных серверов.

То есть Synapse позволяет вам присоединиться к сети Matrix, используя ваш собственный идентификатор @<имя пользователя>:<ваш-домен>, и все они размещены на вашем собственном сервере или арендованном VPS.

Все службы запускаются в контейнерах Docker что позволяет нам иметь предсказуемую и актуальную настройку. Установка (обновления) и некоторые задачи обслуживания автоматизированы с помощью Ansible.

Если нужна установка «под ключ» — есть услуга Matrix Synapse + Element на VPS. Ниже — самостоятельная установка по официальному playbook matrix-docker-ansible-deploy (актуально на 2026).

Системные требования

Без Matrix RTC / Element Call (только чат и базовая связность):

4ГБ оперативной памяти (или 2ГБ+swap), процесcор 2 ядра (с частотой не ниже 3,4 ГГц), 40гб диск SSD или NVME

С Matrix RTC / Element Call (современные звонки через LiveKit):

6ГБ оперативной памяти (или 4ГБ+swap), процессор 2 ядра (с частотой не ниже 3,4 ГГц)

Поддерживаемые ОС:

Debian 10+ (лучше 12)
Ubuntu 20.04+ (лучше 22.04 / 24.04 LTS)
Rocky Linux / AlmaLinux (или другие RHEL-подобные)
Arch Linux

Лично устанавливал только на Ubuntu 24.04 LTS и Debian 11-12.

Сервер с 2ГБ ОЗУ без swap также может работать с Synapse, но только для личных звонков (без видео) и личных переписок (проверено, но с некоторыми ограничениями). Федеративные чаты с множеством подписок перегрузят сервер с подобными характеристиками намертво (придется перезагружать сервер и экстренно удалять Synapse с последующей переустановкой)

Покупка домена

Приобретаем домен для вашего сервера Matrix. Для покупки доменов я рекомендую Timeweb CloudРеклама.

Аренда сервера VPS

Для аренды VPS я рекомендую следующих провайдеров:

Сервер — Timeweb CloudРеклама. Для Synapse желательно выбирать тариф с быстрым процессором.

Серверы в России — Timeweb CloudРеклама: VPS в российских дата-центрах, там же удобно купить доменРеклама и управлять DNS-записями.

Настройка записей DNS на домене

После покупки домена и аренды сервера, необходимо сразу же прописать указанные ниже записи DNS для вашего домена. Сделать это нужно как можно быстрее, так как вам придется ждать от 3 часов до 3 суток обновление записей DNS, обычно обновление длится меньше суток.

Основной домен использоваться для Synapse не будет, так как он обычно используется под основной сайт или блог. Для Synapse будут использоваться поддомены типа matrix.example.ru и element.example.ru

Вместо example.ru подставьте свой домен подготовленный для Synapse.

Необходимые записи DNS для домена:

Минимальный набор для установки «из коробки» (вместо example.ru — ваш домен, IP — адрес VPS):

A matrix → IP сервера
CNAME element → matrix.example.ru

Опционально: AAAA matrix → IPv6 сервера (если есть).

Записи для Dimension / Jitsi и SRV _matrix-identity больше не нужны для базовой установки. Делегация коротких ID вида @user:example.ru настраивается через /.well-known (см. ниже) или параметр matrix_static_files_container_labels_base_domain_enabled, а не через identity SRV.

Пример настройки записей DNS домена в панели управления регистратора:

Проверку обновления записей DNS для домена можно провести тут https://2ip.ru/dig/

Подготовка системы

Обновляем систему

apt update -y && 
apt upgrade -y

Усиливаем безопасность сервера и отключаем вход по паролю по следующей памятке при помощи SSH ключа:

Памятка по безопасности VPS, VDS сервера Ubuntu, Debian

Устанавливаем необходимые зависимости (Python3-pip, ansible и pwgen для генерации паролей):

apt install pipx
pipx ensurepath
pipx install ansible
apt install pwgen

Перегружаем сервер:

reboot

Также для установки Ansible в качестве альтернативного способа можно воспользоваться официальной документацией https://docs.ansible.com/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-debian

Установка Matrix Synapse

Загрузка установочных файлов

Загружаем установочные файлы на сервер

git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git

Настройка Ansible Playbook

Загрузка шаблона базовой конфигурации

Ansible Playbook в данной инструкции мы будем запускать непосредственно на сервере, для этого нам нужно скопировать шаблон конфигурации в каталог конфигурации Synapse и указать настройки SSH подключения в файле matrix-docker-ansible-deploy/inventory/hosts

Переходим в директорию с установочными файлами

cd matrix-docker-ansible-deploy

Создаем каталог для конфигурации нашего сервера (вместо example.ru укажите свой домен)

mkdir -p inventory/host_vars/matrix.example.ru

Копируем шаблонные файлы конфигурации vars.yml и hosts (вместо example.ru укажите свой домен)

cp examples/vars.yml inventory/host_vars/matrix.example.ru/
cp examples/hosts inventory/hosts

Настройка SSH подключения Ansible к серверу

Для редактирования конфигурационного файла подключения к серверу выполните команду:

nano inventory/hosts

Содержимое файла должно быть таким если вы воспользовались памяткой безопасности, т.к. в ней используется ключ SSH вместо пароля и изменен порт для SSH подключения:

[matrix_servers]
matrix.example.ru ansible_host=IP-сервера ansible_ssh_user=root ansible_ssh_port=ПОРТ-SSH ansible_ssh_private_key_file=~/.ssh/id_rsa

Вместо example.ru укажите свой домен приобретенный ранее.

В ansible_host укажите внешний IP адрес своего сервера.

В ansible_ssh_user укажите имя пользователя используемого для SSH (по умолчанию root и я не менял его, пользователь может быть отличным от root). Также если у вас используется sudo вам нужно будет в конце команд установки Ansible добавлять ключ -K

В ansible_ssh_port укажите свой порт SSH (по умолчанию 22, но я изменил его и рекомендую вам сделать также согласно памятке безопасности)

В ansible_ssh_private_key_file укажите путь к ключу SSH (по умолчанию ~/.ssh/id_rsa, в памятке используется такой же путь)

Если SSH ключ не используется и порт SSH не изменен, то содержимое будет таким (но это не наш случай так как мы заботимся о безопасности):

[matrix_servers]
matrix.example.ru ansible_host=IP-сервера ansible_ssh_user=root

Генерация ключей для Matrix Synapse

Заранее сгенируйте ключи для конфигурации Matrix Synapse, вам понадобится для этого 10 ключей. Сгенериуйте ключи следующей командой и сохраните их в на компьютере в блокнот:

pwgen -s 64 1

Настройка основных параметров Synapse

Основные параметры Synapse содержатся в файле vars.yml по пути matrix-docker-ansible-deploy/inventory/host_vars/matrix.example.ru

Для редактирования vars.yml выполните следующую команду (вместо example.ru укажите свой домен):

nano inventory/host_vars/matrix.example.ru/vars.yml

Вы можете использовать готовый шаблон конфигурации vars.yml приведенный ниже полностью заменив все строки файла и заполнить его своими данными.

Вам необходимо заменить example.ru на свой домен и добавить ранее сгенерированные ключи вместо ‘большой ключ’.

В шаблоне используется основной домен, а не поддомен для того чтобы иметь красивые адреса типа @login:example.com без приставки matrix.

#Обязательное
matrix_playbook_migration_validated_version: v2026.05.18.0
matrix_domain: example.com
matrix_homeserver_implementation: synapse
matrix_homeserver_generic_secret_key: 'большой ключ'
matrix_playbook_reverse_proxy_type: playbook-managed-traefik
devture_systemd_docker_base_ipv6_enabled: true
postgres_connection_password: 'большой ключ'


# Если основной домен example.ru можно отдать Matrix (нет отдельного сайта) — включите раздачу /.well-known с Matrix-сервера.
# Если сайт уже на example.ru — закомментируйте и настройте /.well-known на своём веб-сервере (раздел ниже).
matrix_static_files_container_labels_base_domain_enabled: true
traefik_config_certificatesResolvers_acme_email: 'ssl@example.com'
#matrix_nginx_proxy_base_domain_serving_enabled : true

#Активация админ-панели
matrix_ketesa_enabled: true

# Звонки Element Call / Matrix RTC (LiveKit). Для чата можно не включать.
#matrix_rtc_enabled: true
#matrix_element_call_enabled: true

Указанный шаблон конфигурации содержит:

• Synapse homeserver — сервер Matrix Synapse
• PostgreSQL — база данных
• Traefik — reverse-proxy (порты 80/443/8448), SSL через Let’s Encrypt
• Let’s Encrypt — автоматические SSL-сертификаты через Traefik
• Element Web — веб версия клиента Matrix доступная по адресу element.example.ru настроенный по умолчанию на ваш сервер (вместо example.ru укажите свой домен)
• Exim — исходящая почта для уведомлений Matrix (можно настроить relay на внешний SMTP)
• Ketesa / Element Admin — веб-панель администратора (если включена в vars.yml)
• Опционально: Matrix RTC / Element Call (LiveKit) — современные звонки
• Опционально: matrix-registration — регистрация по приглашениям
• Coturn — отдельно, только если включаете классический TURN (по умолчанию для Element Call не обязателен)
• Документация playbook: после правок vars.yml всегда сверяйтесь с examples/vars.yml и CHANGELOG

После заполнения шаблона своими данными нужно запустить установку. Если что-то вам не нужно просто удалите строчку из конфигурационного файла или закомментируйте её.

Запуск установки Matrix Synapse

Установите ansible-core:

pipx install ansible-core

Перезагрузите сервер:

reboot

Установите роли Ansible необходимые для установки Synapse:

rm -rf roles/galaxy &&
ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force

Установите модули Ansible Galaxy community.general, ansible.posix и community.docker:

ansible-galaxy collection install community.general
ansible-galaxy collection install ansible.posix
ansible-galaxy collection install community.docker

Устанавливаем, если пользователь в hosts не root и нужно получить пароль от sudo, добавьте в конце команды ключ -K и во всех командах его добавлять нужно будет

ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start

Дальше можно запустить проверку конфигурации

ansible-playbook -i inventory/hosts setup.yml --tags=self-check

В случае использования SSH пароля вместо ключа для команды деплоя используйте ключ —ask-pass

ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start --ask-pass

Если у вас возникают ошибки, то возможно обновился Matrix Synapse Ansible и вам необходимо актуализировать указанный шаблон относительно examples/vars.yml (просьба написать об этом в комментариях) Также всегда внимательно и осмысленно читайте текст ошибки чтобы исключить ваш человеческий фактор.

Документация и дополнительные настройки Matrix Synapse Ansible

Регистрация первого пользователя и делаем его администратором

Для создания пользователя с правами администратора выполните команду:

ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=логин password=пароль admin=yes' --tags=register-user

Dimension (устарело, удалено из playbook)

Ранее playbook умел ставить Dimension (менеджер интеграций / виджеты, в т.ч. кнопка Jitsi). Компонент больше не поддерживается и убран из matrix-docker-ansible-deploy — новые установки Dimension делать не нужно.

Если Dimension остался со старых лет, удалите вручную на сервере (playbook уже не поможет):

systemctl disable --now matrix-dimension.service
rm -rf /matrix/dimension
/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_dimension;'

Для виджетов и звонков используйте актуальный стек: Element Call + Matrix RTC (LiveKit) — см. следующий раздел. Официально: docs/configuring-playbook-dimension.md.

Активация звонков (Element Call / Matrix RTC)

Современный путь для аудио/видео в Element Web и Element X — Matrix RTC (LiveKit Server + LiveKit JWT Service). Отдельный Jitsi через Dimension больше не актуален.

В vars.yml добавьте (достаточно RTC, если звоните из клиента Element; frontend Element Call нужен только для отдельного веб-UI):

# Поддержка звонков Element Call внутри клиентов
matrix_rtc_enabled: true

# Опционально: отдельный веб-UI Element Call
#matrix_element_call_enabled: true

После правки пересоберите сервисы:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

Откройте в firewall порты LiveKit (если звонки включены): 7881/tcp, 7882/udp, 3479/udp, 5350/tcp, 30000:30020/udp — см. раздел про фаервол.

Документация: Matrix RTC, Element Call.

Регистрация по приглашению

Данная функция уже включена в шаблоне вашей конфигурации. Для создания ссылки-приглашениявоспользуйтесь следующей командой:

ansible-playbook -i inventory/hosts setup.yml 
--tags=generate-matrix-registration-token 
--extra-vars="one_time=yes ex_date=2027-12-31"

one_time=ставьте «no» если вам нужно приглашение без ограничения срока действия. Я рекомендую ставить значение «yes» и прописывать дату для ex_date= в формате как в образце команды

После запуска вышеупомянутой команды вы получите ссылку на регистрацию для ваших друзей.

Панель администратора

Доступна по адресу (/ в конце обязательно):

https://matrix.example.ru/synapse-admin/

Правила фаервола

Используемые правила фаервола (нужно согласовать с уже установленными правилами в системе. См. памятка безопасности пункт 5):

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw allow 8448/tcp
sudo ufw allow 8448/udp
sudo ufw allow ВАШ-SSH-ПОРТ/tcp
# Если включили Matrix RTC / Element Call (LiveKit):
sudo ufw allow 7881/tcp
sudo ufw allow 7882/udp
sudo ufw allow 3479/udp
sudo ufw allow 5350/tcp
sudo ufw allow 30000:30020/udp
sudo ufw enable

Проверяем статус:

sudo ufw status verbose

Делегация /.well-known на основном домене

Если основной домен (example.ru) уже занят сайтом и вы не включили matrix_static_files_container_labels_base_domain_enabled, настройте делегацию вручную: клиенты и федерация должны узнавать, что Matrix для example.ru живёт на matrix.example.ru.

Пример для nginx на сервере с сайтом (проксируйте well-known на Matrix-хост):

location /.well-known/matrix {
    proxy_pass https://matrix.example.ru/.well-known/matrix;
    proxy_set_header X-Forwarded-For $remote_addr;
}

Проверка федерации: federationtester.matrix.org. Документация playbook: Server Delegation.

Проверка TURN/VoIP (если настроили звонки): test.voip.librepush.net.

Обновление и обслуживание

Playbook не обновляет сервисы сам — периодически обновляйте репозиторий и роли, затем перезапускайте установку. Следите за CHANGELOG (бывают breaking changes и поле matrix_playbook_migration_validated_version в vars.yml).

Канал уведомлений: #homeowners:matrix.org. Комната поддержки playbook: #matrix-docker-ansible-deploy:devture.com.

Обновление:

cd matrix-docker-ansible-deploy
git pull
# Обновить Ansible-роли (обязательно после git pull):
rm -rf roles/galaxy && ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force
# Альтернатива: установите just (https://github.com/casey/just) и выполните: just roles   или   just update
# Или: just update   /   just roles

# Если только обновляете версии компонентов:
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start

# Если меняли vars.yml и отключали сервисы — лучше setup-all:
# ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

Версию PostgreSQL playbook сам не мигрирует — мажорные апгрейды БД делаются по документации playbook вручную.

Удаление Synapse

Для удаления Synapse введите следующую команду:

sh /matrix/bin/remove-all

затем скопировать и вставить для подтверждения текст «Yes, I really want to remove everything!»

Реклама. ООО «ТАЙМВЭБ.КЛАУД», ИНН 7810945525, erid: CQH36pWzJqVKyCLcHfYJjN7tMMG5q1zq1zwGxHoZ8G95ZA.