listmonk Docker Compose ve HTTPS ile nasıl kurulur

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.

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:

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:

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:

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:

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

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

İki konteyneri arka planda başlatın:

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:

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:

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:

listmonk.example.com {
    reverse_proxy 127.0.0.1:9000
}

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

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:

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 ya da Traefik rehberini kullanın ve aynı adrese yönlendirin.

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.

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:

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.

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

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 rehberine bakın.
• Compose dosyaları hakkında daha fazlasını Docker Compose temelleri rehberinde öğrenin.
• Aynı proxy arkasında başka uygulamalar barındırmak için Caddy ile reverse proxy rehberini kullanın.
• Bülten ve kampanya sunucularını e-posta pazarlama hosting sayfasında inceleyin.
• Şablonları, API'yi ve rolleri listmonk belgelerinde keşfedin.