Come configurare un server Matrix su Raspberry Pi 4 con Conduit

Un Raspberry Pi 4 può essere utilizzato come pratico server Matrix di piccole dimensioni per uso domestico, per gruppi privati ​​o laboratori, e Conduit è progettato pensando all'hardware leggero. Matrix è un protocollo aperto per la comunicazione decentralizzata: gli utenti si connettono a un server principale , che memorizza i loro account e i dati delle stanze, mentre la federazione consente a tale server di scambiare eventi con altri server Matrix.

Questa guida utilizza Conduit in Docker, con NGINX come proxy per HTTPS. In questo modo, il servizio Matrix rimane isolato sul Raspberry Pi, esponendo solo le porte web pubbliche. Le istruzioni sono state verificate confrontandole con la documentazione di Conduit, Matrix, Raspberry Pi, Docker e NGINX disponibile a ottobre 2026. È importante sottolineare una limitazione: Conduit è ancora in versione beta , quindi è più adatto agli utenti che accettano che alcune funzionalità di Matrix e le versioni precedenti delle stanze potrebbero non funzionare esattamente come in un'implementazione Synapse più matura. Prima di utilizzare Conduit per un servizio critico, consultare la documentazione ufficiale del progetto .

1. Comprendi la configurazione prima di installare qualsiasi cosa

Il percorso finale è semplice: un client Matrix come Element si connette a https://matrix.example.com; NGINX termina la connessione TLS e inoltra la richiesta a Conduit sul Raspberry Pi; Conduit memorizza il suo database nello storage persistente di Docker. Se la federazione è abilitata, gli altri server domestici raggiungono lo stesso endpoint HTTPS pubblico.

Avrai bisogno di un Raspberry Pi 4, un alimentatore affidabile, una scheda microSD o un'unità SSD e un sistema operativo a 64 bit. Un'unità SSD è preferibile per un server che prevedi di utilizzare a lungo termine, poiché Matrix scrive continuamente dati del database e file multimediali. Avrai bisogno anche di un nome di dominio se il server deve essere raggiungibile da Internet.

Al 15 settembre 2026, la versione corrente di Raspberry Pi OS a 64 bit è basata su Debian 13 "Trixie", e Raspberry Pi OS Lite è disponibile per il Raspberry Pi 4. Consultare la pagina ufficiale di download di Raspberry Pi OS . Per questo server, Lite è una buona soluzione perché evita un ambiente desktop non necessario.

Scegliere con attenzione il nome del server Matrix.

In questa guida, il nome del server è matrix.example.com. L'ID utente Matrix risultante ha il seguente aspetto @alice:matrix.example.com: . Considera questo nome come una scelta di identità a lungo termine. Gli ID Matrix e i riferimenti di federazione includono il nome del server, quindi modificarlo in seguito non equivale semplicemente a rinominare un host web.

2. Installa Raspberry Pi OS e aggiorna il Pi

Scrivi Raspberry Pi OS Lite a 64 bit sulla scheda o sull'SSD con Raspberry Pi Imager, abilita SSH durante la creazione dell'immagine se desideri un'installazione senza interfaccia grafica e avvia il Raspberry Pi. Verifica di utilizzare un sistema ARM a 64 bit:

uname -m
cat /etc/os-release

uname -mdovrebbe normalmente segnalare aarch64. Quindi installa gli aggiornamenti correnti:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

3. Installa Docker Engine e Compose

La documentazione di Docker afferma che gli utenti di Raspberry Pi OS a 64 bit dovrebbero utilizzare i pacchetti Debian ARM64 supportati anziché il percorso precedente di Raspberry Pi OS a 32 bit. La procedura ufficiale è disponibile sulla pagina di Docker Engine per Debian . La seguente configurazione del repository segue tale approccio:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io   docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world

Se il comando finale visualizza la conferma "hello-world" di Docker, il runtime del container funziona correttamente. Puoi continuare a utilizzarlo sudo dockerper il resto della guida. Aggiungere il tuo account al dockergruppo è facoltativo, ma ricorda che l'appartenenza a un gruppo Docker garantisce di fatto il controllo a livello di root dell'host.

4. Creare una configurazione Conduit

Conduit può essere configurato tramite un file TOML o variabili d'ambiente. La documentazione ufficiale di configurazione di Conduit elenca server_name, database_backend, e database_pathcome campi obbligatori e raccomanda RocksDB.

Crea una directory di lavoro:

sudo mkdir -p /opt/conduit
sudo chown "$USER":"$USER" /opt/conduit
cd /opt/conduit
nano conduit.toml

Utilizza questa configurazione iniziale e sostituisci il nome host e il token di registrazione:

[global]
server_name = "matrix.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167

allow_registration = true
registration_token = "replace-with-a-long-random-secret"
allow_federation = true
trusted_servers = ["matrix.org"]

Perché proprio 0.0.0.0qui? All'interno di un container, Conduit deve rimanere in ascolto sull'interfaccia del container affinché Docker possa raggiungerlo. La porta lato host sarà comunque associata solo a 127.0.0.1, quindi la porta 6167 non è esposta direttamente a Internet.

5. Esegui Conduit con Docker Compose

Crea /opt/conduit/docker-compose.yml:

services:
  conduit:
    image: registry.gitlab.com/famedly/conduit/matrix-conduit:latest
    container_name: matrix-conduit
    restart: unless-stopped
    ports:
      - "127.0.0.1:6167:6167"
    volumes:
      - ./conduit.toml:/etc/conduit.toml:ro
      - conduit-data:/var/lib/matrix-conduit/
    environment:
      CONDUIT_CONFIG: /etc/conduit.toml

volumes:
  conduit-data:

L'immagine stabile del registro GitLab è quella consigliata dalla documentazione ufficiale di Conduit per Docker . Evitate di copiare un tag di immagine obsoleto da un tutorial a caso; utilizzate il registro ufficiale e consultate le note di rilascio prima di effettuare gli aggiornamenti.

Avvia il servizio e verificane il funzionamento:

cd /opt/conduit
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 conduit

Desideri che il container rimanga in uno Upstato attivo o in esecuzione senza ripetuti cicli di riavvio. Prima di configurare NGINX, verifica l'API locale:

curl http://127.0.0.1:6167/_matrix/client/versions

6. Puntare il DNS al Raspberry Pi e mettere NGINX davanti a Conduit

Crea un Arecord matrix.example.comche punti al tuo indirizzo IPv4 pubblico. Se pubblichi un AAAArecord, assicurati che IPv6 raggiunga effettivamente il Raspberry Pi; un record IPv6 errato può causare il malfunzionamento dei client anche quando IPv4 funziona.

Su un tipico router domestico, inoltra le porte TCP 80 e 443 al Raspberry Pi. Se il tuo ISP utilizza NAT di livello carrier (CGNAT), il normale inoltro delle porte in entrata potrebbe non funzionare; in tal caso avrai bisogno di un indirizzo IP pubblico, di una configurazione VPS/tunnel inverso o di un'altra soluzione di hosting.

Installare NGINX:

sudo apt install -y nginx

Crea /etc/nginx/sites-available/matrix:

server {
    listen 80;
    server_name matrix.example.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Documenti guida ufficiali di NGINX per i proxy inversiproxy_pass e intestazioni inoltrate utilizzate in questo contesto.

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix
sudo nginx -t
sudo systemctl reload nginx

7. Abilitare HTTPS e il rilevamento della matrice

Matrix richiede un protocollo HTTPS valido per una normale distribuzione pubblica. Ottieni un certificato solo dopo che il DNS si è risolto sul Raspberry Pi e la porta 80 è raggiungibile. Debian Trixie fornisce pacchetti Certbot, mentre il progetto Certbot pubblica anche istruzioni specifiche per la piattaforma sul sito certbot.eff.org .

Un percorso comune in Debian/NGINX è:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d matrix.example.com

Dopo che Certbot ha aggiornato l'host virtuale NGINX, testa nuovamente la configurazione:

sudo nginx -t
sudo systemctl reload nginx

Poiché questa guida utilizza lo stesso nome host sia per il nome del server Matrix che per l'endpoint pubblico, Conduit può rispondere ai /.well-knownpercorsi di rilevamento di Matrix tramite il proxy inverso. La specifica Matrix definisce questi endpoint in modo che i client e gli altri server possano individuare l'URL corretto del server principale. Consultare la specifica client-server di Matrix .

8. Crea il primo account, quindi verifica il server

La documentazione Docker di Conduit afferma che il primo account creato su un nuovo homeserver diventa l'amministratore. Apri un client Matrix che supporti i token di registrazione, scegli un homeserver personalizzato e inserisci:

https://matrix.example.com

Registra il primo account utilizzando il token da conduit.toml. Fallo subito dopo aver messo online il servizio. Se non desideri ulteriori registrazioni, modifica la configurazione per impostare allow_registration = falsee riavvia il container:

cd /opt/conduit
sudo docker compose restart conduit

Ora esegui tre controlli da qualsiasi macchina in grado di raggiungere il dominio:

curl https://matrix.example.com/_matrix/client/versions

curl https://matrix.example.com/.well-known/matrix/client

curl https://matrix.example.com/.well-known/matrix/server

La prima richiesta dovrebbe restituire un JSON che descrive le versioni supportate dell'API client Matrix. Le richieste note dovrebbero restituire informazioni di rilevamento JSON valide. Per la federazione, utilizzare anche il Matrix Federation Tester e provare a unirsi a una stanza federata dal nuovo account.

Errori comuni che impediscono il funzionamento di un server Raspberry Pi Matrix

• Utilizzare un sistema operativo a 32 bit inutilmente: per un Raspberry Pi 4, utilizzare Raspberry Pi OS a 64 bit e i pacchetti Debian ARM64 supportati da Docker.
• Esposizione diretta di Conduit: mantenere la porta 6167 associata 127.0.0.1sull'host ed esporre HTTPS tramite NGINX.
• Lasciare la registrazione aperta senza protezione: utilizzare un token di registrazione sicuro durante la configurazione iniziale, quindi disabilitare la registrazione quando non è necessaria.
• Pubblicazione di DNS errati: se si pubblicano entrambi i record, IPv4 e IPv6 devono puntare a un endpoint funzionante.
• Dimenticare le regole del router o del firewall: un container corretto non può compensare il blocco delle porte TCP 80/443 in entrata.
• Supponendo che messaggistica e chiamate vocali siano la stessa cosa: la messaggistica di Matrix può funzionare mentre le chiamate falliscono. La documentazione di Conduit afferma che la comunicazione vocale richiede un server TURN come Coturn.
• Saltare i backup: le FAQ di Conduit raccomandano di arrestare Conduit prima di effettuare una normale copia del database sul filesystem, a meno che non si utilizzi uno snapshot del filesystem appropriato. Eseguire il backup del volume Docker e della configurazione prima degli aggiornamenti.

Come si presenta un'installazione di successo

Hai finito quando tutte queste condizioni sono vere: il container Conduit rimane in esecuzione dopo un riavvio; https://matrix.example.com/_matrix/client/versionsrestituisce JSON; un client Matrix può registrarsi o accedere al tuo homeserver personalizzato; l'account può creare una stanza e inviare un messaggio; e, se la federazione è abilitata, il tester di federazione può raggiungere il server e l'utente può comunicare con gli account su un altro homeserver.

Per una piccola installazione su Raspberry Pi, questa rappresenta una base di partenza pulita, non la fine dell'amministrazione. Monitorate lo spazio di archiviazione libero, mantenete aggiornati Raspberry Pi OS e Docker, eseguite il backup del database e consultate la documentazione ufficiale di Conduit prima di abilitare funzionalità aggiuntive. Conduit rimane un'opzione leggera e interessante per hardware di classe Pi, ma il suo stato beta è un aspetto operativo da non sottovalutare.