Self-hosting a Matrix (Synapse) homeserver on a VPS: federation, Postgres, and the well-known trickEinen Matrix-Homeserver (Synapse) selbst hosten auf einem VPS: Federation, Postgres und der Well-known-Trick

What you are actually installingWas du hier eigentlich installierst

Synapse is the Matrix Foundation's reference homeserver: a Python application, a Postgres (or SQLite) database, and a media store, all speaking the Matrix client-server and server-server protocols. It is not a lightweight process — it does real cryptographic work verifying events from every server your users talk to, and it keeps a growing local copy of every room's history and state. Element is the reference client (web, desktop, iOS, Android) and talks to your homeserver the same way it talks to matrix.org; nothing about self-hosting changes how people chat once they are connected.Synapse ist der Referenz-Homeserver der Matrix Foundation: eine Python-Anwendung, eine Postgres- (oder SQLite-)Datenbank und ein Media-Store, die alle die Matrix-Client-Server- und Server-Server-Protokolle sprechen. Das ist kein leichtgewichtiger Prozess — er leistet echte kryptografische Arbeit beim Verifizieren von Events von jedem Server, mit dem deine Nutzer sprechen, und hält eine wachsende lokale Kopie der Historie und des Zustands jedes Raums vor. Element ist der Referenz-Client (Web, Desktop, iOS, Android) und spricht mit deinem Homeserver genauso wie mit matrix.org; am Chatten selbst ändert Self-Hosting nichts, sobald die Verbindung steht.

Federation is the feature that makes this worth the effort and the part that makes it worth reading this whole guide before you order anything: a Matrix homeserver is not an island by default. Anyone on any other homeserver — matrix.org included — can join a room your server hosts, and your users can join rooms hosted elsewhere, the same way email works across mail providers. You can also run Synapse with federation disabled, as a closed server for your own team, which removes most of the networking problems below entirely.Federation ist das Feature, das den Aufwand rechtfertigt, und der Grund, warum sich diese ganze Anleitung zu lesen lohnt, bevor du irgendetwas bestellst: Ein Matrix-Homeserver ist standardmäßig keine Insel. Jeder auf jedem anderen Homeserver — matrix.org eingeschlossen — kann einem Raum beitreten, den dein Server hostet, und deine Nutzer können Räumen beitreten, die anderswo gehostet werden, genauso wie E-Mail über Anbieter hinweg funktioniert. Du kannst Synapse auch mit deaktivierter Federation betreiben, als geschlossenen Server für dein eigenes Team, was die meisten der Netzwerkprobleme weiter unten komplett entfernt.

Two decisions matter before you touch Docker. First, server_name — your Matrix identity, since user IDs look like @alice:example.com — is effectively permanent; Synapse has no supported rename, so every existing user ID and piece of federated history refers to whatever you pick today. It does not have to match the hostname the software actually runs on: Matrix's well-known delegation mechanism (below) lets server_name stay a clean domain like example.com while the container runs on matrix.example.com. Second, the database: Synapse supports SQLite, and the project itself is direct about what that is for — development and small trials, not a real deployment. SQLite serialises writes behind a single lock, and federation means constant concurrent writes from every joined remote server; on a room with more than a handful of federated participants it becomes the bottleneck long before CPU or RAM does, and there is no live migration back out without Synapse's own offline synapse_port_db tool. Start with Postgres. It is one extra container and it saves you a migration you would otherwise do under pressure.Zwei Entscheidungen sind wichtig, bevor du Docker überhaupt anfasst. Erstens server_name — deine Matrix-Identität, da Nutzer-IDs wie @alice:example.com aussehen — ist praktisch dauerhaft; Synapse unterstützt keine Umbenennung, sodass jede bestehende Nutzer-ID und jedes Stück föderierter Historie sich auf das bezieht, was du heute wählst. Er muss nicht mit dem Hostnamen übereinstimmen, auf dem die Software tatsächlich läuft: Matrix' Well-known-Delegationsmechanismus (weiter unten) lässt server_name eine saubere Domain wie example.com bleiben, während der Container auf matrix.example.com läuft. Zweitens die Datenbank: Synapse unterstützt SQLite, und das Projekt selbst ist unmissverständlich, wofür das gedacht ist — Entwicklung und kleine Tests, kein echtes Deployment. SQLite serialisiert Schreibvorgänge hinter einer einzigen Sperre, und Federation bedeutet ständige gleichzeitige Schreibzugriffe von jedem verbundenen Remote-Server; in einem Raum mit mehr als einer Handvoll föderierter Teilnehmer wird das lange vor CPU oder RAM zum Flaschenhals, und es gibt keine Live-Migration zurück ohne Synapses eigenes Offline-Tool synapse_port_db. Fang mit Postgres an. Das ist ein zusätzlicher Container, und er erspart dir eine Migration, die du sonst unter Druck machen müsstest.

The compose fileDie Compose-Datei

Pin the image tags — the comments say where to check the current release. Versions shown are current as of September 2026; re-check all three before you deploy, since Synapse alone ships roughly monthly.Pinne die Image-Tags — die Kommentare sagen dir, wo du das aktuelle Release nachschaust. Die gezeigten Versionen sind Stand September 2026 aktuell; prüfe alle drei erneut, bevor du deployst, denn allein Synapse veröffentlicht ungefähr monatlich ein neues Release.

services:
  db:
    image: postgres:16  # check hub.docker.com/_/postgres for the current supported major
    restart: unless-stopped
    environment:
      - POSTGRES_DB=synapse
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_INITDB_ARGS=--encoding=UTF8 --locale=C
    volumes:
      - db_data:/var/lib/postgresql/data

  synapse:
    image: matrixdotorg/synapse:v1.116.0  # check hub.docker.com/r/matrixdotorg/synapse/tags for the current release
    restart: unless-stopped
    depends_on: [db]
    environment:
      - SYNAPSE_SERVER_NAME=example.com
      - SYNAPSE_REPORT_STATS=no
    volumes:
      - synapse_data:/data
    ports:
      - "127.0.0.1:8008:8008"

  element:
    image: vectorim/element-web:v1.11.86  # check hub.docker.com/r/vectorim/element-web/tags for the current release
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"

volumes:
  db_data:
  synapse_data:

Notice there is no 8448:8448 mapping here. Nothing inside the Synapse container listens on 8448 by default — the image's generated config puts client and federation traffic on the same 8008 listener — so publishing that port would just be a mapping to nothing. The well-known trick below is what actually gets federation traffic to your server, over 443, and it needs no extra port published at all.Beachte, dass es hier kein 8448:8448-Mapping gibt. Nichts innerhalb des Synapse-Containers lauscht standardmäßig auf 8448 — die generierte Konfiguration des Images legt Client- und Federation-Traffic auf denselben 8008-Listener — sodass das Veröffentlichen dieses Ports nur ein Mapping ins Leere wäre. Der Well-known-Trick weiter unten ist es, der Federation-Traffic tatsächlich zu deinem Server bringt, über 443, und dafür muss überhaupt kein zusätzlicher Port veröffentlicht werden.

Before you run anything else, create a .env file next to the compose file — both the db container and the one-off generate step below read POSTGRES_PASSWORD/DB_PASSWORD from it, and Compose loads .env automatically:Bevor du irgendetwas anderes ausführst, leg eine .env-Datei neben der Compose-Datei an — sowohl der db-Container als auch der einmalige generate-Schritt weiter unten lesen POSTGRES_PASSWORD/DB_PASSWORD daraus, und Compose lädt .env automatisch:

printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .env

The first run needs a generated config before synapse_data has anything useful in it:Der erste Lauf braucht eine generierte Konfiguration, bevor in synapse_data irgendetwas Sinnvolles steckt:

docker compose run --rm -e SYNAPSE_SERVER_NAME=example.com -e SYNAPSE_REPORT_STATS=no synapse generate

That writes homeserver.yaml and a signing key into the synapse_data volume. Open homeserver.yaml afterward and point the database block at Postgres — the generator defaults to SQLite even when Postgres is sitting right next to it in the compose file, so this edit is not optional:Das schreibt homeserver.yaml und einen Signing-Key in das Volume synapse_data. Öffne danach homeserver.yaml und richte den database-Block auf Postgres aus — der Generator setzt standardmäßig SQLite, selbst wenn Postgres direkt daneben in der Compose-Datei steht, also ist diese Änderung nicht optional:

database:
  name: psycopg2
  args:
    user: synapse
    password: paste-your-DB_PASSWORD-value-here
    database: synapse
    host: db
    cp_min: 5
    cp_max: 10

That password has to be the exact string you generated into .env as DB_PASSWORD — Postgres and Synapse are authenticating with the same credential from two independent config files, and there is nothing that checks they match for you; a mismatch fails as a connection error at startup, not a clear "wrong password" message.Dieses password muss exakt der String sein, den du in die .env als DB_PASSWORD generiert hast — Postgres und Synapse authentifizieren sich mit demselben Credential aus zwei unabhängigen Konfigurationsdateien, und nichts prüft für dich, ob sie übereinstimmen; eine Abweichung schlägt beim Start als Verbindungsfehler fehl, nicht als klare Meldung „falsches Passwort“.

Then bring the stack up:Dann fahre den Stack hoch:

docker compose up -d

Caddy in front, and the two ports that both matterCaddy davor, und die zwei Ports, auf die es ankommt

Clients talk to Synapse over ordinary HTTPS on 443. Federation is different: other homeservers reach yours over port 8448 by default, and the well-known trick below is how you avoid actually needing that port open at all.Clients sprechen mit Synapse über gewöhnliches HTTPS auf 443. Federation ist anders: Andere Homeserver erreichen deinen standardmäßig über Port 8448, und der Well-known-Trick weiter unten ist der Weg, wie du vermeidest, diesen Port überhaupt offen haben zu müssen.

example.com {
    redir /.well-known/matrix/server `{"m.server": "matrix.example.com:443"}` 200
    redir /.well-known/matrix/client `{"m.homeserver": {"base_url": "https://matrix.example.com"}}` 200
    header /.well-known/matrix/* Content-Type application/json
}

matrix.example.com {
    reverse_proxy 127.0.0.1:8008
}

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

That top block is the well-known delegation, and it is what lets server_name stay the clean example.com while the actual server answers on matrix.example.com. Other homeservers fetch https://example.com/.well-known/matrix/server to find out where to actually send federation traffic, over plain HTTPS on 443 — which is also why the well-known trick is the way around a NAT IPv4 plan that does not happen to forward 8448: you are not asking it to forward anything beyond whatever it already forwards for HTTPS. The third block is Element, reachable at its own hostname; point DNS at all three names first — point your domain at your service if you have not done that before — and set Element's config.json base_url to https://matrix.example.com so the web client knows which homeserver to talk to.Dieser oberste Block ist die Well-known-Delegation, und er ist es, der server_name das saubere example.com bleiben lässt, während der eigentliche Server auf matrix.example.com antwortet. Andere Homeserver rufen https://example.com/.well-known/matrix/server ab, um herauszufinden, wohin sie Federation-Traffic tatsächlich schicken sollen, über gewöhnliches HTTPS auf 443 — was auch der Grund ist, warum der Well-known-Trick der Weg um einen NAT-IPv4-Plan herum ist, der 8448 zufällig nicht weiterleitet: Du verlangst von ihm nichts, was über das hinausgeht, was er ohnehin schon für HTTPS weiterleitet. Der dritte Block ist Element, erreichbar unter seinem eigenen Hostnamen; richte DNS zuerst auf alle drei Namen aus — richte deine Domain auf deinen Dienst aus, falls du das noch nicht getan hast — und setze in Elements config.json base_url auf https://matrix.example.com, damit der Web-Client weiß, mit welchem Homeserver er sprechen soll.

Read this before you buy: NAT IPv4 and port 8448Lies das, bevor du kaufst: NAT-IPv4 und Port 8448

A federated homeserver needs its server_name domain to answer on 443 for the well-known lookup, and needs something to answer on 8448 — or on whatever port the well-known JSON points remote servers at instead, since the delegation record can name any port. A NAT IPv4 plan hands out a shared address with a specific, fixed set of forwarded ports, not every port you ask for, and whether 8448 happens to be one of them depends on the plan.Ein föderierter Homeserver braucht, dass seine server_name-Domain für den Well-known-Lookup auf 443 antwortet, und braucht etwas, das auf 8448 antwortet — oder auf welchem Port auch immer das Well-known-JSON Remote-Server stattdessen hinweist, da der Delegationseintrag jeden beliebigen Port benennen kann. Ein NAT-IPv4-Plan gibt eine geteilte Adresse mit einer bestimmten, festen Menge weitergeleiteter Ports aus, nicht jeden Port, den du verlangst, und ob 8448 zufällig dazugehört, hängt vom Plan ab.

The well-known delegation above is the actual fix, not a workaround: instead of asking remote servers to reach you on 8448 at all, the m.server record can point them at matrix.example.com:443 — the same port Caddy is already using for client traffic, so if your plan forwards 443 at all, you are not asking it to forward a second, unusual port just for federation. Check your plan's forwarded-port list either way. Federation and client traffic then share port 443 through the same reverse proxy, and 8448 never needs to be reachable from the outside. If you would rather run a literal listener on 8448, check which ports your plan forwards first, and see NAT IPv4 vs a dedicated IP and NAT IPv4, ports and forwarding for the difference between that and a dedicated IPv4, which is arranged by e-mail rather than self-service on our plans.Die Well-known-Delegation oben ist die eigentliche Lösung, kein Workaround: Statt Remote-Server überhaupt zu bitten, dich auf 8448 zu erreichen, kann der m.server-Eintrag sie auf matrix.example.com:443 verweisen — denselben Port, den Caddy für Client-Traffic bereits nutzt, sodass du, falls dein Plan 443 überhaupt weiterleitet, ihn nicht bittest, einen zweiten, ungewöhnlichen Port nur für Federation weiterzuleiten. Prüf die Liste der weitergeleiteten Ports deines Plans trotzdem. Federation- und Client-Traffic teilen sich dann Port 443 über denselben Reverse-Proxy, und 8448 muss nie von außen erreichbar sein. Willst du lieber einen echten Listener auf 8448 betreiben, prüfe zuerst, welche Ports dein Plan weiterleitet, und sieh dir NAT IPv4 vs. dedizierte IP und NAT IPv4, Ports und Weiterleitung für den Unterschied zu einer dedizierten IPv4 an, die bei uns per E-Mail statt per Self-Service geregelt wird.

Registration is off by default, and that is correctRegistrierung ist standardmäßig aus, und das ist richtig so

A fresh Synapse install ships with open registration disabled — nobody, including you, can create an account until you decide otherwise. Create your own first user from the host, against the running container:Eine frische Synapse-Installation kommt mit deaktivierter offener Registrierung — niemand, dich eingeschlossen, kann ein Konto anlegen, bis du etwas anderes entscheidest. Leg deinen eigenen ersten Nutzer vom Host aus an, gegen den laufenden Container:

docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

It prompts for a username, a password, and whether the account should be an admin — say yes for your own account. Leave enable_registration unset (or false) in homeserver.yaml for anything federated; an open registration form on a server that talks to the whole Matrix network is an invitation to abuse it did not ask for. If you do want self-service signup later, registration_requires_token lets you gate it behind an invite token instead of leaving it wide open.Es fragt nach einem Benutzernamen, einem Passwort und ob der Account Admin sein soll — sag Ja für deinen eigenen Account. Lass enable_registration in homeserver.yaml unangetastet (oder false) bei allem, was föderiert; ein offenes Registrierungsformular auf einem Server, der mit dem gesamten Matrix-Netzwerk spricht, ist eine Einladung zu Missbrauch, um den er nicht gebeten hat. Willst du später doch Self-Service-Signup, lässt dich registration_requires_token das hinter einem Einladungstoken absichern, statt es weit offen zu lassen.

Media, retention, and the disk you did not budget forMedien, Aufbewahrung und die Festplatte, die du nicht eingeplant hast

Synapse's media repository stores every image, file and thumbnail anyone sends, plus a cached copy of anything from remote users in rooms you share with them — remote media is not something you chose to store, it just accumulates. Two settings in homeserver.yaml are the ones that keep this from becoming an unbounded liability:Synapses Media-Repository speichert jedes Bild, jede Datei und jedes Thumbnail, das irgendjemand verschickt, plus eine gecachte Kopie von allem, was von Remote-Nutzern in Räumen kommt, die du mit ihnen teilst — Remote-Medien sind nichts, was du bewusst zu speichern beschlossen hast, sie sammeln sich einfach an. Zwei Einstellungen in homeserver.yaml sind es, die verhindern, dass daraus eine unbegrenzte Last wird:

• media_store_path — where it all lives on disk; know this path before you decide how much storage to give the VPS.media_store_path — wo das alles auf der Festplatte liegt; kenn diesen Pfad, bevor du entscheidest, wie viel Speicher du dem VPS gibst.
• media_retention — lets you set local_media_lifetime and remote_media_lifetime so Synapse actually expires cached remote media instead of keeping it forever; unset, the default is to keep everything indefinitely.media_retention — erlaubt dir, local_media_lifetime und remote_media_lifetime zu setzen, damit Synapse gecachte Remote-Medien tatsächlich verfallen lässt, statt sie für immer zu behalten; ungesetzt ist die Vorgabe, alles unbegrenzt zu behalten.

Run docker compose exec synapse du -sh /data/media_store occasionally rather than finding out from a full-disk error. A handful of active federated rooms with image-heavy conversations is what actually fills a small VPS's disk over months, not the room state itself. add extra storage to your VPS covers adding disk on our machines if you get there before you expected to.Führ gelegentlich docker compose exec synapse du -sh /data/media_store aus, statt es an einer vollgelaufenen Festplatte zu bemerken. Eine Handvoll aktiver föderierter Räume mit bildlastigen Unterhaltungen ist es, was die Festplatte eines kleinen VPS im Lauf von Monaten tatsächlich füllt, nicht der Raumzustand selbst. zusätzlichen Speicher zu deinem VPS hinzufügen behandelt das Hinzufügen von Speicherplatz auf unseren Maschinen, falls du früher dort ankommst, als du erwartet hast.

Sizing this honestlyEhrlich dimensioniert

2 GiB of RAM is the real minimum the Synapse project itself states for a small server, and that number assumes a quiet, lightly federated instance — a handful of users and joined rooms, nobody dumping a busy public room into your server's state resolution. Add Postgres, Element's static web bundle and any real federation traffic, and 2 GiB leaves no slack for the moment state resolution has to reconcile a room with a complicated membership history — a genuinely CPU- and memory-spiky operation. A Standard (4 GiB) tier is the honest floor for daily use with federation on; Pro (8 GiB) is where Postgres, Synapse, Element and normal federation churn stop competing for the same headroom, and is what this guide is written against. run a database on your VPS covers running Postgres itself if this is your first time putting a real database on a VPS.2 GiB RAM sind das echte Minimum, das das Synapse-Projekt selbst für einen kleinen Server angibt, und diese Zahl geht von einer ruhigen, leicht föderierten Instanz aus — eine Handvoll Nutzer und beigetretener Räume, niemand, der einen belebten öffentlichen Raum in die State Resolution deines Servers kippt. Zähl Postgres, Elements statisches Web-Bundle und echten Federation-Traffic dazu, und 2 GiB lassen keinen Spielraum für den Moment, in dem die State Resolution einen Raum mit komplizierter Mitgliederhistorie abgleichen muss — eine echt CPU- und speicherlastige Operation. Eine Standard-Stufe (4 GiB) ist die ehrliche Untergrenze für den täglichen Einsatz mit eingeschalteter Federation; Pro (8 GiB) ist der Punkt, an dem Postgres, Synapse, Element und normaler Federation-Traffic nicht mehr um denselben Spielraum konkurrieren, und genau darauf ist diese Anleitung ausgelegt. eine Datenbank auf deinem VPS betreiben behandelt den Betrieb von Postgres selbst, falls du zum ersten Mal eine echte Datenbank auf einen VPS stellst.

The thing that bites later: state resolution and old roomsWas dich später beißt: State Resolution und alte Räume

Synapse's slowest, most memory-hungry operation is not sending messages — it is state resolution, the process of reconciling who is in a room and what the current room state is when federated servers disagree about history, which happens constantly in any room with more than a few joined homeservers. A single old, large, long-federated public room joined out of curiosity can quietly dominate your server's CPU and memory long after everyone in it stopped talking, because your server still has to process every state change in it forever. Leaving large public rooms you do not actually use is not just tidiness — on a small server it is the difference between snappy and mysteriously slow.Synapses langsamste, speicherhungrigste Operation ist nicht das Versenden von Nachrichten — es ist State Resolution, der Prozess, abzugleichen, wer in einem Raum ist und was der aktuelle Raumzustand ist, wenn föderierte Server sich über die Historie uneinig sind, was in jedem Raum mit mehr als ein paar beigetretenen Homeservern ständig passiert. Ein einzelner alter, großer, lange föderierter öffentlicher Raum, dem du aus Neugier beigetreten bist, kann still CPU und Speicher deines Servers dominieren, lange nachdem alle darin aufgehört haben zu reden, weil dein Server trotzdem jede Zustandsänderung darin für immer verarbeiten muss. Große öffentliche Räume zu verlassen, die du eigentlich nicht nutzt, ist nicht nur Ordnung — auf einem kleinen Server ist es der Unterschied zwischen flott und mysteriös langsam.

On overnight.hostBei overnight.host

Full disclosure: this is what we sell. A Pro (4 vCPU / 8 GiB / 120 GB) gives Synapse, Postgres and Element real headroom for a small federated homeserver; a Standard (4 GiB) is the honest floor once you accept a modest room count, and Postgres is the database that keeps either tier from choking on state resolution.Zur vollen Transparenz: Das ist, was wir verkaufen. Ein Pro (4 vCPU / 8 GiB / 120 GB) gibt Synapse, Postgres und Element echten Spielraum für einen kleinen föderierten Homeserver; ein Standard (4 GiB) ist die ehrliche Untergrenze, sobald du eine bescheidene Raumanzahl akzeptierst, und Postgres ist die Datenbank, die verhindert, dass eine der beiden Stufen an der State Resolution erstickt.

Linux KVM VPS — EUR 4.99 to EUR 59.99 a month, on our own single-tenant bare metal in Dallas, TX and Charlotte, NC. Full hardware virtualisation (KVM), your own kernel, full root. Six tiers, vps-starter to vps-ultra. Starter is 1 vCPU, 1 GiB RAM, 25 GB disk.Linux-KVM-VPS — 4,99 bis 59,99 EUR im Monat, auf unserer eigenen Single-Tenant-Bare-Metal-Hardware in Dallas, TX und Charlotte, NC. Vollständige Hardware-Virtualisierung (KVM), eigener Kernel, volles Root. Sechs Tarife, vps-starter bis vps-ultra. Starter hat 1 vCPU, 1 GiB RAM, 25 GB Speicher.

You order in the shop, pay by card (Stripe) or SEPA bank transfer, and your login details are e-mailed to you once the service is set up. Support is e-mail, run by one person, with no guaranteed response time. All prices are final totals under the German small-business rule (§19 UStG); no VAT is added or shown.Du bestellst im Shop, zahlst per Karte (Stripe) oder SEPA-Überweisung, und deine Zugangsdaten werden dir per E-Mail zugeschickt, sobald der Dienst eingerichtet ist. Support läuft per E-Mail, von einer einzelnen Person betrieben, ohne garantierte Reaktionszeit. Alle Preise sind Endpreise. Gemäß § 19 UStG wird keine Umsatzsteuer ausgewiesen.

Order vps-pro → · Linux KVM VPS overviewvps-pro bestellen → · Übersicht Linux-KVM-VPS

Written by the person who runs overnight.host: a small, honest hosting company on dedicated bare metal — Linux VPS, game servers, web hosting. Live status at up.overnight.host.Geschrieben von der Person, die overnight.host betreibt: ein kleines, ehrliches Hosting-Unternehmen auf dedizierter Bare-Metal-Hardware — Linux-VPS, Gameserver, Webhosting. Live-Status unter up.overnight.host.