Server config — Documentation

Overview

This page covers the core configuration options that affect whether the connectivity tester can reach your server. It is not a complete homeserver configuration guide — refer to your homeserver's official documentation for full details.

Server name

The server name is the domain that appears in Matrix IDs (@user:example.com). It must be set before going into production — it cannot be changed afterwards without effectively creating a new server.

Synapse (homeserver.yaml):

server_name: 'example.com'

Continuwuity (config.toml):

[global]
server_name = "example.com"

Listening configuration

For the connectivity tester to reach your server, it must be reachable on the public internet. The recommended setup is to run your homeserver listening only on localhost and use a reverse proxy (Nginx or Caddy) to handle TLS and forward requests.

Synapse — listen on localhost only (reverse proxy handles TLS):

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

The x_forwarded: true setting tells Synapse to trust the X-Forwarded-For header from your reverse proxy, so it sees the real client IP address.

See TLS Certificates for reverse proxy examples that handle TLS on port 443.

Registration

By default, open registration should be disabled or protected against abuse. The connectivity tester does not require registration to be open.

Synapse — disable registration:

enable_registration: false

Synapse — enable registration with CAPTCHA:

enable_registration: true
enable_registration_captcha: true
recaptcha_public_key: 'YOUR_RECAPTCHA_PUBLIC_KEY'
recaptcha_private_key: 'YOUR_RECAPTCHA_PRIVATE_KEY'

Synapse — enable registration with invite tokens:

enable_registration: true
registration_requires_token: true

Tokens are created via the Synapse admin API.

Federation

Federation is enabled by default in Synapse. If you have accidentally disabled it, check for a federation_domain_whitelist setting that restricts which servers you can federate with.

Synapse — unrestricted federation (default):

# No federation_domain_whitelist means federation with all servers

Common configuration mistakes

Server responds on localhost but not from outside

Your homeserver is probably bound to 127.0.0.1 only (which is correct), but your reverse proxy is not configured to forward requests to it. Check your Nginx or Caddy configuration.

`x_forwarded` not set

Without x_forwarded: true in Synapse, rate limiting and IP-based decisions use the proxy's address rather than the real client IP. This is not a connectivity problem but can cause unexpected behaviour.

Wrong server name

The server_name in your homeserver configuration must match the domain in your well-known files and TLS certificate chain. If these don't match, federation will fail.