Deploy Tuwunel

Deploy and Host Tuwunel on Railway

Tuwunel is a Matrix homeserver written in Rust, and the official continuation of the conduwuit project. It speaks the full Matrix client-server and federation protocol, so the people you invite can talk to anyone on matrix.org or on a company server — while every message, room and uploaded file stays on infrastructure you control. Being a single compiled binary over an embedded RocksDB store, it runs in a few hundred megabytes where the reference Python homeserver wants gigabytes, which is what makes self-hosting Matrix realistic for a small team.

Deploy Tuwunel on Railway and you get a working chat service rather than a bare API: the homeserver, handling logins, rooms, encrypted messaging and federation, plus Element Web, a browser client already pointed at it. A volume holds the database and a Railway object storage bucket holds every uploaded image, video and file, so attachments never compete with the database for disk. Federation is published through /.well-known/matrix/server on port 443, so remote servers reach you over Railway's HTTPS edge with no extra port to open.

Getting Started with Tuwunel on Railway

Open the Element Web service URL rather than the homeserver URL — the homeserver answers API calls, not browsers. Element already shows your own domain under "Host account on", so click Create account, pick a username and password, and paste TUWUNEL_REGISTRATION_TOKEN from the Tuwunel service's variables when the token step appears. That token is what stops your server being an open signup form, so share it only with people you want on it. The first account registered is made server admin and invited into an admin room, where commands like !admin users list-users and !admin server show-config run as ordinary messages.

To confirm it works, create a room, send a message and drag in an image: if the picture renders, client, homeserver and bucket are wired correctly. Then open the room directory, switch the server to matrix.org and join a public room — history backfills in a minute or two. To check federation from outside, paste your domain into federationtester.matrix.org.

About Hosting Tuwunel

Matrix is an open standard for real-time communication, and a homeserver stores your users' accounts and their share of every room they join. Running your own means group chat, direct messages, call signalling and file sharing that no vendor can price-change, discontinue or read. Teams reach for it when a hosted chat tool becomes a compliance problem.

Tuwunel is the practical choice when you would rather not run a database cluster:

• Rooms, spaces, threads, reactions, read receipts, presence and end-to-end encryption
• Federation with the wider Matrix network, or a closed server if you turn it off
• Registration closed by default and opened only with a token; optional LDAP, OIDC and JWT login
• An embedded RocksDB database, so there is no separate Postgres to run or back up
• Media on any S3-compatible bucket, with the local disk kept as a fallback
• An in-chat admin console for user, room, media and federation moderation

Tuwunel is the only service holding state: its volume carries the database, its bucket the uploaded media. Element Web is a static client served by nginx that stores nothing.

Why Deploy Tuwunel on Railway

Railway removes the parts of running a homeserver that are not about chat:

• HTTPS certificates are handled for you, and federation rides the same port 443
• The volume and the object storage bucket are attached by the template
• Both services scale independently, with memory and CPU visible per service
• Redeploys pick up new Tuwunel releases without touching your data
• Custom domains attach in the dashboard

Common Use Cases

• A private team chat server for a company whose conversations must stay on its own infrastructure
• A community space federating with matrix.org, so existing Matrix users join without a new account
• A bridge hub joining Slack, Discord, IRC or Signal rooms into Matrix via the appservice API
• A backend for bots, alerting and on-call handover, driven through the client-server API

Dependencies for Tuwunel

• ghcr.io/matrix-construct/tuwunel:latest — the homeserver, from matrix-construct/tuwunel
• ghcr.io/element-hq/element-web:latest — the browser client, from element-hq/element-web, with a startup script pointing it at your homeserver
• A persistent volume at /data — the RocksDB database; without it every account is lost on redeploy
• A Railway object storage bucket — uploaded files, avatars and thumbnails, keeping the volume small

Environment Variables Reference

Deployment Dependencies

• Docs: Tuwunel, Element Web config, spec.matrix.org

Hardware Requirements for Self-Hosting Tuwunel

Memory scales with the size of the rooms your users join, not the number of accounts — joining a large public room pulls in its state and history. A handful of users on private rooms fits the minimum.

Self-Hosting Tuwunel with Docker

Tuwunel is configured entirely by environment variables, and nested configuration sections use a double underscore, as in TUWUNEL_WELL_KNOWN__SERVER. The following Docker command starts a homeserver on port 8008:

docker run -d --name tuwunel -p 8008:8008 \
  -v tuwunel-db:/data \
  -e TUWUNEL_SERVER_NAME="chat.example.com" \
  -e TUWUNEL_DATABASE_PATH="/data" \
  -e TUWUNEL_ADDRESS="0.0.0.0" \
  -e TUWUNEL_ALLOW_REGISTRATION="true" \
  -e TUWUNEL_REGISTRATION_TOKEN="change-me" \
  -e TUWUNEL_WELL_KNOWN__SERVER="chat.example.com:443" \
  ghcr.io/matrix-construct/tuwunel:latest

Put a TLS-terminating reverse proxy in front of it, then confirm the discovery documents answer, since they are what remote servers read first:

curl https://chat.example.com/.well-known/matrix/server
curl https://chat.example.com/_matrix/client/versions

Add Element Web by mounting a config.json whose default_server_config points at the same domain. On Railway both halves are wired together already.

How Much Does It Cost to Self-Host Tuwunel?

Tuwunel is free and open source under the Apache 2.0 licence, and Element Web is free under the AGPL. There are no seats and no paid edition — the whole feature set, federation and encryption included, is in the build you deploy. On Railway you pay only for the compute, volume and object storage the two services use, a few dollars a month for a small team.

FAQ

What is Tuwunel? Tuwunel is a Matrix homeserver written in Rust — the server side of the open Matrix chat protocol. It is the official successor to conduwuit, which was archived in 2026.

What does this Railway template deploy? Two services: the Tuwunel homeserver with a persistent volume and an object storage bucket for media, and Element Web, a browser client already configured to sign in to it.

Why does the template include an object storage bucket? Matrix media grows without limit — every avatar, screenshot and video anyone shares, plus copies cached from other servers. Keeping it in a bucket means the volume rarely needs resizing.

How do I stop strangers creating accounts on my Matrix server? Only people you give TUWUNEL_REGISTRATION_TOKEN to can sign up. Once everyone has an account, set TUWUNEL_ALLOW_REGISTRATION to false to close signup entirely.

Can I use a custom domain with a self-hosted Matrix homeserver? Yes, but attach it before anyone registers. The domain becomes the suffix of every user and room ID and cannot be changed later without starting from an empty database.

Do I need to open port 8448 for Matrix federation? No. The homeserver publishes /.well-known/matrix/server pointing at port 443, so federation rides the same HTTPS endpoint as normal client traffic.

Can I use my own Matrix client instead of Element Web? Yes. Any Matrix client — Element for iOS and Android, FluffyChat, Cinny, Nheko — connects using your homeserver domain, and bots and bridges work through the appservice API.