suphicakir/butcem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(deploy): Dokploy canlıya alma ve MongoDB replica set kılavuzları

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
suphicakir
2026-11-07 02:13:10 +03:00
parent 1bdcedefdc
commit 6ce8ffa4a5
3 changed files with 422 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOY.md
+254
View File
@@ -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ı).
docs/MONGODB-KURULUM.md
+144
View File
@@ -0,0 +1,144 @@
# MongoDB kurulumu (canlı, Dokploy)
BÜTÇEM çok adımlı yazmaları (transfer, "Alışverişi tamamla", kart ödemesi…) **MongoDB transaction**
ile yapar. Transaction yalnızca **replica set** üzerinde çalışır; tek sunucu için **tek düğümlü
replica set** (`rs0`) yeterlidir. Uygulama başlarken bunu kontrol eder; replica set yoksa açık bir
hata mesajıyla durur.
Bu belge mevcut kurulumu esas alır: Dokploy'da **`mongo:7`** veritabanı servisi (mongo:8 sunucu
çekirdeğiyle uyumsuz), kimlik doğrulama açık, `butcem_root` (yönetici) ve `butcem_app` (uygulama)
kullanıcıları oluşturulmuş. Uygulama mongo:7.0 ile test edilmiştir (tüm entegrasyon testleri).
> Komutlar Atlas sunucusunda çalıştırılır. `<…>` ile gösterilen yerleri kendi değerlerinizle
> değiştirin. Parolaları komut geçmişine yazmamak için `mongosh` parola sorduğunda girin.
---
## 1. MongoDB konteynerini bul
```bash
docker ps --format '{{.Names}}' | grep -i mongo
```
Çalışan konteynerlerin adlarından MongoDB'ninkini listeler. Dokploy ada rastgele bir son ek ekler
(ör. `butcem-mongo-a1b2c3.1.xyz`). Aşağıda bu adı `<MONGO>` olarak kullanın; adın ayırt edici
başlangıcı (ör. `butcem-mongo-a1b2c3`) da yeterlidir.
```bash
MONGO=$(docker ps -q --filter name=<mongo-servis-adı> | head -n1); echo "$MONGO"
```
Konteyner kimliğini bir değişkene alır; sonraki komutlar `$MONGO` ile kısalır.
## 2. Replica set açık mı?
```bash
docker exec -it "$MONGO" mongosh -u butcem_root --authenticationDatabase admin \
--eval 'try { const s = rs.status(); print(s.set, s.members[0].stateStr) } catch (e) { print("REPLICA SET YOK: " + e.codeName) }'
```
Yönetici olarak bağlanıp replica set durumunu yazdırır (parolayı sorar).
- Çıktı **`rs0 PRIMARY`** ise replica set hazır; **4. adıma** geçin.
- Çıktı **`REPLICA SET YOK: NoReplicationEnabled`** ise **3. adımı** uygulayın.
## 3. Tek düğümlü replica set'i aç
Dokploy'un MongoDB servisinde bir **"Replica Set"** seçeneği varsa (sürüme göre değişir) onu açıp
servisi yeniden deploy etmeniz ve 3.4'e geçmeniz yeterlidir. Yoksa aşağıdaki elle yöntemi uygulayın.
Kimlik doğrulama açıkken replica set bir **anahtar dosyası (keyfile)** ister.
### 3.1 Yedek alın
```bash
docker exec -it "$MONGO" mongodump -u butcem_root --authenticationDatabase admin --gzip --archive=/data/db/oncesi.archive.gz
docker cp "$MONGO":/data/db/oncesi.archive.gz ~/mongo-oncesi.archive.gz && docker exec "$MONGO" rm /data/db/oncesi.archive.gz
```
Değişiklikten önce tüm veritabanlarının yedeğini konteyner içinde bir dosyaya alır (parolayı sorar),
sonra ev dizinine kopyalayıp konteynerdeki kopyayı siler. Yeni kurulumda veri yoksa atlanabilir.
### 3.2 Anahtar dosyasını oluştur
```bash
docker exec "$MONGO" sh -c 'head -c 756 /dev/urandom | base64 > /data/db/rs-keyfile && chmod 400 /data/db/rs-keyfile && chown 999:999 /data/db/rs-keyfile && ls -l /data/db/rs-keyfile'
```
Kalıcı veri volume'u (`/data/db`) içinde rastgele bir anahtar dosyası üretir; yalnızca `mongodb`
kullanıcısı (uid 999) okuyabilir. Çıktıda `-r-------- … mongodb mongodb` görmelisiniz. Dosya
volume'da olduğu için yeniden başlatmalarda korunur.
### 3.3 Başlatma komutunu değiştir ve yeniden deploy et
Dokploy › MongoDB servisi › **Advanced** sekmesi › **Command** alanına:
```
mongod --replSet rs0 --bind_ip_all --keyFile /data/db/rs-keyfile
```
yazıp kaydedin ve servisi **Redeploy** edin. (`MONGO_INITDB_ROOT_*` ortam değişkenleri yerinde
kaldığı için kimlik doğrulama açık kalır.) Konteyner yeniden oluşacağından 1. adımdaki `MONGO`
değişkenini yeniden alın.
### 3.4 Replica set'i başlat (tek seferlik)
```bash
docker exec -it "$MONGO" mongosh -u butcem_root --authenticationDatabase admin \
--eval 'rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] })'
```
`rs0` adlı tek üyeli replica set'i başlatır; çıktıda `{ ok: 1 }` görmelisiniz. Uygulama
`directConnection=true` ile bağlandığı için üye adresinin `localhost` olması sorun değildir.
Birkaç saniye sonra 2. adımdaki kontrolü tekrarlayın: **`rs0 PRIMARY`**.
## 4. Uygulama kullanıcısını doğrula
```bash
docker exec -it "$MONGO" mongosh -u butcem_root --authenticationDatabase admin --eval '
for (const d of ["admin", "butcem"]) {
const u = db.getSiblingDB(d).getUser("butcem_app");
if (u) print("tanımlı veritabanı:", d, "| roller:", JSON.stringify(u.roles));
}'
```
`butcem_app` kullanıcısının hangi veritabanında tanımlı olduğunu (bağlantı dizesindeki
`authSource`) ve rollerini yazdırır. Beklenen rol: `[{"role":"readWrite","db":"butcem"}]`.
Rol farklıysa düzeltin:
```bash
docker exec -it "$MONGO" mongosh -u butcem_root --authenticationDatabase admin \
--eval 'db.getSiblingDB("<authSource>").updateUser("butcem_app", { roles: [{ role: "readWrite", db: "butcem" }] })'
```
Uygulama kullanıcısına yalnızca `butcem` veritabanında okuma-yazma yetkisi verir (migration'lar
index oluşturmak için bu yetkiyle yetinir).
## 5. Bağlantı dizesi (Dokploy uygulama ortam değişkeni)
```
MONGODB_URI=mongodb://butcem_app:<parola-url-kodlu>@<iç-host>:27017/butcem?authSource=<authSource>&replicaSet=rs0&directConnection=true
```
- `<iç-host>`: Dokploy › MongoDB servisi › **Internal Host** (ör. `butcem-mongo-a1b2c3`). Uygulama
ve veritabanı aynı Dokploy ağında olduğundan **dışa port açmaya gerek yoktur**; açmayın.
- `<authSource>`: 4. adımın çıktısındaki veritabanı (`admin` veya `butcem`).
- Parolada `@ : / ? # %` gibi karakterler varsa URL kodlayın:
```bash
python3 -c 'import urllib.parse,getpass; print(urllib.parse.quote(getpass.getpass(), safe=""))'
```
Parolayı sorar ve bağlantı dizesine yazılacak kodlu hâlini basar (geçmişe düşmez).
## 6. Transaction denemesi (isteğe bağlı)
```bash
docker exec -it "$MONGO" mongosh "mongodb://butcem_app@localhost:27017/butcem?authSource=<authSource>&replicaSet=rs0&directConnection=true" --eval '
const s = db.getMongo().startSession(); const c = s.getDatabase("butcem").getCollection("tx_probe");
s.startTransaction(); c.insertOne({ a: 1 }); s.commitTransaction();
print("transaction tamam:", db.getSiblingDB("butcem").getCollection("tx_probe").countDocuments({}));
db.getSiblingDB("butcem").getCollection("tx_probe").drop();'
```
Uygulama kullanıcısıyla bağlanıp küçük bir transaction yazar, sonucu basar ve deneme
koleksiyonunu siler. `transaction tamam: 1` görmelisiniz.