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

> Kendi Matrix sunucunuzu resmi paketlerden Synapse, PostgreSQL, HTTPS ve federasyon yönlendirmesi için Caddy ve tarayıcıda Element Web ile çalıştırın.

Zorluk: İleri\
Denendiği sistemler: Ubuntu 24.04 LTS, Ubuntu 26.04 LTS, Debian 12, Debian 13

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 | Örnek | Amaç |
|---|---|---|
| Sunucu adı | `example.com` | Her kullanıcı kimliğinde ve oda takma adında görünür. Sonradan değiştirilemez. |
| Synapse ana makinesi | `matrix.example.com` | İstemcilerin ve diğer sunucuların 443 portu üzerinden Synapse'e ulaştığı adres. |
| Element Web | `element.example.com` | Tarayıcı istemcisi. Element, siteler arası betik (XSS) hatalarının etkisini sınırlamak için ana sunucudan farklı bir alan adı önerir. |

## Ön koşullar

- x86_64 (amd64) üzerinde **Ubuntu 24.04 LTS**, **Ubuntu 26.04 LTS**, **Debian 12** veya **Debian 13** çalıştıran bir sunucu. Matrix.org paketleri amd64 için derlenir; packages.matrix.org dört sürüm için de paket yayınlar.
- `sudo` yetkisi olan, root olmayan bir kullanıcı: [Yeni bir Linux sunucusunu güvenli hale getirin](/guides/secure-a-new-linux-server) ve [SSH anahtarlarını ayarlayın](/guides/ssh-keys) rehberlerine bakın.
- Bu sunucuyu gösteren, `matrix.example.com` ve `element.example.com` için DNS A kayıtları (IPv6 kullanıyorsanız AAAA kayıtları).
- Ana alan adı `example.com`, HTTPS üzerinden iki küçük JSON dosyası sunmalıdır. Bu sunucuyu gösteriyorsa Caddy bunları Adım 4'te sunar; web siteniz başka bir yerde çalışıyorsa aynı dosyaları orada yayınlarsınız.
- [Caddy reverse proxy](/guides/caddy-reverse-proxy) rehberinde anlatıldığı gibi kurulmuş Caddy.

Synapse projesi en düşük gereksinimleri yayınlamaz. Aşağıdaki değerler küçük, özel bir sunucu için temkinli bir başlangıç noktasıdır, resmi rakamlar değildir:

| Kaynak | En düşük (resmi) | Önerilen başlangıç |
|---|---|---|
| CPU | Yayınlanmamış | 2 vCPU |
| RAM | Yayınlanmamış | 2 GB; kullanıcılar başka sunuculardaki büyük herkese açık odalara katılıyorsa 4 GB |
| Disk | Yayınlanmamış | 20 GB ve yüklenen medya için ek alan |
| Veritabanı | Güncel sürümler için PostgreSQL 14 veya üstü | Dağıtımınızın PostgreSQL paketi |

## 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:

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html) `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.

> **Not**
>
> HyperDC VPS'lerde giden 25 numaralı port varsayılan olarak kapalıdır. 3 ay veya daha uzun süreyle satın alınan hizmetlerde talep üzerine açılır: [destek talebi açın](/guides/support-tickets). O zamana kadar e-postaları 587 numaralı port üzerinden bir SMTP relay ile gönderin.

## 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:

```caddyfile
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:

```bash
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
```

> **Not**
>
> `example.com` başka bir sunucudaki web siteniz ise `example.com` bloğunu dışarıda bırakın ve aynı iki dosyayı o web sitesinde `Content-Type: application/json` ile, istemci dosyası için de `Access-Control-Allow-Origin` başlığıyla yayınlayın. Önlerinde 308 yönlendirmelerinden kaçının: Synapse HTTP 308 yönlendirmelerini izlemez.

## 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:

```bash
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](https://matrix.org/federationtester) 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```caddyfile
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
}
```

```bash
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:

```bash
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
```

> **Uyarı**
>
> İmza anahtarı sunucunuzu tüm federasyona tanıtır ve yerel medya başka hiçbir yerde bulunmayan tek kopya olabilir. Arşivi gizli tutun ve bir kopyasını sunucunun dışında saklayın.

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.

```bash
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ı](https://element-hq.github.io/synapse/latest/upgrade.html) okuyun ve yedek alın:

```bash
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](/guides/install-jitsi-meet) ile video toplantılar ekleyin; Element grup görüşmeleri için bir Jitsi sunucusu kullanabilir.
- Matrix'i [Mattermost](/guides/install-mattermost) ve [Rocket.Chat](/guides/install-rocket-chat) ile karşılaştırın.
- Burada kullanılan proxy hakkında daha fazlasını [Caddy reverse proxy](/guides/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](https://element-hq.github.io/synapse/latest/) okuyun.
- Ekip sohbeti için sunucuları [team chat hosting](/team-chat-hosting) sayfasında karşılaştırın.

## Sık sorulan sorular

### Matrix sunucu adımı sonradan değiştirebilir miyim?

Hayır. Synapse belgeleri server_name değerinin sonradan değiştirilemeyeceğini belirtir. Bu ad her kullanıcı kimliğinin ve oda takma adının parçası olur; bu yüzden kurmadan önce, genellikle example.com gibi ana alan adınız olacak şekilde karar verin.

### 8448 numaralı portu açmam gerekiyor mu?

Yönlendirme (delegation) kullanıyorsanız hayır. Bu rehber ana alan adınızda, diğer sunuculara 443 portu üzerinden matrix.example.com adresini kullanmalarını söyleyen bir .well-known/matrix/server dosyası yayınlar. Yönlendirme olmadan diğer sunucular server_name ana makinesinde 8448 portunu dener.

### Neden SQLite yerine PostgreSQL?

Synapse belgeleri SQLite'ın üretim sunucusunda kullanılmaması gerektiğini ve kurulumların neredeyse tamamının PostgreSQL kullanmasını söyler. SQLite yalnızca test içindir.

### Diğer kişiler nasıl hesap alır?

Açık kayıt kapalı kalır; bu Synapse'in varsayılanıdır. Yönetici olarak hesapları register_new_matrix_user ile siz oluşturursunuz. İleride kullanıcıların kendi kendine kaydolmasını isterseniz, açmadan önce Synapse yapılandırma kılavuzundaki e-posta doğrulaması veya kayıt token'ları gibi kayıt seçeneklerini okuyun.

### Sesli ve görüntülü görüşmeler için TURN sunucusu gerekir mi?

Genellikle evet. Matrix görüşmeleri WebRTC kullanır ve NAT veya sıkı güvenlik duvarları arkasındaki kullanıcılar çoğu zaman bir TURN relay olmadan bağlanamaz. Synapse'in TURN rehberi coturn ile eturnal kurulumunu ve istemcilere TURN kimlik bilgilerini veren turn_uris ile turn_shared_secret ayarlarını anlatır.

---

Kaynak: <https://hyperdc.com/tr/guides/tutorials/install-matrix-synapse>\
Son güncelleme: 2026-10-09