butcem/docs/DEPLOY.md

Canlıya alma (Dokploy + Gitea)

BÜTÇEM'i Atlas sunucusunda Dokploy ile https://butcem.ta1sph.website adresinde yayınlamak, güncellemek, yedeklemek ve geri yüklemek için adım adım kılavuz.

Mimari: Gitea (main dalı) → webhook → Dokploy, Dockerfile ile imaj build eder → konteyner başlarken veritabanını hazırlar (replica set kontrolü, migration'lar, ilk admin) → Next.js uygulaması 3000 portunda → Traefik HTTPS ile dışarı açar. MongoDB aynı Dokploy ağında, dışa portsuz. Yüklenen dosyalar /app/uploads volume'unda.

Sunucu komutları Atlas'ta çalıştırılır. Her komutun altında ne yaptığı yazıyor. <…> ile gösterilen yerleri kendi değerlerinizle değiştirin.

---

1. Ön koşullar

• MongoDB servisi replica set olarak çalışıyor ve butcem_app kullanıcısı hazır → MONGODB-KURULUM.md (1–5. adımlar).
• Gitea'da BÜTÇEM reposu (main dalı güncel; git push origin main).
• DNS: butcem.ta1sph.website için Atlas'ın genel IP'sine A kaydı (ve gerekiyorsa modemde 80/443 yönlendirmesi Traefik'e).

dig +short butcem.ta1sph.website

Alan adının çözüldüğü IP'yi gösterir; Atlas'ın genel IP'si olmalı.

2. Dokploy'da uygulama

Dokploy › proje › Create Service › Application, ad: butcem.

2.1 Kaynak (General)

• Provider: Gitea (Dokploy › Settings › Git'te Gitea bağlantısı tanımlıysa) ya da Git (repo URL'si + Dokploy'un SSH anahtarı Gitea'da deploy key olarak ekli).
• Repository / Branch: BÜTÇEM reposu, main.
• Build Type: Dockerfile (yol: Dockerfile, context: .).
• Build Args (isteğe bağlı): APP_COMMIT=<kısa-commit> — sağlık kontrolünde görünür; boşsa unknown yazar. Sürüm package.json'dan otomatik gelir.

2.2 Ortam değişkenleri (Environment)

Değişken	Değer	Not
MONGODB_URI	mongodb://butcem_app:<parola>@<iç-host>:27017/butcem?authSource=<admin|butcem>&replicaSet=rs0&directConnection=true	Ayrıntı: MONGODB-KURULUM.md › 5
BETTER_AUTH_SECRET	32+ karakter rastgele	Aşağıdaki komutla üretin; değiştirirseniz tüm oturumlar kapanır
BETTER_AUTH_URL	https://butcem.ta1sph.website	Sonunda / yok
SEED_ADMIN_EMAIL	yönetici e-postası	İlk açılışta admin oluşturulur
SEED_ADMIN_PASSWORD	güçlü parola (8+)	İlk girişten sonra parolayı değiştirip bu değişkeni silebilirsiniz
MAX_UPLOAD_MB	10	İsteğe bağlı

NODE_ENV=production, PORT=3000 ve UPLOAD_DIR=/app/uploads imajda tanımlıdır; eklemeyin. SEED_USER_PASSWORD canlıda kullanılmaz (örnek kullanıcı oluşturulmaz).

openssl rand -base64 32

BETTER_AUTH_SECRET için 32 baytlık rastgele bir değer üretir.

2.3 Volume (Advanced › Volumes / Mounts)

• Volume Mount · ad: butcem-uploads · bağlama yolu: /app/uploads. Fiş, ürün görseli ve ek dosyalar burada tutulur; imaj yeniden oluşturulduğunda kaybolmaz. (Bind mount yerine adlandırılmış volume kullanın; imajdaki dizin izinleri — uid 1001 — volume'a ilk oluşturulurken aktarılır.)

2.4 Domain (Domains)

• Host: butcem.ta1sph.website · Path: / · Container Port: 3000
• HTTPS: açık · Certificate: Let's Encrypt

2.5 İlk deploy

Deploy'a basın ve Logs'ta şu satırları bekleyin:

• MongoDB rs0 PRIMARY
✓ Migration: 001-initial-indexes — …        (ilk kurulumda 15 migration)
✓ Admin oluşturuldu: <e-posta> (kullanıcı adı: admin)
✓ Ready in …

"MongoDB replica set olarak çalışmıyor" hatası görürseniz MONGODB-KURULUM.md › 3'ü uygulayın. Konteynerin Docker sağlık durumu birkaç saniye içinde healthy olur (/api/health).

2.6 İlk giriş

https://butcem.ta1sph.website › kullanıcı adı admin ve SEED_ADMIN_PASSWORD.

1. Yönetim › Kullanıcılar'dan aile üyelerini oluşturun.
2. Yönetim › Haneler'den haneyi açıp üyeleri ve rollerini ekleyin.
3. (Önerilir) Admin parolasını Yönetim › Kullanıcılar › kendi satırınız › Şifre sıfırla ile değiştirip Dokploy'da SEED_ADMIN_PASSWORD'u silin ve yeniden deploy edin; başlatma artık yalnızca migration'ları çalıştırır. (Admin hesabı varken bu değişken parolayı değiştirmez.)

3. Duman testi (smoke test)

Kendi bilgisayarınızda, repo klasöründe:

scripts/smoke-test.sh https://butcem.ta1sph.website 1.0.0

Sağlık (veritabanı, replica set, sürüm), güvenlik başlıkları, HTTP→HTTPS yönlendirmesi ve oturumsuz erişimin engellendiğini kontrol eder; veri değiştirmez. Tümü ✓ olmalı.

SMOKE_USER=admin SMOKE_PASSWORD='<parola>' scripts/smoke-test.sh https://butcem.ta1sph.website 1.0.0

Ayrıca giriş yapıp ana sayfanın açıldığını dener (parola komut geçmişine düşer; sonra history -d ile silebilir ya da satırı boşlukla başlatabilirsiniz).

Elle kontrol listesi (bir kez, tarayıcıdan):

• Giriş / çıkış, telefondan PWA olarak ana ekrana ekleme.
• Bir hesap ve bir gider işlemi oluşturma (transaction'lı yazma).
• İşleme fiş fotoğrafı ekleyip görüntüleme (uploads volume).
• Bir transfer (iki hesap birden; transaction).
• Dokploy'da uygulamayı Restart edip fişin hâlâ açıldığını görme (volume kalıcılığı).

4. Otomatik deploy (Gitea webhook)

Dokploy › butcem › Deployments › Webhook URL'yi kopyalayın (Auto Deploy açık olmalı). Gitea › repo › Settings › Webhooks › Add Webhook › Gitea:

• Target URL: kopyaladığınız Dokploy URL'si · HTTP Method: POST · Content type: JSON
• Trigger On: Push Events · Branch filter: main
• Kaydedip Test Delivery ile deneyin; Dokploy'da yeni bir deployment başlamalı.

Bundan sonra git push origin main → otomatik build ve yayın. Her deploy'da bekleyen migration'lar uygulama açılmadan önce çalışır.

5. Güncelleme ve geri alma

• Normal güncelleme: main'e push (webhook) ya da Dokploy'da Deploy.
• Büyük güncellemeden önce elle yedek alın: sudo /opt/butcem/butcem-backup.sh (bkz. 6).
• Geri alma: Dokploy › Deployments › önceki başarılı deployment › Rollback (ya da Gitea'da önceki commit'e dönüp push). Migration'lar yalnızca ileri yönlüdür; yeni sürümün eklediği index/alanlar eski sürümü bozmaz. Veri bozulduysa 7'deki geri yüklemeyi kullanın.
• Acil durum: başlatma adımı (migration) hata verip uygulama açılmıyorsa geçici olarak SKIP_BOOTSTRAP=1 ortam değişkeniyle açabilirsiniz; sorunu giderince kaldırın.

6. Yedekleme

Günlük: butcem veritabanı (mongodump) + uploads volume arşivi + SHA-256 özetleri, 7 gün saklama, /var/backups/butcem altında. Betik: scripts/backup/butcem-backup.sh.

⚠️ Şimdilik yedekler yalnızca sunucuda. Disk arızasında yedekler de gider; bir sonraki adım olarak sunucu dışına kopya (NAS'a rsync ya da S3 uyumlu depolama) eklenmeli.

6.1 Kurulum (bir kez)

sudo install -d -m 755 /opt/butcem

Betikler için /opt/butcem klasörünü oluşturur.

sudo install -m 750 scripts/backup/butcem-backup.sh scripts/backup/butcem-restore.sh /opt/butcem/

Yedek ve geri yükleme betiklerini (repo klasöründen; sunucuya scp ile de kopyalayabilirsiniz) /opt/butcem'e yalnızca root'un çalıştırabileceği izinle kopyalar.

sudo install -m 600 scripts/backup/butcem-backup.env.example /etc/butcem-backup.env
sudo nano /etc/butcem-backup.env

Ayar dosyasını yalnızca root'un okuyabileceği izinle oluşturur ve düzenlemek için açar. Doldurun:

• MONGO_CONTAINER: MongoDB konteyner adının ayırt edici kısmı (docker ps --format '{{.Names}}').
• MONGO_ROOT_USER / MONGO_ROOT_PASSWORD: butcem_root bilgileri.
• UPLOADS_VOLUME: uygulamanın volume adı.

  docker volume ls | grep -i uploads
  

  Volume adlarını listeler (Dokploy'da verdiğiniz butcem-uploads adını doğrulayın).

6.2 İlk çalıştırma

sudo /opt/butcem/butcem-backup.sh

Yedeği hemen alır; sonunda Tamam: … veritabanı, … dosya yazmalı.

sudo ls -lh /var/backups/butcem && sudo sh -c 'cd /var/backups/butcem && sha256sum -c SHA256SUMS-*'

Yedek dosyalarını listeler ve bütünlüklerini doğrular (OK).

6.3 Günlük zamanlama

sudo crontab -e

root'un zamanlanmış görevlerini açar. Şu satırı ekleyin (her gece 03:30):

30 3 * * * /opt/butcem/butcem-backup.sh >> /var/log/butcem-backup.log 2>&1

sudo tail -n 20 /var/log/butcem-backup.log

Ertesi gün son yedeğin günlüğünü gösterir.

7. Geri yükleme

sudo ls -1 /var/backups/butcem

Mevcut yedekleri listeler; dönülecek tarih damgasını seçin.

1. Dokploy › butcem › Stop (yazma olmasın).
2. Geri yükleyin:

   sudo /opt/butcem/butcem-restore.sh /var/backups/butcem/mongo-<damga>.archive.gz /var/backups/butcem/uploads-<damga>.tar.gz
   

   Bütünlüğü kontrol eder, onay ister (evet), butcem veritabanını yedektekiyle değiştirir ve uploads volume'unu arşivden yeniden yazar. Yalnızca veritabanı için ikinci dosyayı vermeyin.
3. Dokploy › Start, ardından duman testi (3).

Tatbikat: Ayda bir, en son yedeği bu adımlarla deneme amaçlı bir Dokploy kopyasına ya da lokale (docker compose mongo'su) yükleyip açılıp açılmadığını kontrol edin. Yedeği hiç denenmemiş bir yedek, yedek değildir.

8. Sorun giderme

Belirti	Neden / çözüm
Logs: MongoDB replica set olarak çalışmıyor	MONGODB-KURULUM.md › 3
Logs: Authentication failed	MONGODB_URI kullanıcı/parola/authSource; parola URL kodlu mu?
Logs: Geçersiz ortam değişkenleri	Listelenen değişkeni düzeltin (ör. BETTER_AUTH_SECRET < 32 karakter)
Konteyner unhealthy	curl -s https://butcem.ta1sph.website/api/health → db alanı; MongoDB servisi çalışıyor mu?
Giriş sonrası tekrar giriş sayfası	BETTER_AUTH_URL alan adıyla birebir aynı mı (https, sonda / yok)?
Yüklenen dosya açılmıyor / yükleme hatası	Volume /app/uploads'a bağlı mı? docker exec <app> ls -ln /app/uploads sahibi 1001 olmalı
Sertifika alınamadı	DNS A kaydı ve 80 portu Traefik'e ulaşıyor mu?

docker logs --tail 100 $(docker ps -q --filter name=<butcem-uygulama-adı> | head -n1)

Uygulama konteynerinin son 100 log satırını gösterir (Dokploy › Logs ile aynı).