Kaldırma¶

Bu sayfa, scripts/windows/ ve scripts/linux/ altındaki install/update/ uninstall script'lerinin GERÇEKTE ne yaptığını belgeler — repo kökündeki README.md dosyasının "Quick Start" bölümüyle aynı komutları, burada daha ayrıntılı anlatır.

Desteklenen matris¶

Platform	Docker	Native (Docker'sız)
Windows	✅ `install.ps1 -Mode docker`	✅ `install.ps1 -Mode native`
Linux	✅ `install.sh --mode docker`	✅ `install.sh --mode native`

-Mode/--mode verilmezse (auto), script Docker'ın çalışır durumda olup olmadığını (docker info + docker compose version) kontrol eder ve buna göre otomatik seçer; kararını her zaman loglar ([INFO] Installation mode: docker|native).

Docker modu ne kurar¶

docker-compose.prod.yml (repo kökü) — mevcut docker-compose.yml (hot-reload geliştirme ortamı, bind-mount + npm run dev/pnpm run dev) DEĞİŞTİRİLMEDİ ve hâlâ docker compose up -d ile çalışıyor. docker-compose.prod.yml ayrı bir Compose projesi ismiyle (iqv-dictionary-prod) tamamen production imajlar kullanır: backend/Dockerfile.prod (multi-stage: npm ci + npm run build → node dist/server.js, asla npm run dev) ve dashboard/Dockerfile.prod (multi-stage: pnpm install + pnpm run build → statik dosyalar nginx ile servis edilir, dashboard/nginx.conf, asla Vite dev server).
MongoDB'yi containerize ETMEZ — mevcut docker-compose.yml gibi, uygulamanın zaten dışarıda (host/başka bir sunucu) çalışan MongoDB'sine bağlanır (host.docker.internal).
Portlar, publish edilen bind adresi ve frontend'in build-time API adresi repo kökündeki .env dosyasından okunur (yoksa .env.example'dan otomatik oluşturulur): IQV_BACKEND_PORT (varsayılan 3001), IQV_FRONTEND_PORT (varsayılan 8080), IQV_BIND_HOST (varsayılan 0.0.0.0), VITE_API_BASE_URL.
docker-compose.prod.yml generictir: credential, müşteriye/ sunucuya özel network, IP, port veya hostname içermez ve backend/.env'deki MONGODB_URI değerini ezmez.

Configuration katmanları¶

Katman	Git	İçerik
`.env`	gitignored (`.env.example` tracked)	`IQV_FRONTEND_PORT`, `IQV_BACKEND_PORT`, `IQV_BIND_HOST`, `VITE_API_BASE_URL`
`backend/.env`	gitignored (`backend/.env.example` tracked)	`MONGODB_URI`, `MONGODB_DB`, koleksiyonlar, `JWT_SECRET`, `JWT_EXPIRES_IN`, `CORS_ORIGIN`
`docker-compose.prod.yml`	tracked	Generic production Docker tanımı
`docker-compose.server.yml`	gitignored (`docker-compose.server.example.yml` tracked)	Opsiyonel sunucu/müşteri Docker override'ı

MongoDB bağlantısının tek kaynak-doğrusu backend/.env'dir. Compose yalnızca extra_hosts: host.docker.internal:host-gateway ile bu adın çözülebilmesini sağlar; gerçek URI (gerekiyorsa credential ile) backend/.env'de durur ve repository'ye hiçbir zaman girmez.

Server override (`docker-compose.server.yml`)¶

Sunucuya özel Docker ayarları için tracked dosyaları elle düzenlemek gerekmez. Sunucuda bir kereye mahsus:

cp docker-compose.server.example.yml docker-compose.server.yml

Dosya mevcutsa install/update/uninstall script'leri ve npm run docker:* komutları onu otomatik algılar:

# override yoksa
docker compose -f docker-compose.prod.yml --env-file .env <komut>

# override varsa
docker compose -f docker-compose.prod.yml -f docker-compose.server.yml \
  --env-file .env <komut>

Bu çözümleme tek bir helper'da tanımlıdır — scripts/linux/lib.sh içindeki iqv_compose (Windows: Invoke-IqvCompose, npm: scripts/common/compose.mjs) — ve install/update/rebuild/status/ healthcheck/uninstall akışlarının tamamı aynı helper'ı kullanır; hiçbir script kendi compose argümanlarını üretmez.

Tipik içerik (Caddy gibi bir reverse proxy'nin external Docker network'ü):

services:
  dictionary-backend:
    networks: [default, iqv_proxy]
  dictionary-frontend:
    networks: [default, iqv_proxy]

networks:
  iqv_proxy:
    external: true
    name: iqv_proxy

Portların loopback'e bağlanması için ayrı bir override gerekmez — .env içinde IQV_BIND_HOST=127.0.0.1 yeterlidir. Portları tamamen değiştirmek isterseniz docker-compose.server.example.yml içindeki !override örneği (Compose v2.24+) kullanılabilir.

Native mod ne kurar¶

Backend: npm ci + npm run build (derlenmiş backend/dist/server.js).
Dashboard: corepack ile pnpm@9.15.9 etkinleştirilir, pnpm install --frozen-lockfile + pnpm run build (statik dashboard/dist).
Süreç yönetimi: her iki platformda da PM2 (scripts/common/ecosystem.config.js) — aynı iş mantığı, Windows/Linux arasında fark yok:
Backend: node dist/server.js (PM2 altında, autorestart).
Frontend: dashboard/dist'i servis eden, bağımlılıksız, projeye özel statik dosya sunucusu (scripts/common/static-server.mjs) — Docker imajındaki nginx'in native karşılığı; Windows'a ayrıca nginx kurmayı gerektirmez.
Reboot/oturum açılışında otomatik başlatma:
Windows: pm2-windows-startup (pm2-startup install) — admin gerektirmez, PM2'nin kayıtlı process listesini oturum açılışında geri yükler.
Linux: pm2 startup systemd — systemd birimi üretir; script bunu parolasız sudo varsa otomatik kurar, yoksa çalıştırılacak tam komutu ekrana basar (script asla parola bekleyip takılı kalmaz).

Idempotency¶

install.ps1/install.sh ikinci kez çalıştırıldığında:

Var olan backend/.env / dashboard/.env / kök .env DOKUNULMADAN bırakılır ([OK] ... already exists).
Docker modunda docker compose up -d var olan container'ları sadece gerekiyorsa yeniden oluşturur.
Native modda pm2 startOrReload var olan process'leri idempotent şekilde günceller (yeniden yeniden process YARATMAZ).

Update akışı (Bölüm 10-14, IQVizyon kural seti)¶

Production'da tek komut:

cd /opt/iqv/apps/iqv-dictionary
bash ./scripts/linux/update.sh --branch main

Repository kökü doğrulanır (docker-compose.prod.yml, backend/, dashboard/).
Kurulum modu tespiti — .iqv-install/state.json'dan (yoksa çalışan container/PM2 process'lerinden best-effort tespit).
.env ve backend/.env varlığı kontrol edilir; var olanlar dokunulmadan bırakılır, yalnızca eksik olan .example'dan oluşturulur. Ardından .env, backend/.env, dashboard/.env ve docker-compose.server.yml dosyaları .iqv-install/backups/<zaman-damgası>/ altına yedeklenir (içerik asla loglanmaz).
Dirty tree kontrolü — yalnızca TRACKED kaynak (git status --porcelain --untracked-files=no). Gerçek bir kaynak değişikliği varsa update GÜVENLİ ŞEKİLDE İPTAL EDİLİR ve kirli dosyalar listelenir. Untracked/gitignored sunucu configuration'ı (.env, backend/.env, docker-compose.server.yml) update'i engellemez. git reset --hard / git clean -fd / git checkout . / git merge / git rebase script'lerin HİÇBİRİNDE kullanılmaz.
git fetch origin <branch> + hedef branch doğrulaması + git pull --ff-only (diverge varsa güvenli şekilde başarısız olur, hiçbir şeyi ezmez). --branch <ad> verilirse ve checkout edilmiş branch farklıysa, çalışma ağacı temiz olduğu için güvenli bir git checkout yapılır (merge/rebase yok).
VERSION dosyasından "Current version" / "Target version" ve eski→yeni commit SHA'sı loglanır. Yeni .env.example anahtarları geldiyse yalnızca eksik anahtar ADLARI uyarı olarak yazdırılır; mevcut değerler okunmaz/değiştirilmez.
git diff --name-only <eski-sha> <yeni-sha> ile DEĞİŞEN dosyalar incelenir ve buna göre:
backend/package.json/package-lock.json değiştiyse → npm ci
backend/src|scripts değiştiyse → backend yeniden derlenir
backend/Dockerfile* / docker-compose*.yml değiştiyse → Docker imajı yeniden build edilir
dashboard/package.json/pnpm-lock.yaml değiştiyse → pnpm install --frozen-lockfile
dashboard/src|vite.config.ts|... değiştiyse → dashboard yeniden build edilir
backend/scripts/*migrat*|*rename* gibi migration-benzeri dosyalar değiştiyse → OTOMATİK ÇALIŞTIRILMAZ (veri güvenliği), yalnızca [WARN] ile kullanıcıya elle gözden geçirmesi hatırlatılır.
Docker: resolved compose stack (varsa docker-compose.server.yml otomatik eklenir) önce config ile doğrulanır, sonra yalnızca değişen servis(ler) build edilir ve up -d yapılır. Native: pm2 startOrReload/pm2 restart + pm2 save.
Healthcheck — http://127.0.0.1:${IQV_BACKEND_PORT}/health ve http://127.0.0.1:${IQV_FRONTEND_PORT}/; biri bile FAIL ise script hata koduyla çıkar. Başarısız bir update çalışan container'ları kaldırmaz (build hatası up -d'den ÖNCE durur, mevcut sürüm hizmet vermeye devam eder).
.iqv-install/state.json güncellenir (updatedAt, version).

Doğrulama testleri¶

Bu garantiler otomatik olarak test edilir (Docker/MongoDB/network gerekmez, CI'da scripts-lint job'unda çalışır):

bash scripts/linux/tests/deployment-config.test.sh

Uninstall / Purge / Purge-Data (Bölüm 15-17)¶

Komut	Ne yapar
`uninstall.ps1` / `uninstall.sh`	Container'ları veya PM2 process'lerini durdurur/kaldırır. Kaynak kod, `node_modules`, `dist`, `.env` dosyaları DOKUNULMADAN kalır.
`-Purge` / `--purge`	Yukarıya ek: `node_modules`, `dist`, üretilen `.env` dosyaları, Docker prod imajları, `.iqv-install/` durum dizini silinir.
`-Purge -RemoveSource` / `--purge --remove-source`	Yukarıya ek: tüm repository silinir. Script kendi çalıştığı dizini senkron silemeyeceği için, arka planda ayrı bir temizlik script'i (`$TEMP`/`/tmp`'te) zamanlar ve bu script birkaç saniye sonra klasörü siler. Ekstra bir onay (`yes` yazmanız veya `-Yes`/`--yes`) istenir.
`-PurgeData` / `--purge-data`	MongoDB bu kurulum tarafından hiç yönetilmediği (harici DB) için hiçbir veri silmez — yalnızca bunu açıkça loglar.

Varsayılan (bayraksız) uninstall, üretim veritabanını asla silmez — zaten hiçbir zaman bir DB container/volume'u oluşturmaz.

Version mekanizması¶

Tek kaynak-doğrusu: repo kökündeki VERSION dosyası (düz metin, örn. 1.1.0). backend/package.json (1.0.0) ve dashboard/package.json (1.1.0), her alt projenin KENDİ bağımsız modül sürümüdür ve DEĞİŞTİRİLMEDİ — install/update script'leri "Current version"/"Target version" için yalnızca VERSION'ı okur, ikinci bir sürüm dosyası daha icat edilmedi.

Kurulum durumu (state) dosyası¶

.iqv-install/state.json (Git'e girmez — bkz. .gitignore):

{
  "mode": "docker",
  "version": "1.1.0",
  "installPath": "/path/to/Dictionary",
  "installedAt": "2026-08-31T06:00:00Z",
  "updatedAt": "2026-08-31T06:00:00Z",
  "services": { "backend": "iqv-dictionary-backend-prod", "frontend": "iqv-dictionary-frontend-prod" },
  "ports": { "backend": 3001, "frontend": 8080 }
}

Hiçbir secret/token/parola bu dosyaya YAZILMAZ.