ITcompressor IT — сжато и по делу
← Назад к статьям

Установка и настройка tuwunel через docker

18.06.2026
matrixnginxdevops

Tuwunel — это self-hosted сервер Matrix, который можно использовать вместо matrix-synapse, но написан на Rust вместо Python.

Это максимально упрощенный гайд по установке и настройке, основное:

  • tuwunel + element web (веб клиент) через докер
  • с проксирование через nginx (reverse proxy на один домен)
  • wireguard как связка домашнего сервера с внешним миром, гайд по wireguard тут

0. Переменные, которые стоит будет менять под себя (или оставить если ок)#

  • 10.0.3.197 - это мой внутренний айпи сервера, меняете на свое, если все делается на одном сервере, то можно 127.0.0.1
  • next-way.by - мой домен, по которому происходит доступ, меняете на свой
  • /opt/matrix - мой путь на сервере, где распологаются все файлы для Tuwunel
  • dff315b705ce - CONTAINER ID моего инстанса jevolk/tuwunel:main на домашнем сервере, у вас будет другой id

1. Установка и настройка докер#

Если докер старой версии, то может быть сложность при скачивании контейнера (будет ошибка что-то про TAR). Чуть что если у вас старая версия docker, например 20ая, то обновите ее, гайд тут или офф https://docs.docker.com/engine/install/ubuntu/

2. Поднимаем tuwunel + element web#

Создаем файл для docker-compose, например как tuwunel.yaml в папке /opt/matrix. Чтобы не было проблем, сразу поработаем с правами на папку (поменяем владельца на текущего пользователя) командой:

sudo chown -R $USER:$USER /opt/

Далее создаем файл nano /opt/matrix/tuwunel.yaml где необходимо только поменять TUWUNEL_SERVER_NAME и TUWUNEL_REGISTRATION_TOKEN

services:

  homeserver:
    ### If you already built the tuwunel image with 'docker build' or want to use a registry image,
    ### then you are ready to go.
    image: jevolk/tuwunel:main
    restart: unless-stopped
    ports:
      - 8008:6167
    volumes:
      - /opt/matrix/tuwunel:/var/lib/tuwunel
      #- ./tuwunel.toml:/etc/tuwunel.toml
    environment:
      TUWUNEL_SERVER_NAME: next-way.by # EDIT THIS
      TUWUNEL_DATABASE_PATH: /var/lib/tuwunel
      TUWUNEL_PORT: 6167
      TUWUNEL_MAX_REQUEST_SIZE: 20000000 # in bytes, ~20 MB
      TUWUNEL_ALLOW_REGISTRATION: 'true'
      TUWUNEL_REGISTRATION_TOKEN: 'change-it' # A registration token is required when registration is allowed.
      #TUWUNEL_YES_I_AM_VERY_VERY_SURE_I_WANT_AN_OPEN_REGISTRATION_SERVER_PRONE_TO_ABUSE: 'true'
      TUWUNEL_ALLOW_FEDERATION: 'true'
      TUWUNEL_TRUSTED_SERVERS: '["matrix.org"]'
      #TUWUNEL_LOG: warn,state_res=warn
      TUWUNEL_ADDRESS: 0.0.0.0
      #TUWUNEL_CONFIG: '/etc/tuwunel.toml' # Uncomment if you mapped config toml above


  element-web:
    image: vectorim/element-web:latest
    restart: unless-stopped
    ports:
      - 8009:80
    volumes:
      - /opt/matrix/element_config.json:/app/config.json
    depends_on:
      - homeserver

2.1. Настройка element-web#

Чтобы element-web заработал для него необходимо создать конфиг nano /opt/matrix/element_config.json, где необходимо поменять для себя значения в m.homeserver

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://next-way.by",
      "server_name": "next-way.by"
    },
    "m.identity_server": {
      "base_url": "https://vector.im"
    }
  },
  "disable_custom_urls": false,
  "disable_guests": false,
  "disable_login_language_selector": false,
  "disable_3pid_login": false,
  "force_verification": false,
  "brand": "Element",
  "integrations_ui_url": "https://scalar.vector.im/",
  "integrations_rest_url": "https://scalar.vector.im/api",
  "integrations_widgets_urls": [
    "https://scalar.vector.im/_matrix/integrations/v1",
    "https://scalar.vector.im/api",
    "https://scalar-staging.vector.im/_matrix/integrations/v1",
    "https://scalar-staging.vector.im/api"
  ],
  "default_widget_container_height": 280,
  "default_country_code": "GB",
  "show_labs_settings": false,
  "features": {},
  "default_federate": true,
  "default_theme": "light",
  "room_directory": {
    "servers": [
      "matrix.org"
    ]
  },
  "enable_presence_by_hs_url": {
    "https://matrix.org": false,
    "https://matrix-client.matrix.org": false
  },
  "setting_defaults": {
    "breadcrumbs": true
  },
  "jitsi": {
    "preferred_domain": "meet.element.io"
  },
  "element_call": {
    "url": "https://call.element.io",
    "brand": "Element Call"
  },
  "map_style_url": "https://api.maptiler.com/maps/streets/style.json?key=fU3vlMsMn4Jb6dnEIFsx"
}

2.2. Сам запуск#

docker compose -f tuwunel.yaml up -d

# -f - указывает на файл
# up -d - запускает в бекграунде

Можем с помощью docker ps проверить что все запустилось без ошибок

3. Настройка nginx#

Необходимо также завести VPS и создать A запись на домен, но это уже выходит за пределы гайда, все действия по настройке nginx происходят на VPS с внешним айпишником и на котором уже установлен wireguard для связи VPS + домашний сервер

Первым делом сгенерируем сертификаты для Let's Encrypt с помощью cerbot (Установку cerbot найдете тут https://certbot.eff.org/instructions/)

certbot --nginx -d next-way.by

После чего нужно будет удалить лишнее, что добавил cerbot, единственное запомните пути к публичному и приватному ключу, мало ли cerbot будет распологать эти ключи в каком-то другом месте чем у меня по гайду.

Создадим конфиг для проксирования на Tuwunel и element web nano /etc/nginx/sites-enabled/next-way.by

upstream tuwunel {
  server 10.0.3.197:8008; # IP and port where tuwunel is listening
}

server {
  # Client-Server API over HTTPS (port 443)
  listen 443 ssl;
  listen [::]:443 ssl;
  # Matrix Federation over HTTPS (port 8448)
  # Only needed if you want to federate with other homeservers
  # Don't forget to open port 8448 in your firewall!
  listen 8448 ssl;
  listen [::]:8448 ssl;
#  http2 on;
  server_name next-way.by;

  # Nginx standard body size is 1MB, which is quite small for media uploads
  # Increase this to match the max_request_size in your tuwunel.toml
  client_max_body_size 100M;
  location / {
    proxy_pass http://10.0.3.197:8009;

    # Preserve host and scheme - critical for proper Matrix operation
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto https;
  }

  # Forward requests to Tuwunel
  location ~ ^(/_matrix|/_synapse/client|/_synapse/admin|/_synapse/mas) {
    proxy_pass http://10.0.3.197:8008;

    # Preserve host and scheme - critical for proper Matrix operation
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto https;
  }

  # TLS configuration (Let's Encrypt example using certbot)
  ssl_certificate /etc/letsencrypt/live/next-way.by/fullchain.pem; # managed by Certbot
  ssl_certificate_key /etc/letsencrypt/live/next-way.by/privkey.pem; # managed by Certbot
}

server {
    if ($host = next-way.by) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80 ;
    listen [::]:80 ;
    server_name next-way.by;
    return 404; # managed by Certbot
}

У меня конфиг не отрабатывал с http2 on;, но у вас возможно все заведется, моя проблема скорее всего в том что я менял глобальные настройки ранее. Правило для element web взял из https://habr.com/ru/articles/1028012/.

Проверяем конфиг командой

nginx -t

и если все хорошо, то применяем командой

service nginx reload

Если все хорошо, то при открытии своего домена вы увидите element-web

4. Заведение пользователя#

Т.к. мы запустили Tuwunel в docker, то прямого доступа к cli у нас нет и для этого необходимо запускать cli из под докер контейнера. Для этого на домашнем сервере выполняем docker ps чтобы узнать CONTAINER ID для jevolk/tuwunel:main и создаем юзера с админ правами:

# проверяем что доступ к cli есть
docker exec -it dff315b705ce tuwunel -h

# создаем юзера
docker exec -it dff315b705ce tuwunel --execute "users create_user your_user_name"

После чего вам в ответе придет логин и пароль. Лично у меня были в последующем проблемы с логином, но все это починилось простой перезагрузкой контейнера docker restart dff315b705ce

Послесловие#

Клиент я использую FluffyChat https://matrix.org/ecosystem/clients/fluffychat/, он немного неудобный, но зато поддерживает Multi Account.

После логина вы попадете в комнату (чат) где также будет находиться бот @conduit:next-way.by (у вас будет с вашим доменом), который может выполнять команды cli через команды в чат. Для получения справки можете написать в чате:

!admin --help

← Назад к статьям