Kom igång med Matrix, skapa en Synapse server

I den här artikeln kommer vi att gå igenom hur man sätter upp en minimal installation av en Matrix homeserver med Synapse-implementationen. Denna server kommer att kunna federera med andra servrar, för att fullt ut delta i det offentliga Matrix-nätverket.

TLDR: Ifall du vill köra på snabbspåret, kika längst ner i artikeln, där finns det en sammanfattning som endast innehåller konfigurationsfilerna.

Introduktion

All mjukvara i denna artikel är open source, du kan följa denna artikel på i princip vilken linux-maskin som helst, men för mina exempel här kommer jag att använda Debian 12 som jag kör på [Redpill Linpros Nordic Cloud (RLNC)}(https://www.redpill-linpro.com/cloud/cloud/platforms/rlnc.html). Systemkraven för Synapse kräver minst 1GB med ram för stora rum som exempelvis #matrix:matrix.org, jag har allokerat 2st VCPUs, 4GB ram och 50GB lagring i RLNC.

Metod

Vår Synapse homeserver kommer att lagra data på filsystemet och i en Postgres-databas, nätverkstraffik hanteras av reverse proxyn Caddy.

Kom igång med Postgres

Först måste vi installera Postgres.

Exekvera detta i Bash.

# Installera Postgres
$ sudo apt install postgresql postgresql-client
# Verifiera din installation och att tjänsten kör och autostartar
# Leta efter "Loaded: loaded (/lib/systemd/system/postgresql.service; enabled; preset: enabled)"
$ sudo systemctl status postgresql
# Verifiera att du kan logga in med psql som användare postgres
# Skriv \q för att avsluta psql
$ sudo -u postgres psql

Kom igång med Synapse

Välj ett servernamn

Välj ett namn för din Matrix homeserver, mitt kommer att vara e012.se, detta kan inte ändras i efterhand. Servernamnet beskriver för andra servrar vart dina användare hittas i federationen av flera servrar, ett exempel på detta är användare @oscar:e012.se som finns på e012.se. Synapse dokumentation rekommenderar inte att använda ett subdomän som servernamn, utan att istället använda sig av delegering. Min server ligger på matrix.e012.se så jag måste sätta upp delegering till e012.se, jag kommer att gå igenom hur det här funkar senare i artikeln.

Installera Synapse

# Installera beroenden
$ sudo apt install -y lsb-release wget apt-transport-https
# Lägg till Matrix i ditt APT bibliotek
$ sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
# Verifiera att fingerprint är AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058
$ gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg
# Lägg till i APT biblioteket
$ echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list
# Updattera APT
$ sudo apt update
# Installera synapse
# APT kommer att föreslå sqlite3, detta behövs inte eftersom att vi använder postgres
# Python 3 med flera paket kommer att installeras tillsammans med matrix-synapse-py3
$ sudo apt install matrix-synapse-py3

När du installerar matrix-synapse-py3 kommer du att få upp denna prompt, skriv in ditt servernamn.

Du kommer därefter att få upp en till propmpt, om du installerar detta i en produktionsmiljö dela gärna statistiken med utvecklarna. Jag kör nu i en testmiljö, och jag vill inte göra det för krångligt så jag kommer att avstå detta. Men kom ihåg att om du sprider statistik och kunskap så hjälper vi Matrix att hjälpa oss med säker och decentraliserad kommunikation… men nu är det slutpladdrat, vi fortsätter med installationen.

Om du känner för det så är det här ett bra tillfälle att backa upp din homeserver konfiguration.

# Backa upp din homeserver konfiguration
$ cp /etc/matrix-synapse/homeserver.yaml ~/homeserver.yaml.bak

Skapa en databas

Skapa postgres-användaren synapse med lösenord ee94cb132a2432c6e95d505334736186.
Skapa databas synapse med locale C och encoding UTF8.
Konfigurera Synapse för att använda Postgres.

Exekvera detta i bash.

# Logga in som användare postgres
$ sudo -u postgres -i
# Skapa postgres-användaren synapse
# Använd lösenord ee94cb132a2432c6e95d505334736186 (om du vill)
$ createuser --pwprompt synapse
# Skapa databas synapse för användare synapse
# Tänk på att locale och encoding är viktigt
$ createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse synapse
# Verifiera att din databas existerar och att den har rätt locale och encoding
$ psql -l
# Logga ut från användare postgres
$ exit

Dina databaser bör se ut enligt följande.

                                             List of databases
   Name    |  Owner   | Encoding | Collate |  Ctype  | ICU Locale | Locale Provider |   Access privileges   
-----------+----------+----------+---------+---------+------------+-----------------+-----------------------
 postgres  | postgres | UTF8     | C.UTF-8 | C.UTF-8 |            | libc            | 
 synapse   | synapse  | UTF8     | C       | C       |            | libc            | 
 template0 | postgres | UTF8     | C.UTF-8 | C.UTF-8 |            | libc            | =c/postgres          +
           |          |          |         |         |            |                 | postgres=CTc/postgres
 template1 | postgres | UTF8     | C.UTF-8 | C.UTF-8 |            | libc            | =c/postgres          +
           |          |          |         |         |            |                 | postgres=CTc/postgres
(4 rows)

Nu ska du modifiera databasinställningarna i /etc/matrix-synapse/homeserver.yaml så att de använder Postgres.

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

Delegering

Notera att du kan hoppa över detta steg ifall ditt hostname är detsamma som ditt servernamn.

Delegering är ett krav när vi tillhandahåller trafik från en server som inte har samma hostname som ditt servernamn, i mitt fall är mitt hostname matrix.e012.se och mitt servernamn är e012.se. Notera att dessa två servrar är två helt separata maskiner i mitt fall, det spelar ingen roll, vi löser det med delegering. Som standardinställning kommer andra servrar att slå upp användare @oscar:e012.se på server e012.se:8448, och vi kan inte klandra dem för det eller hur, men vi behöver peka dem vidare till matrix.e012.se där vår Synapse-installation finns. Detta åstakommer vi med något som kallas .well-known delegation, i praktiken så kommer andra servrar pekas mot matrix.e012.se:443.

För att använda .well-known delegation behöver vi tillhandahålla två JSON-filer, dena ena på /.well-known/matrix/server och den andra på /.well-known/matrix/client. Filen server pekar om trafik som hanterar federering.

{
    "m.server": "matrix.e012.se:443"
}

Filen client pekar om användarens autentisering.

{
    "m.homeserver":
    {
        "base_url": "https://matrix.e012.se"
    }
}

Lägg till följande konfiguration i din homeserver konfiguration serve_server_wellknown: true och public_baseurl: "https://matrix.e012.se", du hittar konfigurationen på /etc/matrix-synapse/homeserver.yaml. Här är mina sista 4 rader i konfigurationsfilen.

trusted_key_servers:
  - server_name: "matrix.org"
serve_server_wellknown: true
public_baseurl: "https://matrix.e012.se"

Tillhandahålla .well-known

Jag använder caddy som reverse proxy för e012.se, så jag kommer att lägga till delegationen i min Caddyfile och sedan starta om caddy.

e012.se {
    # Add this
        handle /.well-known/matrix/server {
        respond `{ "m.server": "matrix.e012.se:443"}` 200
        header Content-Type application/json
        header Access-Control-Allow-Origin *
    }

    # Add this
    handle /.well-known/matrix/client {
        respond `{ "m.homeserver": { "base_url": "https://matrix.e012.se" }}` 200
        header Content-Type application/json
        header Access-Control-Allow-Origin *
    }

    # This is an unrelated service
    reverse_proxy localhost:49167
    encode gzip
}

# Verifiera att din .well-known funkar
$ curl https://e012.se/.well-known/matrix/server -v

Funkar det? Kan du se access-control-allow-origin: * och content-type: application/json i dina headers? Snyggt!

Secrets

Du behöver nu sätta macaroon_secret_key i /etc/matrix-synapse/homeserver.yaml, sätt den till en slumpmässig sträng (pwgen 32 1). Denna sträng kommer att användas som en hemlig nyckel för vissa krypteringsalgoritmer.

Du kan också sätta form_secret, gör detta med macaroon_secret_key.

Slutet av din homeserver konfiguration bör nu se ut enligt följande.

macaroon_secret_key: 2d6cb04e7ed21a3275c104c66143169155eca864
form_secret: fae8c35cd966d3067a0fc4dbcbd7fa8f26616c42

Användarautentisering och användarregistrering

Användare kan autentiseras på många sätt i Matrix, med OpenID Connect, JWT eller flera andra metoder. I den här artikeln kommer vi att använda förenklad användarautentisering utan captcha eller andra säkerhetsmekanismer, användarnamn och lösenord helt enkelt. Alla internetanvändare kan skapa ett konto och börja kommunicera på din server, du kommer förmodligen vilja begränsa detta på något sätt, men det kommer inte att behandlas i denna artikel.

Lägg till följande i din homeserver konfiguration.

enable_registration: true
enable_registration_without_verification: true
registration_shared_secret: b10aa181d025852ce5616b950c1b7342f12beaf2

Tänk på att registration_shared_secret är en hemlighet. Med denna nyckel kan man skapa administratörskonton, till och med om man stänger av användarregistrering med enable_registration: false. Du bör generera en slumpmässig lång sträng för denna nyckel (pwgen 32 1) och du bör aldrig dela den med någon obehörig, du bör framförallt inte skriva en bloggartikel och dela den med hela världen… oj då heh!

Lägg till en användare manuellt

Du kan manuellt lägga till använda genom att nyttja admin-APIet, det kommer vi att göra för att skapa vår första administratörsanvändare. Det finns ett trevligt litet skript som förenklar hela den här processen.

# Bara python 3 minimal är installerad med Synapse
# Jag installerar mina python beroenden med APT
$ sudo apt install python3 python3-requests python3-yaml
# Ladda ner skriptet
$ curl -o register_new_matrix_user.py "https://raw.githubusercontent.com/element-hq/synapse/refs/heads/develop/synapse/_scripts/register_new_matrix_user.py"
# Gör skriptet exekverbart
$ sudo chmod +x register_new_matrix_user.py
# Kör skriptet
# Välj yes för att skapa en administratör
$ python3 register_new_matrix_user.py -c "/etc/matrix-synapse/homeserver.yaml"

Reverse proxy med Caddy

Installera Caddy
Öppna Synapse mot internet med en reverse proxy

Installera Caddy med APT.

$ sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
$ sudo apt update
$ sudo apt install caddy
# Tillåt caddy att start med systemet
$ sudo systemctl enable caddy

Titta på din homeserver konfiguration på /etc/matrix-synapse/homeserver.yaml, blocket listener bör se ut enligt följande.

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

Redigera din Caddyfile som du hittar på /etc/caddy/Caddyfile, vi måste fixa en reverse proxy för Synapse. Din Caddyfile bör se ut enligt följande.

matrix.e012.se {
    reverse_proxy /_matrix/* localhost:8008
    reverse_proxy /_synapse/client/* localhost:8008
}

Valfria endpoints

Om du vill och behöver kan du exponera följande endpoints:

/health vilket alltid kommer attt returnera 200 OK, denna endpoint loggas inte.
/_synapse/admin, är admin-APIet som man anropar med en token.

En helt exponerad homeserver ser ut så här.

matrix.e012.se {
    reverse_proxy /health localhost:8008
    reverse_proxy /_matrix/* localhost:8008
    reverse_proxy /_synapse/client/* localhost:8008
    reverse_proxy /_synapse/admin/* localhost:8008
}

De sista stegen

Starta Caddy och Synapse.

# Starta om (eller starta) Caddy
$ sudo systemctl restart caddy
# Verifiera att Caddy körs
$ sudo systemctl status caddy
# Start om (eller starta) Synapse
$ sudo systemctl restart matrix-synapse.service
# Verifiera att Synapse körs
$ sudo systemctl status matrix-synapse.service

Du kommer förmodligen att se nedanstående varning från Synapse, du kan gömma denna varning genom att sätta suppress_key_server_warning: true i /etc/matrix-synapse/homeserver.yaml.

Mar 20 13:10:27 matrix.e012.se matrix-synapse[5772]: This server is configured to use 'matrix.org' as its trusted key server via the
Mar 20 13:10:27 matrix.e012.se matrix-synapse[5772]: 'trusted_key_servers' config option. 'matrix.org' is a good choice for a key
Mar 20 13:10:27 matrix.e012.se matrix-synapse[5772]: server since it is long-lived, stable and trusted. However, some admins may
Mar 20 13:10:27 matrix.e012.se matrix-synapse[5772]: wish to use another server for this purpose.
Mar 20 13:10:27 matrix.e012.se matrix-synapse[5772]: To suppress this warning and continue using 'matrix.org', admins should set
Mar 20 13:10:27 matrix.e012.se matrix-synapse[5772]: 'suppress_key_server_warning' to 'true' in homeserver.yaml.

Testning

Testa federering

Gå till The Matrix Federation Tester och skriv in ditt servernamn, i mitt fall är det e012.se.

Om du vill jämföra våra federeringsrapporter så ser min ut så här.

{
  "WellKnownResult": {
    "m.server": "matrix.e012.se:443",
    "CacheExpiresAt": 0
  },
  "DNSResult": {
    "SRVSkipped": true,
    "SRVCName": "",
    "SRVRecords": null,
    "SRVError": null,
    "Hosts": {
      "matrix.e012.se": {
        "CName": "matrix.e012.se.",
        "Addrs": [
          "87.238.55.105"
        ],
        "Error": null
      }
    },
    "Addrs": [
      "87.238.55.105:443"
    ]
  },
  "ConnectionReports": {
    "87.238.55.105:443": {
      "Certificates": [
        {
          "SubjectCommonName": "matrix.e012.se",
          "IssuerCommonName": "E6",
          "SHA256Fingerprint": "O30FA5vrwAV4SkanmElnsy56gnvNotqjFNAQ2yitxGI",
          "DNSNames": [
            "matrix.e012.se"
          ]
        },
        {
          "SubjectCommonName": "E6",
          "IssuerCommonName": "ISRG Root X1",
          "SHA256Fingerprint": "duniiKr8Djf0OQy/lGqtmX1cHJAbPOUT09j626viq4U",
          "DNSNames": null
        }
      ],
      "Cipher": {
        "Version": "TLS 1.3",
        "CipherSuite": "TLS_AES_128_GCM_SHA256"
      },
      "Checks": {
        "AllChecksOK": true,
        "MatchingServerName": true,
        "FutureValidUntilTS": true,
        "HasEd25519Key": true,
        "AllEd25519ChecksOK": true,
        "Ed25519Checks": {
          "ed25519:a_iIQQ": {
            "ValidEd25519": true,
            "MatchingSignature": true
          }
        },
        "ValidCertificates": true
      },
      "Errors": [],
      "Ed25519VerifyKeys": {
        "ed25519:a_iIQQ": "rgzS2r2YL1/2mMvnZOF/rVA8dX7ueV+l6Ayr8mi8msg"
      },
      "Info": {},
      "Keys": {
        "old_verify_keys": {},
        "server_name": "e012.se",
        "signatures": {
          "e012.se": {
            "ed25519:a_iIQQ": "QyVvx2iHlVax6peGKJmlCB5rJWUS0Vcq8UHtGMsVLnufsrokDO4tsruLCQSfg1jYq4XfzpgDo5cWxsoc8mPkDg"
          }
        },
        "valid_until_ts": 1742564141137,
        "verify_keys": {
          "ed25519:a_iIQQ": {
            "key": "rgzS2r2YL1/2mMvnZOF/rVA8dX7ueV+l6Ayr8mi8msg"
          }
        }
      }
    }
  },
  "ConnectionErrors": {},
  "Version": {
    "name": "Synapse",
    "version": "1.126.0"
  },
  "FederationOK": true
}

Testa som en användare

Jag använder klienten Cinny men det finns en uppsjö av klienten att välja bland, det är vad som är så vackert med Matrix, du behöver inte passa mjukvaran, mjukvaran låter dig använda internet på det sätt som passar dig, det är en öppen standard, underbart eller hur!… ursäkta, nog snackat! Vi kör vidare.

Skriv in ditt servernamn e012.se.
Logga in som @oscar:e012.se
Skapa en till användare @test:e012.se, med skriptet jag tidigare nämnde.
Logga in som din andra användare @test:e012.se (du behöver två separata webbläsare öppna samtidigt, tips inkognito).
Påbörja en konversation mellan de båda användarna.

Problemlösning relaterat till federering

Jag upplevde en viss problematik kring federering när jag sökte efter mitt personliga konto på servern matrix.org i klienten Fractal, men efter en natts sömn med Synapse igång på min server så funkade det, helt plötsligt. I Fractal kunde jag inte lägga till användaren, men i Cinny kunde jag. Värt att notera är att Cinny anses vara en stabil klient medan Fractal fortfarande är i ett betastadie. Min gissning för varför dessa problem uppstod är att matrix.org har vissa restriktioner för nyskapade servarar, att de har en tidsfrist som måste överskridas innan servern anses vara trovärdig.

För att felsöka din federering använd The Matrix Federation Tester. Testa först med att skicka meddelanden till andra användare på din server innan du skickar meddelanden till användare på andra servrar, för att utesluta att andra fel som inte har med federering att göra.

Resultat

Toppen! Nu har vi en homeserver och vi deltar i det federerade och decentraliserade nätverket av nästa generations kommunikation. Matrix är flera saker, det kan göra mycket, du kan kontrollera IoT, göra konferenssamtal med video, koordinera blåljusmyndigheter och väldigt mycket mer. Eftersom att Matrix är en öppen standard kan du skicka i princip vilken data som helst igenom systemet, du kan skapa allt du kan drömma om.

Om den här artikeln var behjälplig för dig, skicka gärna ett meddelande till @oscarandersson:matrix.org, jag skulle verkligen vilja höra vad du tycker om både den här artikeln men också om Matrix i allmännhet.

Om du är i behov av en enterprise-lösning eller om du har fundering om ifall Matrix är den rätta lösningen för dig och ditt organisation, kontakta gärna oss på Redpill Linpro. Vi har kontor i Karlstad, Göteborg, Oslo, Stockholm, Köpenhamn, Karlskrona, Aarhus och Trondheim.

TLDR

Jag fattar, det är en lång artikel, här kommer en snabb genomgång, ifall du fastnar någonstans kan du alltid skrolla upp. Lycka till.

homeserver.yaml

pid_file: "/var/run/matrix-synapse.pid"
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::1', '127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false
database:
  name: psycopg2
  args:
    user: synapse
    password: ee94cb132a2432c6e95d505334736186
    dbname: synapse
    host: localhost
    cp_min: 5
    cp_max: 10
log_config: "/etc/matrix-synapse/log.yaml"
media_store_path: /var/lib/matrix-synapse/media
signing_key_path: "/etc/matrix-synapse/homeserver.signing.key"
trusted_key_servers:
  - server_name: "matrix.org"
serve_server_wellknown: true
public_baseurl: https://matrix.e012.se/
suppress_key_server_warning: true
macaroon_secret_key: 2d6cb04e7ed21a3275c104c66143169155eca864
form_secret: fae8c35cd966d3067a0fc4dbcbd7fa8f26616c42
enable_registration: true
enable_registration_without_verification: true
registration_shared_secret: b10aa181d025852ce5616b950c1b7342f12beaf2

Caddyfile for Synapse

matrix.e012.se {
    reverse_proxy /_matrix/* localhost:8008
    reverse_proxy /_synapse/client/* localhost:8008
}

Caddyfule for delegation

e012.se {
    handle /.well-known/matrix/server {
        respond `{ "m.server": "matrix.e012.se:443"}` 200
        header Content-Type application/json
        header Access-Control-Allow-Origin *
    }

    handle /.well-known/matrix/client {
        respond `{ "m.homeserver": { "base_url": "https://matrix.e012.se" }}` 200
        header Content-Type application/json
        header Access-Control-Allow-Origin *
    }

    # This is an unrelated service
    reverse_proxy localhost:49167
    encode gzip
}