Matrix AiO

Text like nobody's reading. Because nobody can.

   

What is this?

Your own Matrix homeserver, without assembling it yourself. This is a wrapper around the official Synapse image that adds everything a working server actually needs: coturn for voice and video relay, Element Web as the client, and the Ketesa admin interface, all behind one lightweight web server. You fill in your domain and your PostgreSQL connection; the container generates every config file itself. No SSH into the container, no YAML editing, no hand-written TURN secrets.

Because it builds on top of the official image rather than alongside it, Synapse security patches land here as soon as upstream ships them. A workflow checks hourly and rebuilds automatically — and no build ships blind: CI boots each freshly built image against a throwaway PostgreSQL and refuses to publish it unless Synapse is demonstrably running on that database.

Highlights

• Everything in one container — Synapse (:8008), Element Web (:8080/element/), Ketesa admin UI (:8080/admin/), coturn, Prometheus metrics

• Config is generated, not edited — set SERVER_NAME and your Postgres details and start; overrides are re-rendered on every boot, so changing a setting is a container restart

• Federation works out of the box — Synapse serves /.well-known/matrix/server and /.well-known/matrix/client itself, so no extra reverse-proxy rules are needed

• Voice and video that actually connects — coturn with a pinned relay port range, optional TURN over TLS that switches itself on when you mount a certificate

• QR code device linking (new, opt-in) — sign a new device in by scanning a code, via Matrix Authentication Service. Off by default and it stays off until you enable it

• Admin account bootstrap — set two variables and the first server admin is created, or an existing account promoted

• Startup that fails loudly — a broken configuration stops the container with the reason in the log rather than quietly running on wrong settings

• Multi-arch — amd64 + arm64

• Image: ghcr.io/junkerderprovinz/matrix:latest (mirrored to junkerderprovinz/matrix on Docker Hub)

Requirements

• Unraid 6.10+

• PostgreSQL, external, and the database must use UTF8 with C collation or Synapse refuses to start:
  CREATE DATABASE matrix ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE template0 OWNER matrix;

• A reverse proxy for matrix.yourdomain.tld to Unraid-IP :8008. In the proxy host's Advanced tab add client_max_body_size 100m; and generous timeouts, or media uploads fail and long-polling sync times out

• For voice and video: the TURN relay UDP range must be reachable, so a port forward rather than a tunnel

• Only if you want QR code login: a second, empty PostgreSQL database and a second reverse-proxy host with HTTPS. The README explains what enabling it changes before you flip anything

Posting a bug report

Please post:

• Unraid version (Settings → System Information)

• Image tag (latest or a pinned vX.Y.Z) — and please confirm you actually pulled it; Unraid happily reuses a cached image on the same tag

• Output of docker logs --tail 200 Matrix

• Your SERVER_NAME (the domain is fine, no credentials) and whether the reverse proxy sits in front

• Whether you changed ENABLE_FEDERATION, ENABLE_REGISTRATION, the TURN variables, or anything in the Delegated Auth block

• For database errors: the output of \l in psql, so the encoding and collation are visible

GitHub issues with the same info are also welcome: github.com/junkerderprovinz/matrix/issues

Credits

Built on Synapse and Element by Element, the Matrix Authentication Service, Ketesa by etke.cc (the maintained continuation of Synapse Admin), and coturn. All used unmodified, each under its own license. If this saved you an evening of YAML, you can buy me a coffee.

---

Self-hosted, AGPL-3.0 licensed — you run it, you own your data and the responsibility. Not affiliated with Element or the Matrix.org Foundation.

Edited August 4Aug 4 by Junker der Provinz

Would I be able to use a cloudflare tunnel or do I need to utilize a reverse proxy setup to access? Thanks in advance

23 hours ago, 01111000 said:

Would I be able to use a cloudflare tunnel or do I need to utilize a reverse proxy setup to access? Thanks in advance

Both work, you don't strictly need a reverse proxy.

A Cloudflare Tunnel is fine for client access and means zero open ports. Two things to know: Cloudflare caps uploads at 100 MB (the README already uses 100M, so that lines up), and for federation you still need the .well-known delegation to 443 (section 6 in the README). Voice/video (TURN) is UDP and can't go through a tunnel or proxy, so forward those ports either way.

A normal reverse proxy (NPM, what the README documents) is the cleaner option if you want federation plus bigger media. And if you ever use Cloudflare's orange-cloud proxy instead of a tunnel, set the Matrix subdomain to DNS only (grey cloud), the orange proxy breaks non-browser clients and federation.

v2.4.0 is out. Two things in here matter to everyone, and one is opt-in.

Everyone gets a long-overdue Element update

The build workflow pinned Element Web and the admin UI in its own environment and passed those values as build arguments, which silently overrode the Dockerfile. The published image had been shipping Element Web 1.11.92 while the Dockerfile advertised 1.12.23, and the dependency bot had been dutifully opening update PRs against values that never reached the built image. Versions now live in one place, so this release carries the Element jump that had been stuck.

In the same pass the admin UI moved from Synapse-Admin, whose last release was in March, to Ketesa — the maintained continuation by etke.cc. Same URL at :8080/admin/, drop-in replacement, still actively developed.

A startup guard that had been decorative

The init scripts have claimed since v2.1.1 to halt the container on a broken configuration so the problem is visible. They did not. s6-overlay defaults to "continue silently" when an init script fails, so a missing SERVER_NAME or a failed config generation produced a running-but-wrong container instead of a loud stop. It now actually stops, with the reason in the log.

QR code device linking, opt-in

If you have ever opened Element's Settings → Sessions → Link new device and found Show QR code greyed out with "Not supported by your account provider", that is not an Element bug. QR device linking is built on OAuth 2.0, and a plain Synapse with password logins has none to offer. Synapse will not even start with the feature flag unless authentication is delegated.

So this release ships Matrix Authentication Service inside the image. It is off by default and does nothing until you turn it on. With the switch off, not one byte of the generated Synapse config differs from before — that is asserted in CI on every build, because a container update should never rearrange anybody's authentication.

Turning it on is a real decision, not a checkbox. It needs a second empty PostgreSQL database and a second reverse-proxy host with HTTPS, and it changes how people sign in: the password field disappears in favour of a browser flow, login by email address stops working, password changes move to the auth service's own web UI, and encrypted bridges break. Your existing accounts stay in Synapse until you migrate them, which the container can now do for you on the next start — it runs before Synapse comes up, which is exactly the offline window the migration needs. Users keep their sessions and are not signed out.

The README section Delegated Auth and QR Code Login spells all of that out, including what breaks. Read it before enabling anything, and take a database backup: once the auth service has started and someone has signed in, only a restore undoes the migration.

Upgrading

Nothing to do beyond the usual update. If you do not touch the Delegated Auth fields, the container behaves exactly as it did before. Force Update rather than a plain restart, since Unraid will otherwise happily reuse the cached image on the same tag.

Full changelog: github.com/junkerderprovinz/matrix/releases/tag/v2.4.0

---

As always, bug reports with the Unraid version, the image tag and docker logs --tail 200 Matrix get sorted fastest.