# listmonk Docker Compose ve HTTPS ile nasıl kurulur

> listmonk bülten yöneticisini Docker Compose ve PostgreSQL ile sunucunuza kurun, Caddy ile HTTPS üzerinden sunun, SMTP bağlayın, yedek ve güncelleme ayarlayın.

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

listmonk, kendi sunucunuzda çalışan bir bülten ve e-posta listesi yöneticisidir: aboneleri, listeleri, şablonları ve kampanya istatistiklerini kendi PostgreSQL veritabanınızda tutar, gönderimi istediğiniz SMTP servisi üzerinden yapar. Barındırılan bülten araçlarına hızlı, tek dosyalık bir alternatif arayan ekipler için uygundur; transactional iletiler için bir API de sunar.

Bu rehber listmonk'u proje deposundaki **resmi Docker Compose dosyasıyla** kurar. Uygulamayı `127.0.0.1:9000` üzerinde tutar, Caddy ile HTTPS üzerinden yayınlar, Süper Yönetici hesabını güvenli şekilde oluşturur, kök URL'yi ve medya depolamayı ayarlar, bir SMTP relay bağlar ve isteğe bağlı olarak bounce (geri dönen e-posta) işlemeyi açarsınız. Son bölümler yedekleme, geri yükleme, güncelleme ve sorun gidermeyi anlatır.

## Ön koşullar

- **Ubuntu 24.04 LTS**, **Ubuntu 26.04 LTS**, **Debian 12** veya **Debian 13** çalıştıran bir sunucu.
- `sudo` yetkisine sahip, root olmayan bir kullanıcı. Henüz hazırlamadıysanız [Yeni bir Linux sunucusunu güvenli hale getirin](/guides/secure-a-new-linux-server) ve [SSH anahtarlarını ayarlayın](/guides/ssh-keys) rehberlerini izleyin.
- Compose eklentisiyle birlikte Docker Engine: [Ubuntu'ya Docker kurulumu](/guides/install-docker-ubuntu) veya [Debian'a Docker kurulumu](/guides/install-docker-debian).
- [Caddy ile reverse proxy](/guides/caddy-reverse-proxy) rehberinde anlatıldığı gibi sunucuya kurulmuş Caddy.
- Sunucunuza yönlenen bir A kaydına (IPv6 kullanıyorsanız AAAA kaydına da) sahip `listmonk.example.com` gibi bir alan adı.
- Gönderim için bir SMTP servisine erişim; örneğin bir transactional e-posta sağlayıcısının sunucu adı, portu, kullanıcı adı ve parolası.

listmonk PostgreSQL 12 veya daha yenisini gerektirir; resmi Compose dosyası PostgreSQL 17'yi zaten bir konteynerde çalıştırır. Proje en düşük CPU veya bellek gereksinimi yayınlamaz. Aşağıdaki değerler resmi ya da ölçülmüş rakamlar değil, temkinli bir başlangıç noktasıdır:

| Kaynak | En düşük (resmi) | Önerilen başlangıç |
|---|---|---|
| CPU | Yayınlanmıyor | 1 vCPU |
| Bellek | Yayınlanmıyor | 1 GB RAM |
| Disk | Yayınlanmıyor | 10 GB, ayrıca veritabanı ve yüklemeler için pay |
| Veritabanı | PostgreSQL 12 veya üstü | Resmi Compose dosyasındaki PostgreSQL 17 |

Büyük listeler ve yüksek gönderim hızları daha fazla CPU ve veritabanı G/Ç kullanır; ilk büyük kampanyanızda `docker stats` ile kaynakları izleyin ve gerekirse sunucuyu büyütün.

## Adım 1 — Resmi Compose dosyasını indirin

Proje klasörünü oluşturun, sahibini kendi kullanıcınız yapın ve `docker-compose.yml` dosyasını kurulum rehberinde gösterildiği gibi listmonk deposundan indirin:

```bash
sudo mkdir -p /opt/listmonk && sudo chown $USER:$USER /opt/listmonk
cd /opt/listmonk
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml
less docker-compose.yml
```

Çalıştırmadan önce dosyayı okuyun. İki servis tanımlar: `app` (imaj `listmonk/listmonk:latest`) ve `db` (`listmonk-data` adlı volume ile `postgres:17-alpine` imajı). Uygulama tamamen `LISTMONK_*` ortam değişkenleriyle yapılandırılır; başlatma komutu önce `--install --idempotent`, sonra `--upgrade`, ardından sunucuyu çalıştırır. Medya yüklemeleri `./uploads` klasöründe, yani sunucuda `/opt/listmonk/uploads` içinde saklanır.

## Adım 2 — Gizli değerleri ayarlayın ve uygulama portunu gizli tutun

Depodaki dosya veritabanı parolası olarak `listmonk` kullanır ve 9000 portunu sunucunun tüm adreslerinde yayınlar. Rastgele bir veritabanı parolası ve ilk Süper Yönetici hesabının bilgileriyle bir `.env` dosyası oluşturun ve dosyayı yalnızca sizin okuyabileceğiniz hale getirin:

```bash
cd /opt/listmonk
echo "LISTMONK_DB_PASSWORD=$(openssl rand -hex 24)" > .env
echo "LISTMONK_ADMIN_USER=admin" >> .env
echo "LISTMONK_ADMIN_PASSWORD=$(openssl rand -base64 18)" >> .env
chmod 600 .env
cat .env
```

Üretilen yönetici parolasını şimdi parola yöneticinize kopyalayın. Ardından veritabanı parolasını yeni değişkene bağlayın ve uygulamayı yalnızca loopback adresinde yayınlayın:

```bash
sed -i 's/"9000:9000"/"127.0.0.1:9000:9000"/' docker-compose.yml
sed -i 's/&db-password listmonk/\&db-password ${LISTMONK_DB_PASSWORD}/' docker-compose.yml
grep -nE '9000:9000|db-password' docker-compose.yml
```

Port satırını `"127.0.0.1:9000:9000"` olarak, `POSTGRES_PASSWORD` satırını da `${LISTMONK_DB_PASSWORD}` ile biter halde görmelisiniz. Dosya bir YAML anchor kullandığı için PostgreSQL ve listmonk aynı değeri alır. Compose'un değeri çözdüğünü doğrulayın:

```bash
docker compose config | grep -E 'POSTGRES_PASSWORD|LISTMONK_db__password|published'
```

> **Not**
>
> `grep` hiçbir satır bulamazsa depodaki dosya bu rehber yazıldıktan sonra değişmiştir. Dosyayı `nano docker-compose.yml` ile açın ve aynı iki değişikliği elle yapın. PostgreSQL portu dosyada olduğu gibi `127.0.0.1:5432` adresine bağlı kalır; internetten erişilemez.

## Adım 3 — listmonk'u başlatın ve Süper Yöneticiyi oluşturun

İki konteyneri arka planda başlatın:

```bash
docker compose up -d
docker compose ps
docker compose logs app --tail 30
```

`docker compose ps` çıktısında `listmonk_app` ve `listmonk_db` çalışır durumda, veritabanı da healthy olarak görünmelidir. Bu ilk başlatmada listmonk tablolarını oluşturur; `LISTMONK_ADMIN_USER` ve `LISTMONK_ADMIN_PASSWORD` ayarlı olduğu için Süper Yönetici hesabını da açar. Uygulamanın yerelde yanıt verdiğini kontrol edin:

```bash
curl -I http://127.0.0.1:9000/admin/login
```

`HTTP/1.1 200 OK` gibi bir durum satırı almalısınız. Yönetici değişkenleri yalnızca ilk başlatmada okunur; parolayı sakladıktan sonra bunları `.env` dosyasından silin:

```bash
sed -i '/^LISTMONK_ADMIN_/d' .env
cat .env
```

## Adım 4 — listmonk'u Caddy ile HTTPS üzerinden sunun

`/etc/caddy/Caddyfile` dosyasına alan adınız için bir site bloğu ekleyin. Caddy TLS sertifikasını otomatik olarak alır ve yeniler:

```caddyfile
listmonk.example.com {
    reverse_proxy 127.0.0.1:9000
}
```

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

```bash
sudo systemctl reload caddy
curl -I https://listmonk.example.com/admin/login
```

Güvenlik duvarının yalnızca SSH ve web trafiğine izin verdiğinden emin olun. 9000 portu `127.0.0.1` adresine bağlı olduğu için kural gerektirmez:

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

Nginx veya Traefik tercih ediyorsanız [Nginx ve Certbot](/guides/nginx-reverse-proxy-certbot) ya da [Traefik](/guides/traefik-reverse-proxy) rehberini kullanın ve aynı adrese yönlendirin.

> **İpucu**
>
> listmonk'un yapılandırma belgeleri hangi yolların herkese açık (`/subscription/*`, `/link/*`, `/campaign/*`, `/public/*`, `/webhooks/service/*`, `/uploads/*`), hangilerinin özel (`/admin/*`, `/api/*`, `/webhooks/bounce`) olduğunu listeler. Önüne bir kimlik doğrulama proxy'si veya web uygulama güvenlik duvarı koyarsanız abonelik formları, izleme bağlantıları ve abonelikten çıkma sayfaları çalışmaya devam etsin diye herkese açık yolları açık bırakın.

## Adım 5 — Kök URL'yi ve medya depolamayı ayarlayın

`https://listmonk.example.com/admin/login` adresini açın ve Süper Yönetici hesabıyla giriş yapın. listmonk 4. sürümden beri bu giriş sayfasını kullanır ve rollere sahip birden fazla kullanıcıyı destekler; hesabınızı paylaşmak yerine çalışma arkadaşlarınız için **Settings → Users** altında ayrı hesaplar oluşturun.

**Settings → General** bölümüne gidin ve **Root URL** değerini sonda eğik çizgi olmadan `https://listmonk.example.com` yapın. listmonk bu genel adresi ürettiği her bağlantıda kullanır: abonelikten çıkma ve tercih sayfaları, izleme bağlantıları, arşiv sayfaları ve medya adresleri. Aynı ekranda **Default `from` email** alanına gönderen alan adınızdaki bir adresi, **Admin notification e-mails** alanına da kendi adresinizi yazın. **Save** düğmesine tıklayın; listmonk ayarlarını yeniden yükler.

Ardından **Settings → Media** bölümünü açın. **filesystem** sağlayıcısıyla **Upload path** değerini `/listmonk/uploads` yapın; Compose dosyası bu klasörü sunucudaki `/opt/listmonk/uploads` klasörüne bağlar. **Upload URI**, bu dosyaların kök URL altında sunulduğu genel yoldur; değiştirmek için bir nedeniniz yoksa varsayılanı koruyun. **Campaigns → Media** altında bir test görseli yükleyin ve `/opt/listmonk/uploads` içinde göründüğünü kontrol edin.

**Settings → Privacy** bölümünü de gözden geçirin. Buradaki **Individual subscriber tracking**, **Include `List-Unsubscribe` header**, **Allow exporting** ve **Allow wiping** gibi seçenekler, abonelerin kendi verileriyle neler yapabileceğini ve sizin onlar hakkında neleri kaydettiğinizi belirler.

## Adım 6 — Bir SMTP sunucusu bağlayın

listmonk e-postaları kendisi teslim etmez: her iletiyi **Settings → SMTP** altında eklediğiniz SMTP sunucularına iletir.

> **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.

**Settings → SMTP** bölümünü açın ve e-posta sağlayıcınızın veya relay sunucunuzun bilgilerini girin:

- **Host** ve **Port**: relay sunucusunun adı, örneğin `smtp.example.com`, ve `587` numaralı port.
- **Auth protocol**, **Username** ve **Password**: sağlayıcının verdiği değerler; birçok sağlayıcı parola olarak bir API anahtarı kullanır.
- **TLS**: 587 numaralı portun beklediği STARTTLS.
- **HELO hostname**: isteğe bağlı, size ait bir sunucu adı.

Kaydetmeden önce **Test connection** düğmesine tıklayın ve kendinize bir test iletisi gönderin. Birden fazla SMTP sunucusu ekleyip aynı anda birkaçını etkinleştirebilirsiniz. **Retries**, gönderim anında başarısız olan bir iletinin havuzdaki diğer bağlantılarla kaç kez sessizce yeniden deneneceğini belirler; sonra ileti hata olarak loglanır.

Sağlayıcınız gönderen alan adı için SPF ve DKIM kayıtları yayınlamanızı isteyecektir; bir DMARC kaydı da eklemelisiniz. Bu kayıtlar olmadan birçok alıcı sunucu kampanyalarınızı spam klasörüne koyar veya reddeder.

## Adım 7 — Bounce işlemeyi açın (isteğe bağlı)

Bounce kayıtları hangi adreslerin artık e-posta kabul etmediğini gösterir. **Settings → Bounces** bölümüne gidin ve **Enable bounce processing** seçeneğini açın. Bounce bilgisini iki yoldan alabilirsiniz:

- **Webhook** (**Enable bounce webhooks**): listmonk'ta Amazon SES (`/webhooks/service/ses`), SendGrid (`/webhooks/service/sendgrid`), Postmark (`/webhooks/service/postmark`), Azure Communication Services, Forward Email ve Lettermint için hazır uç noktalar vardır. Tam adresi, örneğin `https://listmonk.example.com/webhooks/service/ses`, sağlayıcınızın panelinde tanımlayın.
- **Posta kutusu** (**Enable bounce mailbox**): listmonk bounce iletilerini alan bir POP3 posta kutusunu tarar; örneğin **Settings → SMTP → Custom headers** altında `Return-Path` başlığı olarak ayarlanan ayrı bir adres.

Her bounce türü (soft, hard, complaint) için bir sayı ve bir **Action** seçersiniz. Belgelerdeki Amazon SES örneği soft bounce için 2 sayısı ve none eylemini, hard bounce ve şikâyetler için 1 sayısı ve blocklist eylemini kullanır. Listenizi bu şekilde temiz tutmak gönderici itibarınızı korur.

## Yedekleme ve geri yükleme

listmonk durumunun neredeyse tamamını PostgreSQL'de tutar. Tam bir yedek üç parçadan oluşur: veritabanı dökümü, `uploads` klasörü ve `docker-compose.yml` ile `.env` dosyalarınız. Döküm listmonk çalışırken alınabilir:

```bash
sudo mkdir -p /opt/backups && sudo chown $USER:$USER /opt/backups && chmod 700 /opt/backups
cd /opt/listmonk
docker compose exec -T db pg_dump -U listmonk -Fc listmonk > /opt/backups/listmonk-db-$(date +%F).dump
tar czf /opt/backups/listmonk-files-$(date +%F).tar.gz -C /opt/listmonk docker-compose.yml .env uploads
ls -lh /opt/backups
```

Döküm abonelerinizin kişisel verilerini içerir; yedek klasörünü gizli tutun ve dosyaları sunucunun dışına da kopyalayın, örneğin `rsync` ile veya bir nesne depolama alanına. Bir geri yüklemeyi test ettikten sonra bu iki komutu cron ile zamanlayın.

Geri yüklemek için dosyaları `/opt/listmonk` içine açın, yalnızca veritabanını başlatın, boş veritabanını yeniden oluşturun ve dökümü yükleyin. `.env` dosyası, veritabanı volume'u oluşturulurken kullanılan parolanın aynısını içermelidir.

> **Uyarı**
>
> Aşağıdaki geri yükleme mevcut listmonk veritabanını siler. Yalnızca verileri değiştirmek istediğiniz bir sunucuda çalıştırın; oradaki veriler önemliyse önce yeni bir döküm alın.

```bash
cd /opt/listmonk
tar xzf /opt/backups/listmonk-files-2026-10-09.tar.gz -C /opt/listmonk
docker compose stop app
docker compose up -d --wait db
docker compose exec -T db dropdb -U listmonk --if-exists listmonk
docker compose exec -T db createdb -U listmonk listmonk
docker compose exec -T db pg_restore -U listmonk -d listmonk < /opt/backups/listmonk-db-2026-10-09.dump
docker compose up -d
```

Tarihleri kendi yedek dosyalarınızınkilerle değiştirin. Giriş yapın ve listelerin, abonelerin ve kampanyaların geri geldiğini kontrol edin.

## listmonk güncelleme

Önce [sürüm notlarını](https://github.com/knadh/listmonk/releases) okuyun ve bir veritabanı yedeği alın; listmonk yükseltme rehberi her yükseltmeden önce yedek ister ve daha yeni bir sürümün yükselttiği veritabanı eski sürümle kullanılmamalıdır. Güncel Compose dosyasıyla belgelenen yükseltme şöyledir:

```bash
cd /opt/listmonk
docker compose down app
docker compose pull
docker compose up app -d
docker compose logs app --tail 30
```

Başlatma komutu `--upgrade` adımını kendiliğinden çalıştırır; şema geçişleri yeni konteyner başlarken uygulanır. `latest` etiketi her zaman en yeni sürümü izler. Belirli bir sürümde kalmak için `docker-compose.yml` içindeki etiketi GitHub sürümler sayfasındaki bir sürüm etiketiyle değiştirin, örneğin `listmonk/listmonk:v6.2.0`, ve yükseltirken bilinçli olarak güncelleyin.

Ana sürümler bazen Compose dosyasının kendisini de değiştirir. Örneğin 6. sürüm veritabanı sunucu adını `listmonk_db` yerine `db` yaptı. Bir ana sürüm yükseltmesinden önce dosyanızı depodaki güncel `docker-compose.yml` ile karşılaştırın ve iki yerel değişikliğinizi yeni dosyaya taşıyın.

## Sorun giderme

### password authentication failed for user "listmonk"

PostgreSQL parolayı yalnızca boş bir volume'u ilk kez hazırlarken ayarlar. Yığını Adım 2'den önce başlattıysanız volume hâlâ eski parolayı kullanır. Veri içermeyen yeni bir kurulumda volume'u `docker compose down -v` ile silin ve yeniden başlatın. Aksi halde yeni parolayı veritabanı içinde `docker compose exec db psql -U listmonk -c "ALTER USER listmonk PASSWORD 'value-from-env';"` komutuyla ayarlayın ve uygulamayı yeniden başlatın.

### Bind for 127.0.0.1:5432 failed: port is already allocated

Sunucuda 5432 numaralı portu dinleyen başka bir PostgreSQL sunucusu var. listmonk veritabanına iç Docker ağı üzerinden ulaşır; bu yüzden `db` servisinin `ports:` girdisini silebilir veya `"127.0.0.1:5433:5432"` olarak değiştirip `docker compose up -d` komutunu yeniden çalıştırabilirsiniz.

### E-postalardaki bağlantılar localhost'a veya yanlış adrese gidiyor

**Settings → General** altındaki **Root URL** hâlâ varsayılan değerde. Sonda eğik çizgi olmadan HTTPS adresinize ayarlayın, kaydedin ve yeni bir test kampanyası gönderin; daha önce gönderilmiş iletiler eski bağlantılarını korur.

### SMTP ayarlarında Test connection başarısız oluyor

Önce sunucu adını, portu ve TLS modunu kontrol edin: 587 numaralı port STARTTLS bekler. Sunucunun relay'e ulaşıp ulaşamadığını `nc -vz smtp.example.com 587` ile test edin. Zaman aşımı, sunucu ile relay arasındaki bir güvenlik duvarının bağlantıyı düşürdüğünü; kimlik doğrulama hatası ise yanlış bilgileri veya gönderim yetkisi olmayan bir API anahtarını gösterir.

### Caddy 502 Bad Gateway döndürüyor

listmonk `127.0.0.1:9000` üzerinde yanıt vermiyor. `/opt/listmonk` içinde `docker compose ps` ve `docker compose logs app --tail 50` komutlarını çalıştırın. Başlangıçta sürekli yeniden başlama genellikle uygulamanın veritabanına ulaşamadığı veya `.env` dosyasının eksik olduğu anlamına gelir.

## Sonraki adımlar

- listmonk'u kapsamlı bir pazarlama otomasyonu paketiyle karşılaştırmak için [Mautic nasıl kurulur](/guides/install-mautic) rehberine bakın.
- Compose dosyaları hakkında daha fazlasını [Docker Compose temelleri](/guides/docker-compose-basics) rehberinde öğrenin.
- Aynı proxy arkasında başka uygulamalar barındırmak için [Caddy ile reverse proxy](/guides/caddy-reverse-proxy) rehberini kullanın.
- Bülten ve kampanya sunucularını [e-posta pazarlama hosting](/email-marketing-hosting) sayfasında inceleyin.
- Şablonları, API'yi ve rolleri [listmonk belgelerinde](https://listmonk.app/docs/) keşfedin.

## Sık sorulan sorular

### listmonk e-postaları kendisi gönderebilir mi?

Hayır. listmonk, yapılandırdığınız SMTP sunucusu üzerinden gönderir. 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 destek talebiyle açılır. O zamana kadar e-postaları 587 numaralı port üzerinden bir SMTP relay ile gönderin.

### Docker ile listmonk --install komutunu elle çalıştırmam gerekir mi?

Hayır. Resmi docker-compose.yml uygulamayı her başlatmada önce --install --idempotent, ardından --upgrade ile çalıştırır; böylece şema boş veritabanında bir kez oluşturulur ve yeni imaj çektiğinizde otomatik yükseltilir.

### İlk yönetici hesabı nasıl oluşturulur?

İlk docker compose up için LISTMONK_ADMIN_USER ve LISTMONK_ADMIN_PASSWORD değerlerini ayarlarsanız listmonk Süper Yönetici hesabını kendisi oluşturur. Bunlar yoksa web arayüzünü ilk açan kişi hesabı oluşturur; bu rehber bu yüzden değerleri önceden ayarlar.

### Neleri yedeklemem gerekir?

Listeler, aboneler, kampanyalar, şablonlar ve ayarlar PostgreSQL veritabanında durur; bunu pg_dump ile dökün. Ayrıca medya dosyalarınızın bulunduğu uploads klasörünü, docker-compose.yml dosyasını ve veritabanı parolasını içeren .env dosyasını saklayın.

### listmonk hangi HyperDC sunucularında çalışır?

listmonk, root erişiminiz ve desteklenen bir Ubuntu veya Debian sürümünüz olan her HyperDC Linux VPS, VDS veya dedicated sunucuda Docker içinde çalışır. E-postaların teslimini bağladığınız SMTP servisi yapar.

---

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