Anleitung gesucht für Matrix/Element selbstgehostet.

wendy2702

Hi,

Hat jemand eine gute Anleitung zur Installation und Einrichtung eines selbst gehosteten Matrix/Element Systems.

Der Server soll hinter eine bereits existierenden Reverse Proxy betrieben werden.

Bin für Hinweise dankbar!

Jey Cee

@wendy2702 Da wäre ich auch dran interessiert. Ich habe das schon mal versucht und es war super Kompliziert.

wendy2702

Ja, das scheint nicht ganz trivial zu sein.

Man kann sich das zwar mit den Proxmox Helper Scripten komplett installieren lassen aber dann hänge ich erstmal bei der Konfiguration.

Deshalb dachte ich eine Schritt für Schritt Anleitung hilft mir da besser zu verstehen was, wie und wo konfiguriert werden muss und wird.

bloop

SOP aus meinem Chatverlauf mit Claude:
Matrix Server läuft einwandfrei.

SOP – Matrix Synapse Homeserver Setup

1. Voraussetzungen

Hardware / Infrastruktur

Proxmox LXC Container (Ubuntu 24.04)
RAM: mindestens 4 GB (für Synapse + Bridges)
Disk: mindestens 20 GB

Software

apt update && apt upgrade -y
apt install -y curl wget git python3 python3-pip python3-venv \
  libolm-dev libpq-dev nginx postgresql

Timezone setzen

timedatectl set-timezone Europe/Vienna

2. Synapse Installation

apt install -y lsb-release wget apt-transport-https
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg \
  https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] \
  https://packages.matrix.org/debian/ $(lsb_release -cs) main" \
  > /etc/apt/sources.list.d/matrix-org.list

apt update
apt install -y matrix-synapse-py3

systemctl enable matrix-synapse

3. PostgreSQL Datenbank

systemctl enable postgresql
systemctl start postgresql

sudo -u postgres psql << 'EOF'
CREATE USER synapse WITH PASSWORD 'SICHERES_PASSWORT';
CREATE DATABASE synapse
  ENCODING 'UTF8'
  LC_COLLATE='C'
  LC_CTYPE='C'
  template=template0
  OWNER synapse;
EOF

Verbindung testen:

psql -h localhost -U synapse -d synapse -c "SELECT 1;"

4. Synapse Konfiguration

nano /etc/matrix-synapse/homeserver.yaml

Minimale Pflicht-Konfiguration

server_name: "matrix.example.com"
public_baseurl: "https://matrix.example.com/"
pid_file: "/var/run/matrix-synapse.pid"
serve_server_wellknown: true

listeners:
  - bind_addresses:
      - '0.0.0.0'
    port: 8008
    resources:
      - names: [client, federation]
        compress: false
    tls: false
    type: http
    x_forwarded: true

database:
  name: psycopg2
  args:
    user: synapse
    password: SICHERES_PASSWORT
    database: synapse
    host: localhost
    cp_min: 5
    cp_max: 10

report_stats: false
suppress_key_server_warning: true

# Automatisch generieren:
macaroon_secret_key: "GENERIERTER_KEY"
registration_shared_secret: "GENERIERTER_KEY"

# Performance
presence:
  enabled: false
event_cache_size: 10K
caches:
  global_factor: 2.0

# Rate Limits (für Bots anpassen)
rc_login:
  address:
    per_second: 100
    burst_count: 100
  account:
    per_second: 100
    burst_count: 100
  failed_attempts:
    per_second: 100
    burst_count: 100

Secrets generieren

# macaroon_secret_key
python3 -c "import secrets; print(secrets.token_hex(32))"

# registration_shared_secret
python3 -c "import secrets; print(secrets.token_hex(32))"

Synapse starten

systemctl restart matrix-synapse
systemctl status matrix-synapse

Synapse testen

curl -s http://localhost:8008/_matrix/client/versions | python3 -m json.tool | head -5

5. Nginx Reverse Proxy (lokal)

nginx wird für drei Zwecke verwendet:

Element Web auf Port 80 (lokal erreichbar via http://192.168.X.X)
Synapse Admin UI auf Port 8081 (lokal erreichbar via http://192.168.X.X:8081)
Well-Known Dateien für Matrix Federation Discovery

nginx installieren

apt install -y nginx

Element Web auf Port 80

cat > /etc/nginx/sites-available/element << 'EOF'
server {
    listen 80 default_server;
    server_name chat.example.com 192.168.X.X;

    # Well-Known für Matrix Federation
    location /.well-known/matrix/ {
        root /var/www/html;
        default_type application/json;
        add_header Access-Control-Allow-Origin *;
    }

    # Element Web Static Files
    location / {
        root /var/www/element;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}
EOF

ln -s /etc/nginx/sites-available/element /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx

Synapse Admin UI auf Port 8081

Die Synapse Admin UI ist eine separate React Web-App (von Awesome-Technologies)
die als statische HTML/JS/CSS Dateien über nginx ausgeliefert wird.
Sie kommuniziert direkt mit der Synapse API – kein eigener Backend-Prozess nötig.

cat > /etc/nginx/sites-available/synapse-admin << 'EOF'
server {
    listen 8081;
    server_name 192.168.X.X;
    root /var/www/synapse-admin;
    index index.html;

    # SPA Routing
    location / {
        try_files $uri $uri/ /index.html;
    }
}
EOF

ln -s /etc/nginx/sites-available/synapse-admin /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Ports prüfen

ss -tlnp | grep -E "80|8081"
# Erwartet:
# 0.0.0.0:80    → nginx (Element Web)
# 0.0.0.0:8081  → nginx (Synapse Admin)

Well-Known Dateien

mkdir -p /var/www/html/.well-known/matrix

cat > /var/www/html/.well-known/matrix/client << 'EOF'
{"m.homeserver":{"base_url":"https://matrix.example.com"}}
EOF

cat > /var/www/html/.well-known/matrix/server << 'EOF'
{"m.server":"matrix.example.com:443"}
EOF

Well-Known verifizieren

curl -s http://192.168.X.X/.well-known/matrix/client
# Erwartet: {"m.homeserver":{"base_url":"https://matrix.example.com"}}

curl -s http://192.168.X.X/.well-known/matrix/server
# Erwartet: {"m.server":"matrix.example.com:443"}

6. Reverse Proxy (extern)

Reverse Proxy übernimmt TLS-Terminierung und leitet externe Requests intern weiter.

Architektur

Internet (HTTPS)
    │
    ▼
Reverse Proxy (TLS/Let's Encrypt)
    ├── matrix.example.com → 192.168.X.X:8008  (Synapse API)
    └── chat.example.com   → 192.168.X.X:80    (nginx → Element Web)

Wichtig: Synapse Admin UI (192.168.X.X:8081) wird NICHT über Reverse Proxy
nach außen geleitet – nur intern erreichbar!

7. Element Web Installation

Element Web ist eine eigenständige React Web-App (von element-hq).
Sie wird als statische HTML/JS/CSS Dateien über nginx ausgeliefert.
Kein eigener Backend-Prozess – nur nginx liefert die Dateien aus.
Die App kommuniziert direkt mit der Synapse API via Browser.

mkdir -p /var/www/element
cd /tmp

LATEST=$(curl -s https://api.github.com/repos/element-hq/element-web/releases/latest \
  | grep tag_name | cut -d'"' -f4)

wget "https://github.com/element-hq/element-web/releases/download/${LATEST}/element-${LATEST}.tar.gz"
tar xzf element-${LATEST}.tar.gz
cp -r element-${LATEST}/* /var/www/element/
cp /var/www/element/config.sample.json /var/www/element/config.json

config.json anpassen

nano /var/www/element/config.json

{
    "default_server_config": {
        "m.homeserver": {
            "base_url": "https://matrix.example.com",
            "server_name": "matrix.example.com"
        },
        "m.identity_server": {
            "base_url": "https://vector.im"
        }
    },
    "disable_custom_urls": false,
    "disable_guests": false,
    "brand": "Element"
}

Aufruf

Lokal: http://192.168.X.X
Extern: https://chat.example.com

Wichtig Browser-Cache: Bei Änderungen an config.json immer
Browser-Cache vollständig leeren (F12 → Application → Clear site data)

8. Synapse Admin UI

Synapse Admin ist eine eigenständige React Web-App (von Awesome-Technologies).
Wie Element Web wird sie als statische Dateien über nginx ausgeliefert – Port 8081.
Sie kommuniziert direkt mit der Synapse Admin API (/_synapse/admin/).
Nur lokal erreichbar – nicht über Zoraxy nach außen geleitet!

mkdir -p /var/www/synapse-admin
cd /tmp

LATEST=$(curl -s https://api.github.com/repos/Awesome-Technologies/synapse-admin/releases/latest \
  | grep tag_name | cut -d'"' -f4)

wget "https://github.com/Awesome-Technologies/synapse-admin/releases/download/${LATEST}/synapse-admin-${LATEST}.tar.gz"
tar xzf synapse-admin-${LATEST}.tar.gz
cp -r synapse-admin-${LATEST}/* /var/www/synapse-admin/

nginx-Vhost wurde bereits in Kapitel 5 erstellt (Port 8081)

Aufruf: http://192.168.X.X:8081

Login

Feld	Wert
Nutzername	`admin`
Passwort	Admin-Passwort
Heimserver URL	`https://matrix.example.com`

Wichtig: Heimserver URL muss die externe HTTPS-URL sein,
nicht die interne IP – sonst "Failed to fetch"!

9. Admin-User anlegen

register_new_matrix_user \
  -c /etc/matrix-synapse/homeserver.yaml \
  -u admin \
  -p 'SICHERES_PASSWORT' \
  --admin \
  http://localhost:8008

Login testen

curl -s -X POST http://localhost:8008/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"admin","password":"SICHERES_PASSWORT"}' \
  | python3 -m json.tool

10. Bridges

PostgreSQL Datenbanken für Bridges anlegen

sudo -u postgres psql << 'EOF'
CREATE USER mautrix WITH PASSWORD 'BridgeDB_PASSWORT';
CREATE DATABASE mautrix_whatsapp ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER mautrix;
CREATE DATABASE mautrix_discord  ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER mautrix;
CREATE DATABASE mautrix_telegram ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER mautrix;
CREATE DATABASE mautrix_signal   ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER mautrix;
EOF

Bridge-Registrierungen in homeserver.yaml eintragen

app_service_config_files:
  - /etc/matrix-synapse/whatsapp-registration.yaml
  - /etc/matrix-synapse/discord-registration.yaml
  - /etc/matrix-synapse/telegram-registration.yaml

Nach jeder Änderung: systemctl restart matrix-synapse

10.1 WhatsApp Bridge

mkdir -p /opt/bridges/whatsapp
cd /opt/bridges/whatsapp

wget https://github.com/mautrix/whatsapp/releases/latest/download/mautrix-whatsapp-amd64
chmod +x mautrix-whatsapp-amd64

# Beispiel-Config generieren
./mautrix-whatsapp-amd64 -e -c config.yaml

config.yaml (Pflichtfelder)

homeserver:
    address: http://localhost:8008
    domain: matrix.example.com

appservice:
    address: http://localhost:29318
    hostname: 0.0.0.0
    port: 29318
    database: postgres://mautrix:BridgeDB_PASSWORT@localhost/mautrix_whatsapp

bridge:
    permissions:
        "*": relay
        "matrix.example.com": user
        "@admin:matrix.example.com": admin

# Registration generieren
./mautrix-whatsapp-amd64 -g -c config.yaml -r registration.yaml

# In Synapse registrieren
cp registration.yaml /etc/matrix-synapse/whatsapp-registration.yaml
chown matrix-synapse:matrix-synapse /etc/matrix-synapse/whatsapp-registration.yaml
systemctl restart matrix-synapse

Systemd Service

cat > /etc/systemd/system/mautrix-whatsapp.service << 'EOF'
[Unit]
Description=mautrix-whatsapp bridge
After=matrix-synapse.service

[Service]
Type=simple
WorkingDirectory=/opt/bridges/whatsapp
ExecStart=/opt/bridges/whatsapp/mautrix-whatsapp-amd64 -c config.yaml
Restart=always
User=root

[Install]
WantedBy=multi-user.target
EOF

systemctl enable mautrix-whatsapp
systemctl start mautrix-whatsapp

WhatsApp Login

In Element Web → Neuer Chat → @whatsappbot:matrix.example.com → login

10.2 Discord Bridge

mkdir -p /opt/bridges/discord
cd /opt/bridges/discord

wget https://github.com/mautrix/discord/releases/latest/download/mautrix-discord-amd64
chmod +x mautrix-discord-amd64

wget https://raw.githubusercontent.com/mautrix/discord/main/example-config.yaml -O config.yaml

config.yaml (Pflichtfelder)

homeserver:
    address: http://localhost:8008
    domain: matrix.example.com

appservice:
    address: http://localhost:29334
    hostname: 0.0.0.0
    port: 29334
    database:
        type: postgres
        uri: postgres://mautrix:BridgeDB_PASSWORT@localhost/mautrix_discord

bridge:
    permissions:
        "*": relay
        "matrix.example.com": user
        "@admin:matrix.example.com": admin

# Tippfehler korrigieren falls vorhanden
sed -i 's/matrix.amting.xyz/matrix.example.com/g' config.yaml

# Registration generieren
./mautrix-discord-amd64 -g -c config.yaml -r registration.yaml

cp registration.yaml /etc/matrix-synapse/discord-registration.yaml
chown matrix-synapse:matrix-synapse /etc/matrix-synapse/discord-registration.yaml
systemctl restart matrix-synapse

Systemd Service

cat > /etc/systemd/system/mautrix-discord.service << 'EOF'
[Unit]
Description=mautrix-discord bridge
After=matrix-synapse.service

[Service]
Type=simple
WorkingDirectory=/opt/bridges/discord
ExecStart=/opt/bridges/discord/mautrix-discord-amd64 -c config.yaml
Restart=always
User=root

[Install]
WantedBy=multi-user.target
EOF

systemctl enable mautrix-discord
systemctl start mautrix-discord

Discord Login

In Element Web → @discordbot:matrix.example.com → login
Dann Guild-Channels bridgen: guilds bridge <guild ID>

10.3 Telegram Bridge

mkdir -p /opt/bridges/telegram
cd /opt/bridges/telegram

wget https://github.com/mautrix/telegram/releases/latest/download/mautrix-telegram-amd64
chmod +x mautrix-telegram-amd64

# Beispiel-Config herunterladen
wget https://github.com/mautrix/telegram/releases/latest/download/example-config.yaml -O config.yaml

Telegram API-Keys erforderlich: https://my.telegram.org/apps

Config anpassen (ein Befehl)

sed -i \
  -e 's|address: http://example.localhost:8008|address: http://localhost:8008|' \
  -e 's|domain: example.com|domain: matrix.example.com|' \
  -e 's|hostname: 127.0.0.1|hostname: 0.0.0.0|' \
  -e 's|uri: postgres://user:password@host/database?sslmode=disable|uri: postgres://mautrix:BridgeDB_PASSWORT@localhost/mautrix_telegram|' \
  -e 's|"example.com": user|"matrix.example.com": user|' \
  -e 's|"@admin:example.com": admin|"@admin:matrix.example.com": admin|' \
  -e 's|api_id: 12345|api_id: DEINE_API_ID|' \
  -e 's|api_hash: tjyd5yge35lbodk1xwzw2jstp90k55qz|api_hash: DEIN_API_HASH|' \
  config.yaml

./mautrix-telegram-amd64 -g -c config.yaml -r registration.yaml

cp registration.yaml /etc/matrix-synapse/telegram-registration.yaml
chown matrix-synapse:matrix-synapse /etc/matrix-synapse/telegram-registration.yaml
systemctl restart matrix-synapse

Systemd Service

cat > /etc/systemd/system/mautrix-telegram.service << 'EOF'
[Unit]
Description=mautrix-telegram bridge
After=matrix-synapse.service

[Service]
Type=simple
WorkingDirectory=/opt/bridges/telegram
ExecStart=/opt/bridges/telegram/mautrix-telegram-amd64 -c config.yaml
Restart=always
User=root

[Install]
WantedBy=multi-user.target
EOF

systemctl enable mautrix-telegram
systemctl start mautrix-telegram

11. Troubleshooting

Synapse startet nicht

journalctl -xeu matrix-synapse.service --no-pager | tail -30

Häufige Ursachen:

report_stats nicht gesetzt → echo "report_stats: false" >> homeserver.yaml
macaroon_secret_key fehlt → generieren und eintragen
Appservice-Registration hat falsche Permissions → chown matrix-synapse:matrix-synapse

Element Web hängt bei "Synchronisiere"

# Well-known prüfen
curl -s http://192.168.X.X/.well-known/matrix/client
curl -s https://matrix.example.com/.well-known/matrix/client

# Synapse well-known deaktivieren falls Konflikt
# In homeserver.yaml: serve_server_wellknown: false

Bridge antwortet nicht

journalctl -fu mautrix-whatsapp --no-pager
# Prüfen ob Bridge auf richtigen Port zeigt
grep "address:" /opt/bridges/whatsapp/config.yaml

Port-Konflikte

ss -tlnp | grep -E "8008|8009|8081|29318|29334"

Federation-Test

https://federationtester.matrix.org/#matrix.example.com

Gesundheitsprüfung (alle Services)

systemctl is-active matrix-synapse nginx postgresql \
  mautrix-whatsapp mautrix-discord mautrix-telegram \

Anhang: Ports Übersicht

Port	Service	Erreichbar von
8008	Synapse (intern)	localhost
80	nginx / Element Web	LAN
8081	Synapse Admin UI	LAN
29318	WhatsApp Bridge	localhost
29334	Discord Bridge	localhost
29317	Telegram Bridge	localhost

Anhang: Service-Dateien Übersicht

Service	Config	Registration
Synapse	`/etc/matrix-synapse/homeserver.yaml`	—
WhatsApp	`/opt/bridges/whatsapp/config.yaml`	`/etc/matrix-synapse/whatsapp-registration.yaml`
Discord	`/opt/bridges/discord/config.yaml`	`/etc/matrix-synapse/discord-registration.yaml`
Telegram	`/opt/bridges/telegram/config.yaml`	`/etc/matrix-synapse/telegram-registration.yaml`

wendy2702

Wofür sind diese Bridges gut?

bloop

@wendy2702
Damit kannst du deine bestehenden WhatsApp, Discord, Telegramm Accounts mit Matrix verbinden. Somit reicht eine App statt für jeden Message Dienst eine eigene. Mach nun alles über Element.

Community Forum

NEWS

Anleitung gesucht für Matrix/Element selbstgehostet.

SOP – Matrix Synapse Homeserver Setup

1. Voraussetzungen

Hardware / Infrastruktur

Software

Timezone setzen

2. Synapse Installation

3. PostgreSQL Datenbank

4. Synapse Konfiguration

Minimale Pflicht-Konfiguration

Secrets generieren

Synapse starten

Synapse testen

5. Nginx Reverse Proxy (lokal)

nginx installieren

Element Web auf Port 80

Synapse Admin UI auf Port 8081

Ports prüfen

Well-Known Dateien

Well-Known verifizieren

6. Reverse Proxy (extern)

Architektur

7. Element Web Installation

config.json anpassen

Aufruf

8. Synapse Admin UI

Login

9. Admin-User anlegen

Login testen

10. Bridges

PostgreSQL Datenbanken für Bridges anlegen

Bridge-Registrierungen in homeserver.yaml eintragen

10.1 WhatsApp Bridge

config.yaml (Pflichtfelder)

Systemd Service

WhatsApp Login

10.2 Discord Bridge

config.yaml (Pflichtfelder)

Systemd Service

Discord Login

10.3 Telegram Bridge

Config anpassen (ein Befehl)

Systemd Service

11. Troubleshooting

Synapse startet nicht

Element Web hängt bei "Synchronisiere"

Bridge antwortet nicht

Port-Konflikte

Federation-Test

Gesundheitsprüfung (alle Services)

Anhang: Ports Übersicht

Anhang: Service-Dateien Übersicht

Support us

551

32.8k

82.9k

1.3m