Ubuntu veya Debian'a Matrix Synapse ve Element Web nasıl kurulur

Matrix, sohbet ve görüşmeler için açık ve federe bir protokoldür: farklı sunuculardaki kullanıcılar, tıpkı e-postada olduğu gibi birbirleriyle konuşabilir. Synapse, Element'in geliştirdiği ana sunucu (homeserver) yazılımıdır; Element Web ise tarayıcı istemcisidir. Bu rehber Synapse'i Ubuntu veya Debian üzerine resmi packages.matrix.org deposundan kurar, verilerini PostgreSQL'de saklar, HTTPS için Caddy'nin arkasına koyar ve .well-known yönlendirmesi kullanır; böylece sunucu matrix.example.com adresinde çalışırken kullanıcı kimlikleri @alice:example.com biçiminde görünür. Ardından Element Web'i kendi alt alan adına ekler, açık kayıt kapalıyken ilk yöneticiyi oluşturur, yedeklemeyi ve güncellemeleri ayarlarsınız.

Kurulum üç ad kullanır. Bunları şimdi seçin:

Adım 1 — PostgreSQL'i kurun ve veritabanını oluşturun

PostgreSQL'i ve Synapse'in kullandığı istemci kütüphanesini kurun, bir parola üretin ve Synapse'in gerektirdiği kodlama ile yerel ayara sahip bir veritabanı kullanıcısı ve veritabanı oluşturun:

sudo apt update
sudo apt install postgresql libpq5
openssl rand -hex 24
sudo -u postgres createuser --pwprompt synapse_user
sudo -u postgres createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse

createuser sorduğunda üretilen parolayı iki kez girin ve Adım 3 için saklayın. Yeni veritabanını kontrol edin:

sudo -u postgres psql -l | grep synapse

Satırda UTF8 kodlaması ile hem sıralama (collation) hem karakter türü için C görünmelidir. Synapse başka bir sıralamaya sahip veritabanında başlamayı reddeder.

Adım 2 — Matrix.org deposunu ekleyin ve Synapse'i kurun

Synapse belgeleri Matrix.org paketlerini önerir. Debian'ın kendi matrix-synapse paketi yalnızca Debian 14 (forky) ve unstable için vardır; belgeler Ubuntu arşivindeki paketi de önermez.

sudo apt install -y lsb-release wget apt-transport-https
sudo 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 matrix-synapse-py3

Kurulum sırasında paket iki soru sorar:

• Name of the server: matrix.example.com değil, sunucu adınızı yani example.com değerini girin. Yanıt /etc/matrix-synapse/conf.d/server_name.yaml dosyasına yazılır.
• Report homeserver usage statistics: tercihinize göre yanıtlayın. Varsayılan hayırdır.

Sonucu kontrol edin:

cat /etc/matrix-synapse/conf.d/server_name.yaml
sudo systemctl status matrix-synapse --no-pager

Paket Synapse'i geçici bir SQLite veritabanıyla hemen başlatır. Henüz hiç hesap olmadığı için bir sonraki adımda PostgreSQL'e geçmek hiçbir şey kaybettirmez.

Adım 3 — Synapse'i PostgreSQL'e yönlendirin ve kaydı kapatın

Ana yapılandırma /etc/matrix-synapse/homeserver.yaml dosyasındadır. Kendi ayarlarınızı bunun yerine /etc/matrix-synapse/conf.d/ içindeki ayrı dosyalara koyun: Synapse bunları ana dosyadan sonra yükler ve paket yükseltmeleri sizden birleştirme istemez. Önce Synapse'i durdurun:

sudo systemctl stop matrix-synapse

Üç dosya oluşturun. Komutu çalıştırmadan önce ilk dosyadaki change-me değerini Adım 1'deki veritabanı parolasıyla değiştirin; ikinci dosya rastgele bir kayıt sırrı üretir:

sudo tee /etc/matrix-synapse/conf.d/database.yaml > /dev/null <<'EOF'
database:
  name: psycopg2
  args:
    user: synapse_user
    password: "change-me"
    dbname: synapse
    host: localhost
    cp_min: 5
    cp_max: 10
EOF
sudo tee /etc/matrix-synapse/conf.d/registration.yaml > /dev/null <<EOF
enable_registration: false
registration_shared_secret: "$(openssl rand -hex 32)"
EOF
echo 'public_baseurl: "https://matrix.example.com/"' | sudo tee /etc/matrix-synapse/conf.d/public_baseurl.yaml

• database, Synapse'i PostgreSQL'e geçirir.
• enable_registration: false açık kaydı kapalı tutar (bu aynı zamanda varsayılandır).
• registration_shared_secret, register_new_matrix_user aracının hesap oluşturmasını sağlar. Bu sırrı bilen herkes, kayıt kapalı olsa bile yöneticiler dahil kullanıcı kaydedebilir; bu yüzden gizli tutun.
• public_baseurl, istemcilerin kullandığı adrestir. Bu ayar olmadan Synapse, çalıştığı yer olmayan https://example.com/ adresini varsayar.

Dosyaları yalnızca root ve matrix-synapse grubunun okuyabileceği hâle getirin, ardından Synapse'i başlatın:

sudo chown root:matrix-synapse /etc/matrix-synapse/conf.d/*.yaml
sudo chmod 640 /etc/matrix-synapse/conf.d/*.yaml
sudo systemctl start matrix-synapse
sudo systemctl status matrix-synapse --no-pager
curl -s http://localhost:8008/_matrix/client/versions

Son komut desteklenen Matrix sürümlerinin JSON listesini yazmalıdır. Synapse yalnızca localhost üzerindeki 8008 portunda dinler ve paketle gelen dinleyici, yerel bir reverse proxy'den gelen X-Forwarded-For başlığına zaten güvenir. Synapse başlamazsa sudo journalctl -u matrix-synapse -n 50 --no-pager çıktısını okuyun.

Synapse; parola sıfırlama, adres doğrulama ve (enable_notifs: true ile) kaçırılan mesaj bildirimi e-postaları gönderebilir; bunu açmak için /etc/matrix-synapse/conf.d/email.yaml gibi bir dosyaya, Synapse'in yapılandırma kılavuzunda email altında anlatıldığı gibi smtp_host: smtp.example.com, smtp_port: 587, require_transport_security: true, smtp_user, smtp_pass ve bir notif_from adresi içeren bir email bölümü ekleyin, ardından Synapse'i yeniden başlatın.

Adım 4 — Caddy'yi Synapse ve yönlendirme için yapılandırın

/etc/caddy/Caddyfile dosyasına iki site bloğu ekleyin. İlki Matrix istemci ve federasyon API'lerini Synapse'e iletir; ikincisi ana alan adınızda yönlendirme dosyalarını sunar:

matrix.example.com {
    reverse_proxy /_matrix/* localhost:8008
    reverse_proxy /_synapse/client/* localhost:8008
}

example.com {
    header /.well-known/matrix/* Content-Type application/json
    header /.well-known/matrix/* Access-Control-Allow-Origin *
    respond /.well-known/matrix/server `{"m.server": "matrix.example.com:443"}`
    respond /.well-known/matrix/client `{"m.homeserver": {"base_url": "https://matrix.example.com"}}`
}

• /.well-known/matrix/server, diğer ana sunuculara example.com için federasyon trafiğini 443 portu üzerinden matrix.example.com adresine göndermelerini söyler; bu yüzden 8448 portu gerekmez.
• /.well-known/matrix/client, kullanıcı yalnızca @alice:example.com yazdığında Element gibi uygulamaların ana sunucuyu bulmasını sağlar.
• /_synapse/admin bilerek iletilmez. Synapse belgeleri yönetim API'sini internete açmayı önermez; gerektiğinde ona localhost:8008 adresine bir SSH tüneliyle ulaşın.

Caddy'yi yeniden yükleyin ve üç adresi de test edin:

sudo systemctl reload caddy
curl https://example.com/.well-known/matrix/server
curl https://example.com/.well-known/matrix/client
curl https://matrix.example.com/_matrix/client/versions

Adım 5 — Güvenlik duvarını açın ve federasyonu test edin

Synapse yalnızca localhost'ta dinler ve yönlendirme federasyon trafiğini 443 portuna gönderir; bu yüzden güvenlik duvarında yalnızca SSH ve web trafiği gerekir:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Federasyonu resmi federation tester aracıyla kontrol edin: example.com girin; tüm kontroller başarılı olmalıdır. Aynı test bir JSON API olarak da kullanılabilir:

curl -s "https://matrix.org/federationtester/api/report?server_name=example.com" | grep -o '"FederationOK":[a-z]*'

Çıktı "FederationOK":true olmalıdır.

Adım 6 — İlk yöneticiyi oluşturun

Kendi hesabınızı yönetici olarak oluşturun. Hem ana yapılandırma dosyasını (dinleyici adresi için) hem de kayıt dosyasını (paylaşılan sır için) verin:

sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml -c /etc/matrix-synapse/conf.d/registration.yaml

Araç bir kullanıcı adı, bir parola ve kullanıcının yönetici yapılıp yapılmayacağını sorar; kendi hesabınız için yes yanıtını verin. Diğer herkes için komutu yönetici yetkisi olmadan tekrarlayın. Yeni kullanıcı kimliği @kullaniciadi:example.com biçimindedir.

Adım 7 — Element Web'i kurun

Element, Element Web'i Debian ve Ubuntu'da çalışan bir Debian paketi olarak yayınlar. Depoyu ekleyin ve paketi kurun:

sudo wget -O /usr/share/keyrings/element-io-archive-keyring.gpg https://packages.element.io/debian/element-io-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/element-io-archive-keyring.gpg] https://packages.element.io/debian/ default main" | sudo tee /etc/apt/sources.list.d/element-io.list
sudo apt update
sudo apt install element-web

/etc/element-web/config.json dosyasını en küçük bir yapılandırmayla değiştirerek Element'i ana sunucunuza yönlendirin:

sudo tee /etc/element-web/config.json > /dev/null <<'EOF'
{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com",
      "server_name": "example.com"
    }
  }
}
EOF

Ardından Caddyfile'a element.example.com için bir site bloğu ekleyin. Blok statik dosyaları /usr/share/element-web klasöründen sunar, Element'in önerdiği güvenlik başlıklarını ayarlar ve her sürümde değişen dosyalar için önbelleği kapatır:

element.example.com {
    root * /usr/share/element-web
    file_server
    header {
        X-Frame-Options SAMEORIGIN
        X-Content-Type-Options nosniff
        X-XSS-Protection "1; mode=block"
        Content-Security-Policy "frame-ancestors 'self'"
    }
    @nocache path / /index.html /version /config.json /i18n/*
    header @nocache Cache-Control no-cache
}

sudo systemctl reload caddy
curl -I https://element.example.com

https://element.example.com adresini açın, Adım 6'daki hesapla giriş yapın, bir oda oluşturun ve mesajların iki yönde de ulaştığını görmek için ikinci bir kullanıcıyı davet edin.

Yedekleme ve geri yükleme

Synapse'in yedekleme rehberi durumu tutan yerleri listeler: PostgreSQL veritabanı, /etc/matrix-synapse içindeki yapılandırma (sunucunun imza anahtarı homeserver.signing.key dahil) ve /var/lib/matrix-synapse/media içindeki yerel medya. Uzak medya, URL önizlemeleri ve bunların küçük resimleri önbellektir ve atlanabilir. Rehber ayrıca e2e_one_time_keys_json tablosunun verisini dışarıda bırakmayı önerir; çünkü eski tek kullanımlık anahtarları geri yüklemek şifreli oturumları bozabilir. pg_dump tutarlı bir anlık görüntü aldığı için Synapse çalışmaya devam edebilir:

sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
chmod 700 /opt/backups
sudo -u postgres pg_dump -Fc --exclude-table-data e2e_one_time_keys_json synapse > /opt/backups/synapse-db-$(date +%F).dump
sudo tar czf /opt/backups/synapse-files-$(date +%F).tar.gz --exclude='remote_*' --exclude='url_cache*' /etc/matrix-synapse /var/lib/matrix-synapse/media /etc/element-web /etc/caddy/Caddyfile
ls -lh /opt/backups

Yeni bir sunucuya geri yüklemek için Adım 1 ve 2'yi aynı sunucu adı ve aynı veritabanı parolasıyla tamamlayın, ancak Synapse veri almadan önce onu durdurun. Synapse rehberi, zaten tablo içeren bir veritabanına asla geri yükleme yapılmaması konusunda uyarır; Synapse şimdiye kadar SQLite kullandığı için Adım 1'deki veritabanı hâlâ boştur.

sudo systemctl stop matrix-synapse
sudo -u postgres pg_restore -d synapse < /opt/backups/synapse-db-2026-10-09.dump
sudo tar xzf /opt/backups/synapse-files-2026-10-09.tar.gz -C /
sudo chown -R matrix-synapse:matrix-synapse /var/lib/matrix-synapse
sudo systemctl start matrix-synapse

Ardından Element Web'i kurun (Adım 7) ve Caddy'yi yeniden yükleyin.

Synapse güncelleme

Synapse diğer paketler gibi apt üzerinden güncellenir. Bazı sürümler yapılandırmayı değiştirdiği veya en düşük Python ya da PostgreSQL sürümünü yükselttiği için önce kendi sürümünüzle yenisi arasındaki her sürümün yükseltme notlarını okuyun ve yedek alın:

sudo apt update
sudo apt upgrade
curl -s http://localhost:8008/_matrix/federation/v1/version

Son komut çalışan Synapse sürümünü yazar. Atladığınız her sürümü tek tek kurmanız gerekmez; ancak veritabanı şeması değiştikten sonra geri dönmek zordur, dönüş yolunuz yedektir. apt bir yapılandırma dosyasını değiştirmek isteyip istemediğinizi sorarsa kendi sürümünüzü koruyun. Aynı apt upgrade Element Web'i de günceller.

Sorun giderme

register_new_matrix_user registration_shared_secret tanımlı değil diyor

Araç yalnızca -c ile verdiğiniz dosyaları okur; conf.d klasörünü taramaz. Adım 6'da gösterildiği gibi hem homeserver.yaml hem de conf.d/registration.yaml dosyasını verin.

Synapse başlamıyor: Database has incorrect collation

Veritabanı C yerine sistem yerel ayarınızla oluşturulmuş. Veritabanını sudo -u postgres dropdb synapse ile silin (yalnızca verisi olmayan yeni bir sunucuda), Adım 1'deki createdb komutuyla yeniden oluşturun ve Synapse'i yeniden başlatın.

Federation tester bir .well-known veya sertifika hatası bildiriyor

Adım 4'teki üç curl komutunu çalıştırın. Sunucu dosyası https://example.com adresinden geçerli bir sertifikayla JSON döndürmeli, m.server değeri matrix.example.com:443 olmalı ve istek HTTP 308 ile yönlendirilmemelidir. İki adın DNS kayıtlarını da kontrol edin.

Element ana sunucuya ulaşamıyor

Tarayıcıda https://matrix.example.com/_matrix/client/versions adresini açın. Açılmıyorsa Caddy bloğunu ve public_baseurl değerini kontrol edin. Açılıyorsa /etc/element-web/config.json içindeki base_url değerini ve /.well-known/matrix/client üzerindeki Access-Control-Allow-Origin başlığını kontrol edin.

Diğer sunuculardan davet edilen kullanıcılar odalarınıza katılamıyor

Federasyon iki yönde de bağlantı gerektirir ve Synapse'in federasyon rehberi yanlış yapılandırılmış bir reverse proxy'yi yaygın bir neden olarak gösterir. Federation tester'ı yeniden çalıştırın, bağlantı hataları için sudo journalctl -u matrix-synapse çıktısını kontrol edin ve sunucunun dışarıya HTTPS bağlantısı kurabildiğinden emin olun.

Sonraki adımlar

• Jitsi Meet ile video toplantılar ekleyin; Element grup görüşmeleri için bir Jitsi sunucusu kullanabilir.
• Matrix'i Mattermost ve Rocket.Chat ile karşılaştırın.
• Burada kullanılan proxy hakkında daha fazlasını Caddy reverse proxy rehberinde öğrenin.
• Worker'lar, e-posta, görüşmeler için TURN ve yönetim API'si için resmi Synapse belgelerini okuyun.
• Ekip sohbeti için sunucuları team chat hosting sayfasında karşılaştırın.