Synapse homeserver

• In the Azure Portal, search the Marketplace for Synapse Homeserver on Ubuntu 24.04 LTS and select the SecureAnyCloud offer.
• Choose Standard_B2ms or larger.
• Set the administrator username to azureuser and upload your SSH public key.
• On the Networking tab, allow inbound SSH (22) and HTTPS (443) to begin with. Add the call and federation ports from Step 6 before you invite users.
• Select Review + create, then Create.

az vm image terms accept --urn sac1647283583153:matrix-synapse-element-coturn-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-matrix-rg \
  --name my-synapse-vm \
  --image sac1647283583153:matrix-synapse-element-coturn-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

ssh azureuser@<vm-ip>

The stack is four services. matrix-stack-firstboot is a one-shot unit that runs once, on the very first boot. It mints everything this VM needs before the homeserver is allowed to start.

systemctl is-active postgresql matrix-synapse coturn nginx

Expected output:

active active active active

If you connect within the first minute or so of a cold boot, the web address may answer HTTP 503. That is deliberate. nginx refuses to serve anything until first boot has finished writing this VM's own secrets, so there is no window in which a half-configured homeserver is reachable. Watch first boot complete with:

sudo systemctl status matrix-stack-firstboot.service --no-pager

Confirm the Matrix client API is answering through nginx:

curl -ks -o /dev/null -w '%{http_code}\n' https://127.0.0.1/_matrix/client/versions

Expected output:

200

Every VM generates its own administrator on first boot. The credentials are written to a file that only root can read:

sudo cat /root/matrix-stack-credentials.txt

This file contains:

• matrix.server.name: this homeserver's permanent server name
• matrix.web.url: the address to open in a browser
• matrix.admin.user / matrix.admin.pass / matrix.admin.mxid: the per-instance administrator
• matrix.federation.port: the port other homeservers use to reach yours
• matrix.turn.realm: the realm the TURN relay authenticates against

The homeserver's signing key, at /etc/matrix-synapse/homeserver.signing.key, is this server's cryptographic identity. It is generated on this VM and exists nowhere else. Back it up with your database, and never copy it to another server.

Do not just check that the ports you expect are open. List every socket bound to something other than loopback, so anything unexpected has nowhere to hide:

sudo ss -lntuH | awk '{print $1, $5}' | grep -vE '127\.0\.0|\[::1\]' | sort -u

That is the complete public surface, and it is what your network security group needs to allow:

• 22 (TCP): SSH administration
• 80 (TCP): redirects to HTTPS, and serves ACME http-01 if you install a trusted certificate
• 443 (TCP): the web client, the Matrix client API and .well-known discovery
• 8448 (TCP): Matrix federation. Leave this closed if you want a private, non-federating server
• 3478 (TCP and UDP): TURN and STUN, for call setup and relay
• 5349 (TCP and UDP): the same over TLS and DTLS, for networks that only permit HTTPS-like traffic
• 49152-49231 (UDP): the bounded media relay range that coturn allocates calls from, one port per live call leg

Everything else stays on loopback. PostgreSQL and the Synapse process itself are never reachable from off the VM:

sudo ss -lntH | grep -E ':(5432|8008)' | awk '{print $1, $4}'

Expected output:

LISTEN 127.0.0.1:5432 LISTEN 127.0.0.1:8008

Open registration is closed, so a stranger who finds your server cannot create an account on it:

curl -ks -o /dev/null -w '%{http_code}\n' -X POST https://127.0.0.1/_matrix/client/v3/register \
  -H 'Content-Type: application/json' -d '{"username":"walkup","password":"not-allowed"}'

Expected output:

403

Confirm that the per-instance administrator password authenticates, and that a wrong one does not:

ADMIN_USER=$(sudo grep '^matrix.admin.user=' /root/matrix-stack-credentials.txt | cut -d= -f2-)
ADMIN_PASS=$(sudo grep '^matrix.admin.pass=' /root/matrix-stack-credentials.txt | cut -d= -f2-)
GOOD=$(curl -ks -o /dev/null -w '%{http_code}' -X POST https://127.0.0.1/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d "{\"type\":\"m.login.password\",\"identifier\":{\"type\":\"m.id.user\",\"user\":\"${ADMIN_USER}\"},\"password\":\"${ADMIN_PASS}\"}")
BAD=$(curl -ks -o /dev/null -w '%{http_code}' -X POST https://127.0.0.1/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d "{\"type\":\"m.login.password\",\"identifier\":{\"type\":\"m.id.user\",\"user\":\"${ADMIN_USER}\"},\"password\":\"wrong-password-xyz\"}") case "${BAD}" in 403|429) VERDICT="rejected (${BAD})" ;; *) VERDICT="UNEXPECTED (${BAD})" ;; esac echo "correct password -> ${GOOD}; wrong password -> ${VERDICT}"

Expected output:

correct password -> 200; wrong password -> rejected (403)

Synapse rate-limits sign-in attempts, so a run of failed logins starts returning 429 instead of 403. Both mean that Synapse refused the credential. 429 means that Synapse stopped answering in detail because it was being hammered. That protection is on by default, and it is why the check above accepts either code.

Open https://<vm-ip>/ in a browser. The image ships a self-signed certificate generated for this VM, so your browser warns on the first visit. Accept the warning, or install a trusted certificate as described below.

Sign in with the administrator username and password from Step 5. You land on an empty account on your own homeserver.

Signing in on an additional device. Matrix verifies devices against each other so that end-to-end encrypted history can be shared safely. The first device to sign in to an account sets up that account's encryption identity by itself. Every later device must confirm itself against one you already trust.

If you no longer have a trusted device, the client offers a "Can't confirm?" path that resets the identity and starts again. That is normal Matrix behaviour, not a fault with the image.

Use the + button beside the room list to create a room, then invite people to it and type into the composer at the bottom. Private rooms are end-to-end encrypted by default, so the server stores only ciphertext for them.

Your account settings show the full Matrix ID your homeserver issued you, in the form @user:server-name.

coturn relays calls between people on restrictive networks. Synapse hands each signed-in client a short-lived TURN credential, derived from a secret it shares with the relay, so there is no static call login to leak:

ADMIN_USER=$(sudo grep '^matrix.admin.user=' /root/matrix-stack-credentials.txt | cut -d= -f2-)
ADMIN_PASS=$(sudo grep '^matrix.admin.pass=' /root/matrix-stack-credentials.txt | cut -d= -f2-)
# Synapse rate limits sign ins, so back off and retry rather than failing outright if
# you have just run the checks above. for attempt in $(seq 1 12); do
TOKEN=$(curl -ks -X POST https://127.0.0.1/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d "{\"type\":\"m.login.password\",\"identifier\":{\"type\":\"m.id.user\",\"user\":\"${ADMIN_USER}\"},\"password\":\"${ADMIN_PASS}\"}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin).get("access_token",""))') [ -n "${TOKEN}" ] && break sleep 10 done [ -n "${TOKEN}" ] || { echo "could not sign in to read TURN settings — Synapse is still rate limiting; wait a few minutes"; exit 1; } curl -ks -H "Authorization: Bearer ${TOKEN}" https://127.0.0.1/_matrix/client/v3/voip/turnServer \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print("ttl:", d["ttl"]); [print("uri:", u) for u in d["uris"]]'

The expected output follows. The URIs carry your own server name:

ttl: 86400 uri: turn:<SERVER_NAME>:3478?transport=udp uri: turn:<SERVER_NAME>:3478?transport=tcp uri: turns:<SERVER_NAME>:5349?transport=tcp

The relay is deliberately restricted. It refuses to forward traffic to loopback, to private ranges, or to the Azure instance metadata address at 169.254.169.254. Without that restriction, an authenticated user could point the relay at your own network and read instance metadata through it.

Registration is closed, so you create accounts explicitly. The following command uses the registration_shared_secret that first boot generated for this VM:

sudo /opt/venvs/matrix-synapse/bin/register_new_matrix_user \
  -c /etc/matrix-synapse/conf.d/90-sac-instance.yaml \
  -u alice -p 'choose-a-strong-password' --no-admin http://127.0.0.1:8008 \
  || echo "That username is already registered on this homeserver — choose another."

Add --admin instead of --no-admin to create another server administrator.

To let people sign up for themselves instead, set enable_registration: true in /etc/matrix-synapse/conf.d/10-sac.yaml. Pair it with a verification method or a registration token so that you are not running an open relay for spam. Then restart with sudo systemctl restart matrix-synapse.

Synapse also supports SAML, CAS and OpenID Connect single sign-on. Configure your provider in the same directory.