docs(deploy): Dokploy canlıya alma ve MongoDB replica set kılavuzları
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+254
@@ -0,0 +1,254 @@
|
||||
# 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=<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).
|
||||
|
||||
```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: <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:
|
||||
|
||||
```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='<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)
|
||||
|
||||
```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-<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? |
|
||||
|
||||
```bash
|
||||
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ı).
|
||||
Reference in New Issue
Block a user