Kurulum (self-host)

SingleMail'i kendi sunucunuza kurmak yaklaşık yarım saat sürer. Bu sayfa platformu işletecek ekip içindir; yalnızca e-posta göndermek istiyorsanız İlk e-postanız rehberiyle başlayın.

Gerekenler

• Docker ve Docker Compose kurulu bir Linux sunucu (2 vCPU, 4 GB RAM yeterli). Coolify ya da Proxmox üzerindeki bir VM de olur.
• Panel ve API için bir alt domain, ör. mail.firma.com ve TLS sertifikası (Coolify/Traefik otomatik alır).
• E-postayı teslim edecek bir SMTP relay. Başlangıç için Amazon SES (eu-central-1, Frankfurt) öneriyoruz.

Kurulum adımları

1. Kodu alın

   terminal

   git clone <repo-adresi>/singlemail.git
   cd singlemail
   cp .env.example .env

2. .env dosyasını doldurun

   Değişken	Açıklama
   PUBLIC_URL	API'nin dışarıdan erişilen adresi. Takip linkleri bu adrese işaret eder.
   APP_SECRET	Uzun, rastgele bir değer. Takip linklerini imzalar; kurulumdan sonra değiştirmeyin.
   DATABASE_URL / REDIS_URL	Postgres ve Redis bağlantıları. Compose dosyası bunları kendisi ayarlar.
   SMTP_RELAY_URL	E-postayı internete teslim edecek SMTP sunucusu (Amazon SES, Postfix …).
   SPF_INCLUDE / RETURN_PATH_MX	Müşterilere gösterilen SPF ve MX kayıtları; relay'inize göre ayarlayın.
   SMTP_INGRESS_TLS_KEY / _CERT	SMTP girişi için TLS sertifikası. Production'da zorunlu.
   POSTGRES_PASSWORD / REDIS_PASSWORD	Veritabanı ve Redis şifreleri. Compose bu servisleri yalnızca sunucunun kendisine (127.0.0.1) açar.
   SES_SNS_TOPIC_ARN	Bounce/şikâyet bildirimlerinin geldiği SNS topic'i. Yalnızca AWS imzalı ve bu topic'ten gelen mesajlar kabul edilir; boşsa uç kapalıdır.
   ADMIN_EMAIL / ADMIN_PASSWORD	Varsayılan yönetici hesabı. Her açılışta oluşturulur ya da şifresi güncellenir; şifre en az 12 karakter olmalı ve yalnızca buradan değişir.
   REQUIRE_ADMIN_2FA	true ise bütün yöneticiler (ADMIN_EMAIL dahil) panele girmeden önce iki adımlı doğrulamayı (TOTP) açmak zorundadır. Varsayılan false: iki adımlı doğrulama herkes için isteğe bağlıdır. Production'da true önerilir.
   ALLOW_SIGNUP	Herkese açık kayıt. Varsayılan olarak kapalı: müşteriler yöneticinin açtığı hesaplarla giriş yapar.
   RATE_LIMIT_RPS	Proje başına saniyelik istek sınırı (varsayılan 10).

   .env

   PUBLIC_URL=https://mail.firma.com
   APP_SECRET=<openssl rand -base64 48 çıktısı>
   POSTGRES_PASSWORD=<openssl rand -base64 32 çıktısı>
   REDIS_PASSWORD=<openssl rand -base64 32 çıktısı>
   SES_SNS_TOPIC_ARN=arn:aws:sns:eu-central-1:<hesap>:singlemail-feedback
   SMTP_INGRESS_TLS_KEY=/certs/privkey.pem
   SMTP_INGRESS_TLS_CERT=/certs/fullchain.pem
   SMTP_RELAY_URL=smtps://AKIA…:SES_SMTP_PASSWORD@email-smtp.eu-central-1.amazonaws.com:465
   SPF_INCLUDE=amazonses.com
   RETURN_PATH_MX=feedback-smtp.eu-central-1.amazonses.com
   ADMIN_EMAIL=yonetici@firma.com
   ADMIN_PASSWORD=<en az 12 karakterlik güçlü bir şifre>
   REQUIRE_ADMIN_2FA=true
   ALLOW_SIGNUP=false

3. Servisleri başlatın

   terminal

   docker compose up -d --build
   docker compose ps        # postgres, redis, api, worker, smtp, web

   Veritabanı tabloları API ilk açıldığında otomatik oluşturulur. Geliştirme ortamı değilse compose dosyasından mailpit servisini çıkarın.

   Servis	Port	Görevi
   web	3001	Landing page, dokümanlar, müşteri ve yönetici panelleri
   api	3000	REST API, takip linkleri, SES geri bildirimi
   smtp	2587	SMTP girişi
   worker	—	Gönderim ve webhook kuyrukları

4. Yönetici olarak giriş yapın

   Servisler açılınca ADMIN_EMAIL hesabı otomatik oluşur. https://mail.firma.com/login adresinden bu bilgilerle giriş yapın. Şifreyi değiştirmek için .env dosyasını güncelleyip servisleri yeniden başlatın; eski oturumlar kapanır.

   Ek yöneticiler panelden (Kullanıcılar → Yönetici yap) ya da komut satırından açılabilir:

   terminal

   docker compose exec api pnpm sm admin:create ikinci@firma.com "En-az-10-karakterlik-sifre"

5. İlk müşteriyi açın

   Yönetici panelinde Şirketler → Yeni müşteri formunu doldurun: şirket, plan, ilk proje, giriş yapacak kullanıcı ve bir API anahtarı tek seferde oluşur. Ayrıntılar Yönetici paneli sayfasında.

6. Sistem sayfasını kontrol edin

   Yönetici panelinde Sistem sayfasını açın. Postgres, Redis, SMTP relay ve API yeşil görünmeli. Turuncu satırlar production'dan önce düzeltilmesi gereken ayarlardır.

   

Amazon SES ayarları

1. SMTP kimlik bilgisi oluşturun

   SES konsolunda bölge olarak eu-central-1 seçin, SMTP settings bölümünden SMTP kullanıcısı oluşturun ve SMTP_RELAY_URL değişkenine yazın.

2. Sandbox'tan çıkın

   Yeni SES hesapları yalnızca doğrulanmış adreslere gönderebilir. production access talebinde kullanım amacını (transactional e-posta, bounce/şikâyet yönetimi var) kısaca anlatın.

3. Geri bildirimleri bağlayın

   Bir configuration set ve SNS topic oluşturun; Delivery, Bounce, Complaint olaylarını topic'e gönderin. Topic'e HTTPS aboneliği olarak https://api.singlemail.singleton.com.tr/providers/ses adresini ekleyin. Abonelik onayı otomatik yapılır.

Coolify

Coolify'da yeni bir Docker Compose kaynağı oluşturup depoyu bağlayın. web servisine panel domainini, api servisine API domainini atayın; smtp için 2587 portunu dışarı açın. Ortam değişkenlerini Coolify arayüzünden girin.

Bakım

• Güncelleme: git pull && docker compose up -d --build. Veritabanı değişiklikleri API açılırken uygulanır.
• Yedek: Postgres'i düzenli yedekleyin: docker compose exec postgres pg_dump -U singlemail singlemail > yedek.sql. Redis yalnızca kuyruk tutar.
• Ölçekleme: Gönderim yükü artınca worker servisinden birden fazla çalıştırın (docker compose up -d --scale worker=3).
• Demo verisi: pnpm seed:demo örnek projeler ve e-postalar üretir; dokümanlardaki ekran görüntüleri pnpm docs:screenshots ile yenilenir.