Come installare e usare Synapse su Linux

Synapse è il server Matrix più usato quando serve un backend federato controllabile, leggibile e abbastanza flessibile da stare sia su una VM piccola sia dietro una piattaforma più strutturata. Su Linux il punto non è solo “installarlo”, ma scegliere il metodo giusto, mettere in sicurezza il servizio, collegarlo a un database serio e verificare che la federazione funzioni davvero. Se salti questi passaggi, il risultato tipico è un’istanza che parte, ma non regge traffico, non federata bene o difficile da mantenere.

Architettura minima che conviene avere in mente

Synapse parla con i client Matrix tramite HTTPS, usa un database PostgreSQL per evitare colli di bottiglia e dipende da un nome DNS coerente con l’identità Matrix del server. In pratica devi tenere allineati tre elementi: il dominio pubblico, il certificato TLS e il file /.well-known/matrix/server o la porta standard 8448, a seconda di come vuoi esporre la federazione. Se uno di questi tre è incoerente, i client possono funzionare ma la federazione no, oppure viceversa.

La scelta più lineare è installare Synapse come servizio dedicato su Linux, con PostgreSQL locale o remoto, reverse proxy davanti e backup regolari. Per ambienti piccoli va bene anche un’installazione più semplice, ma il salto a produzione richiede sempre almeno: log consultabili, database separato dal processo applicativo, TLS valido e una policy minima di aggiornamento.

Prerequisiti: sistema, DNS e porta

Prima di installare, verifica che il server abbia un hostname stabile e un record DNS pubblico coerente con il nome Matrix che vuoi usare. Se il dominio sarà matrix.example.com, quel nome deve risolvere correttamente e puntare alla macchina o al reverse proxy. Per la federazione Matrix, inoltre, i peer devono poter raggiungere il server via HTTPS standard, quindi il certificato deve essere valido e la porta 8448 non deve essere bloccata se la usi direttamente.

Controlli rapidi utili:

dig +short matrix.example.com
curl -I https://matrix.example.com
ss -ltnp | grep -E ':443|:8448'

Se il dominio non risponde o il certificato non è corretto, fermati qui: installare Synapse prima di sistemare il livello DNS/TLS porta solo a debug inutili dopo.

Installazione su Debian e Ubuntu con repository ufficiale

Su Debian e Ubuntu la strada più pulita è usare il repository ufficiale del progetto, perché ottieni pacchetti aggiornati e una procedura più prevedibile rispetto a soluzioni improvvisate con source installati a mano. Il pacchetto di Synapse crea in genere l’utente di servizio, i file base e l’integrazione con systemd.

Sequenza tipica:

sudo apt update
sudo apt install -y lsb-release wget apt-transport-https ca-certificates gnupg2
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" | sudo tee /etc/apt/sources.list.d/matrix-org.list
sudo apt update
sudo apt install -y matrix-synapse-py3

Durante l’installazione ti verrà chiesto il nome del server Matrix. Qui va inserito il dominio che useranno i client, non un hostname interno. Se il nome è sbagliato, correggerlo dopo è possibile, ma evita di farlo: il cambio di server name è delicato e può complicare identità, federazione e migrazioni future.

Database: PostgreSQL prima di tutto

Synapse può partire con SQLite in scenari molto piccoli, ma per qualunque uso serio PostgreSQL è la scelta corretta. Il vantaggio non è teorico: riduci i problemi di concorrenza, migliori la tenuta sotto carico e hai strumenti più solidi per backup e manutenzione.

Installa PostgreSQL e crea un database dedicato:

sudo apt install -y postgresql
sudo -u postgres psql

Dentro la shell SQL:

CREATE USER synapse_user WITH PASSWORD 'password-lunga-e-unica';
CREATE DATABASE synapse_db WITH OWNER synapse_user ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE template0;
\q

Qui c’è un punto importante: la password non va lasciata in chiaro nei documenti operativi. Meglio salvarla in un password manager o in un secret store e poi inserirla nel file di configurazione con permessi stretti. Se devi ruotarla, fallo prima sul DB e poi aggiorna il file di Synapse, con un riavvio controllato.

Configurazione base di Synapse

Il file principale è in genere /etc/matrix-synapse/homeserver.yaml. Dopo l’installazione conviene aprirlo e verificare almeno: nome server, database, listener HTTP, registrazione utenti e logging. La configurazione generata dal pacchetto è un buon punto di partenza, ma quasi sempre va rifinita.

Esempio minimo di blocco database:

database: name: psycopg2 args: user: synapse_user password: "***" database: synapse_db host: 127.0.0.1 cp_min: 5 cp_max: 10

Non copiare questo blocco alla cieca: il campo password va gestito con attenzione e i valori di pool dipendono dalla RAM e dal carico. Su macchine piccole, esagerare con i pool non aiuta. Se il server ha pochi utenti, una configurazione prudente è meglio di una “ottimizzata” sulla carta.

Per i listener, l’approccio più comune è far terminare TLS al reverse proxy e lasciare Synapse in ascolto locale su una porta interna. In questo modo riduci la superficie esposta e semplifichi la gestione del certificato.

Reverse proxy con Nginx

Se usi Nginx davanti a Synapse, il proxy deve inoltrare correttamente gli header e supportare le richieste lunghe usate da Matrix. Un errore classico è alzare il proxy ma dimenticare il supporto ai timeout o ai path giusti, con il risultato di client che si collegano male o notifiche che arrivano in ritardo.

Snippet essenziale:

server { listen 443 ssl http2; server_name matrix.example.com; ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem; location /_matrix { proxy_pass http://127.0.0.1:8008; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Host $host; proxy_read_timeout 600s; } location /_synapse/client { proxy_pass http://127.0.0.1:8008; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Host $host; }
}

La parte dei path può cambiare in base alla tua architettura, ma il punto è sempre lo stesso: il proxy deve parlare bene con Synapse e non troncare le connessioni. Dopo ogni modifica, testa la configurazione con nginx -t prima del reload.

File .well-known e federazione

Per evitare di esporre direttamente la logica di federazione su porte non standard, molti setup usano il file /.well-known/matrix/server. È un dettaglio piccolo, ma fa la differenza quando vuoi mantenere il server dietro un proxy o quando il dominio principale non coincide con il nome dell’istanza Matrix.

Il file serve a dire ai peer dove trovare il server Matrix. Esempio:

{"m.server": "matrix.example.com:443"}

Questo file deve essere servito in HTTPS, con content-type corretto e senza redirect strani. Se la federazione non parte, controlla prima questo punto insieme al DNS. È un errore molto più frequente di quanto sembri.

Avvio del servizio e verifica iniziale

Dopo la configurazione, abilita e avvia il servizio systemd:

sudo systemctl enable --now matrix-synapse
sudo systemctl status matrix-synapse --no-pager

La verifica non si ferma allo stato “active”. Controlla i log per errori di connessione al DB, problemi di permessi sui file di configurazione o errori TLS. I log utili stanno di solito in journalctl, ma se hai abilitato un log file dedicato, quello va consultato subito.

journalctl -u matrix-synapse -n 100 --no-pager

Se il servizio parte ma i client non si autenticano, il problema spesso è uno di questi tre: indirizzo del server sbagliato, reverse proxy incompleto o database non raggiungibile. In quella fase conviene fare test di livello HTTP prima di toccare altro.

Creazione del primo utente amministratore

Synapse include strumenti per creare un account amministrativo. In installazioni recenti si usa spesso il comando dedicato fornito dal pacchetto o dall’ambiente Python del servizio. Il nome esatto può variare in base al metodo di installazione, quindi qui la regola è semplice: usa il binario presente nel pacchetto e verifica con --help se la tua versione differisce.

Approccio tipico:

sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://127.0.0.1:8008

Se il comando non è presente, non improvvisare: controlla i pacchetti installati e il path del tool. Il punto operativo è creare il primo admin in modo tracciabile, poi disabilitare la registrazione aperta se non ti serve pubblicamente.

Hardening minimo che non va saltato

Synapse esposto su Internet senza hardening è una cattiva idea. Anche se il protocollo Matrix è pensato per la federazione, il servizio resta un’applicazione web con superfici da limitare. Le misure base sono poche ma vanno fatte bene: aggiornamenti, permessi stretti, TLS valido, registrazione controllata e backup verificati.

Controlli pratici:

• Il file /etc/matrix-synapse/homeserver.yaml deve essere leggibile solo dall’utente di servizio e da root, non dal mondo.
• La porta interna di Synapse non deve essere esposta direttamente su Internet se usi un proxy.
• Gli utenti guest e la registrazione aperta vanno tenuti spenti se non servono.
• I secret non vanno messi in chiaro in script condivisi o ticket.

Se vuoi una postura più solida, aggiungi un backup del database e dei media store, oltre al controllo dei log di accesso del reverse proxy. È il minimo per capire chi entra, da dove e con quale volume di traffico.

Backup e ripristino: il punto che si dimentica sempre

Un’istanza Matrix senza strategia di backup è fragile. Non basta salvare solo la configurazione: servono anche il database PostgreSQL e la directory dei media caricati dagli utenti. Se perdi uno di questi due pezzi, il servizio resta magari in piedi, ma i dati non sono davvero recuperabili.

Per PostgreSQL puoi usare un dump logico o, per ambienti più seri, una strategia con backup consistenti e test di restore. Esempio di dump:

pg_dump -U synapse_user -h 127.0.0.1 synapse_db | gzip > /backup/synapse_db.sql.gz

Per il media store, salva la directory indicata nella configurazione di Synapse. Il path può cambiare, ma spesso è sotto una directory dati dedicata del servizio. Non fare ipotesi: cerca il parametro media_store_path nel file YAML e usa quello come fonte di verità.

Il restore va testato in un ambiente separato. Se non l’hai mai provato, non hai un backup: hai solo una speranza.

Debug dei problemi più comuni

Se Synapse non parte, i casi più frequenti sono tre: credenziali database errate, YAML malformato o porta già occupata. Il primo controllo è sempre il log, poi il file di configurazione, poi l’ascolto delle porte.

journalctl -u matrix-synapse -n 50 --no-pager
python3 -c 'import yaml; print(yaml.safe_load(open("/etc/matrix-synapse/homeserver.yaml")))'
ss -ltnp | grep 8008

Se i client si collegano ma la federazione fallisce, il controllo successivo è sul file /.well-known/matrix/server, sul certificato e sulla raggiungibilità esterna. Da una macchina esterna prova anche:

curl -s https://matrix.example.com/.well-known/matrix/server
curl -I https://matrix.example.com/_matrix/client/versions

Se invece il problema è prestazionale, osserva l’uso CPU, RAM, numero di connessioni al database e latenza dei messaggi. Synapse risente molto di database lenti e storage saturi, quindi il collo di bottiglia non è sempre l’applicazione in sé.

Quando conviene fermarsi e riprogettare

Se l’istanza deve servire molti utenti, più domini o una federazione pesante, conviene progettare da subito un layout più ordinato: PostgreSQL separato, backup automatici, reverse proxy ben gestito, monitoraggio e controllo accessi. In quel caso Synapse non è “un servizio da installare”, ma un componente da trattare come qualunque altro backend critico.

La regola pratica è semplice: se stai correggendo lo stesso tipo di errore due o tre volte, non è un incidente isolato, è un problema di architettura o di processo. Allora vale la pena sistemare naming, TLS, backup e logging in una volta sola invece di rincorrere i sintomi.

Checklist rapida di validazione

Prima di dichiarare conclusa l’installazione, verifica questi punti:

1. systemctl status matrix-synapse mostra il servizio attivo.
2. curl -I https://matrix.example.com/_matrix/client/versions risponde con HTTP 200.
3. journalctl -u matrix-synapse non mostra errori DB o YAML.
4. /.well-known/matrix/server è servito correttamente in HTTPS.
5. Il primo utente admin è stato creato e la registrazione pubblica è disabilitata se non necessaria.

Se questi cinque punti sono a posto, hai un’istanza Synapse pronta per essere usata davvero, non solo avviata. Da lì in poi il lavoro vero diventa manutenzione: aggiornamenti, monitoraggio, backup e controllo dei log.