# 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`](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). ```bash 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=` — 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:@:27017/butcem?authSource=&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). ```bash 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: (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: ```bash 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ı. ```bash SMOKE_USER=admin SMOKE_PASSWORD='' 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) ```bash sudo install -d -m 755 /opt/butcem ``` Betikler için `/opt/butcem` klasörünü oluşturur. ```bash 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. ```bash 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ı. ```bash 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 ```bash sudo /opt/butcem/butcem-backup.sh ``` Yedeği hemen alır; sonunda `Tamam: … veritabanı, … dosya` yazmalı. ```bash 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 ```bash 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 ``` ```bash sudo tail -n 20 /var/log/butcem-backup.log ``` Ertesi gün son yedeğin günlüğünü gösterir. ## 7. Geri yükleme ```bash 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: ```bash sudo /opt/butcem/butcem-restore.sh /var/backups/butcem/mongo-.archive.gz /var/backups/butcem/uploads-.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 ls -ln /app/uploads` sahibi 1001 olmalı | | Sertifika alınamadı | DNS A kaydı ve 80 portu Traefik'e ulaşıyor mu? | ```bash docker logs --tail 100 $(docker ps -q --filter name= | head -n1) ``` Uygulama konteynerinin son 100 log satırını gösterir (Dokploy › Logs ile aynı).