Docker Kurulumu¶

Dağıtım Türü

Docker, yerel işletim sistemi servislerinden ayrı bir dağıtım türüdür. Yerel Windows Servisi dağıtımı için Windows Servis Kurulumu sayfasına bakın. Yerel Linux systemd dağıtımı için Linux systemd Kurulumu sayfasına bakın.

Doğrulama kanıtı

IMPLEMENTED = YES. Eski yazılmış lab sayfaları: Windows Docker RETEST REQUIRED; Linux Docker ForceRedeploy tarihsel LIVE FAIL sonra kod düzeltmesi. Operatör beyanlı e2202ac yeterliliği Canlı E2E sayfasındadır. Ayrıca Docker E2E. Bkz. Docker E2E.

Linux Docker — ÖNERİLEN PRODUCTION

Önceden üretilmiş offline OCI image arşivi + harici / mevcut MongoDB.

Müşteri sunucusunda Go, Git, kaynak, registry pull, docker build ve internet yok.

Docker Engine + Compose önkoşuldur (pakette yoktur).

Bundled MongoDB yalnızca development/lab/opsiyonel legacy’dir.

Tam kılavuz: Ubuntu Docker Kurulumu.

Linux Üretim Önerisi

Linux'ta hem systemd (offline prebuilt binary) hem de Docker (offline prebuilt image) önerilen üretim yöntemleridir. İkisi de harici MongoDB kullanır.

Ön Koşullar¶

Windows¶

Windows Server 2016+ veya Windows 10/11 (64-bit)
Docker Desktop veya Windows için Docker Engine
PowerShell 5.1+
Yönetici (Administrator) yetkileri

Linux (üretim offline paketi)¶

Ubuntu 24.04 amd64
Docker Engine + Docker Compose v2 önceden kurulu
sudo / root
Offline paket iqv-integration-api-<version>-linux-docker-amd64
Container ağından erişilebilir harici MongoDB (gerçek host/IP; loopback değil)

Linux üretim kurucusu Docker Engine kurmaz.

Ortak¶

MongoDB 6.0+ ayrı mevcut servis
Windows Docker host MongoDB için host.docker.internal kullanabilir
Linux Docker üretim URI’yi olduğu gibi kullanır (host.docker.internal rewrite yok)

MongoDB Ayrı Bir Servistir

Docker kurulum betiği MongoDB kurmaz veya yönetmez. Konteyneri başlatmadan önce MongoDB erişilebilir olmalıdır.

Kurulum¶

Windows¶

Yönetici olarak açılmış bir PowerShell istemcisinde çalıştırın:

powershell powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\docker\install.ps1

Linux (offline üretim paketi)¶

bash sudo ./scripts/install.sh \ --external-mongodb \ --mongo-uri "mongodb://<MONGODB_HOST>:27017" \ --mongo-database champion \ --integration-actor-user-id "GERCEK_KULLANICI_OBJECT_ID" \ --host-port 4242 \ --container-port 4242 \ --public-base-url "http://<API_HOST>:4242"

Bkz. Ubuntu Docker Kurulumu.

Linux offline kurucu ne yapar¶

Root, Docker Engine, Compose ve amd64 doğrular.
manifest.json ve image tar SHA256 (uyuşmazlık → docker load yok, mutation yok).
config/.env.example + CLI ile env (mevcut env korunur).
Actor formatı (rastgele ObjectID üretilmez).
docker load (pull/build yok).
Compose doğrulama (yalnızca API; build: yok).
Host port, read-only check, one-shot migrate, compose up -d --no-build.
/health/live, /health/ready, metadata.

Windows kurucu davranışı değişmez.

Ortam Yapılandırması¶

Kurulum betiği env dosyasını asla otomatik oluşturmaz. Depo .env veya açık bir dosya verin:

```bash cp .env.example .env

veya Docker'a özel (gitignore) dosya: .env.docker.external¶

```

Windows — EnvFile / HostPort / ContainerPort¶

powershell .\scripts\windows\docker\install.ps1 ` -ExternalMongoDB ` -EnvFile .\.env.docker.external ` -HostPort 4243 ` -ContainerPort 4242 ` -SkipGitPull

Kavram	Anlam
`HostPort` (`IQV_HOST_PORT`)	Host'ta publish edilen port (`0.0.0.0:4243`)
`ContainerPort` (`HTTP_PORT`)	Container içi dinleme portu (`4242`)
Compose eşlemesi	`${IQV_HOST_PORT}:${HTTP_PORT}` → `4243:4242`
Compose `--env-file`	Yalnızca interpolation (port, image tag, `IQV_ENV_FILE` yolu)
Servis `env_file`	Container runtime ortamı (secret'lar). Interpolation ile aynı değildir

Native Windows Service 4242 üzerinde çalışmaya devam ederken Docker 4243 publish edebilir. Çakışma ön kontrolü yalnızca HostPort içindir (çıkış 15).

Linux üretim (offline paket)¶

--skip-git-pull reddedilir. Linux Docker üretim Git kullanmaz.

bash sudo ./scripts/install.sh \ --external-mongodb \ --mongo-uri "mongodb://<MONGODB_HOST>:27017" \ --mongo-database champion \ --integration-actor-user-id "GERCEK_KULLANICI_OBJECT_ID" \ --host-port 4242 \ --container-port 4242 \ --public-base-url "http://<API_HOST>:4242"

--env-file isteğe bağlıdır. Mevcut /etc/iqvizyon/iqv-integration-api.docker.env üzerine yazılmaz.

Linux Docker: offline install / reboot / NO-OP LIVE PASS. ForceRedeploy LIVE FAIL / RETEST REQUIRED (compose up -d aynı container’ı recreate etmedi; düzeltme: --force-recreate). Rollback bu retest’e bağlıdır.

Dosyayı düzenleyin ve tüm zorunlu değerleri ayarlayın — en azından MONGODB_URI, AUTH_CLIENT_SECRET, AUTH_JWT_SECRET.

Gizli Bilgiler

Env dosyası içeriğini asla günlüğe yazmayın veya paylaşmayın. Secret'lar uygulama günlüklerine ve deployment metadata'ya yazılmaz.

Sunucu MongoDB'ye Bağlanma¶

MongoDB Docker sunucusunda (konteynerde değil) çalışıyorsa:

Windows Docker Desktop: host.docker.internal kullanın:

text MONGODB_URI=mongodb://host.docker.internal:27017/iqv_integration

Linux üretim: gerçek MongoDB host veya IP kullanın. Kurucu URI’yi host.docker.internal olarak yeniden yazmaz. Üretim compose extra_hosts bağımlılığı taşımaz.

text MONGODB_URI=mongodb://<MONGODB_HOST>:27017 MONGODB_DATABASE=champion

Loopback (localhost / 127.0.0.1 / ::1) fail-closed’dır (adres container’ın kendisidir).

External MongoDB modunda localhost / 127.0.0.1 / ::1 fail-closed'dır. Kurulum betikleri URI'yi gizlice yeniden yazmaz.

-WithMongoDB / --with-mongodb kullanıldığında API Compose DNS üzerinden mongodb://mongodb:27017 kullanır (host MongoDB URI'si değil).

MongoDB Ayrı Bir Servistir

Docker kurulum betiği harici MongoDB kurmaz veya yönetmez. Paketlenmiş MongoDB için açıkça -WithMongoDB / --with-mongodb kullanın.

İsteğe Bağlı Compose MongoDB Profili¶

Yerel MongoDB konteyneri ile geliştirme veya test için:

bash docker compose -f docker-compose.yml -f docker-compose.local.yml --profile local-db up --build -d

Warning

local-db profili yalnızca geliştirme içindir. Üretim dağıtımlarında müşterinin mevcut MongoDB servisini kullanın.

Konteyner Yönetimi¶

Durum¶

bash docker compose ps docker compose logs --tail=50

Durdurma¶

bash docker compose stop

Yeniden Başlatma¶

bash docker compose restart

Kaldırma¶

bash docker compose down

MongoDB Verileri

docker compose down MongoDB verilerini silmez (MongoDB ister sunucuda ister adlandırılmış birimli ayrı bir konteynerde çalışsın). Veritabanınız bozulmadan kalır.

Yeniden Oluşturma ve Güncelleme¶

Windows / lab (kaynak ağacı): docker compose up --build -d development yoludur.

Linux üretim: müşteri sunucusunda derleme yoktur. Yeni offline paketi aktarıp şunu çalıştırın:

bash sudo ./scripts/update.sh

Aynı image digest → NO-OP. Bkz. Güncelleme ve Geri Alma.

Güvenlik Duvarı Yapılandırması¶

Windows¶

powershell New-NetFirewallRule -DisplayName "IQV Integration API (Docker)" ` -Direction Inbound -Protocol TCP -LocalPort 8080 ` -Action Allow -Profile Domain,Private

Linux¶

bash sudo ufw allow 8080/tcp comment "IQV Integration API (Docker)"

Port Çakışmaları

Port 8080 sunucuda zaten kullanılıyorsa konteyner başlatılamaz. Compose dosyanızdaki port eşlemesini değiştirin veya çakışan işlemi durdurun.

Günlükleme¶

Konteyner günlüklerini görüntüleyin:

bash docker compose logs -f

Gizli bilgiler, belirteçler (token) ve kimlik bilgileri günlüklere asla yazılmaz.

Çıkış Kodları¶

Kod	Anlam
0	Başarı
1	Genel hata
2	Yapılandırma hatası
3	MongoDB bağlantı hatası
4	MongoDB kimlik doğrulama hatası
5	MongoDB zaman aşımı
6	Port zaten kullanımda
7	TLS sertifika hatası
8	İzin reddedildi
9	İkili dosya bulunamadı
10	Servis kayıt hatası
11	Sağlık kontrolü hatası
12	Yedekleme hatası
13	Geri yükleme hatası
14	Migrasyon hatası
15	Kirli depo (dirty repository)
16	Ağ hatası
17	Bilinmeyen hata

Sorun Giderme¶

DATABASE_UNAVAILABLE¶

Konteyner MongoDB'ye ulaşamıyor. Kontrol edin:

MongoDB sunucuda veya erişilebilir bir konteynerde çalışıyor.
MONGODB_URI doğru hostname kullanıyor (sunucu MongoDB için host.docker.internal, compose MongoDB için servis adı).
MongoDB kimlik doğrulama bilgileri geçerli.
Docker ağ yapılandırması konteynerin MongoDB portuna erişmesine izin veriyor.

Port Çakışması (Çıkış Kodu 6)¶

Sunucu portu zaten kullanımda. Kontrol edin:

```bash

Linux¶

sudo ss -tlnp | grep 8080

Windows¶

Get-NetTCPConnection -LocalPort 8080 | Select-Object OwningProcess ```

Migrasyon Hatası (Çıkış Kodu 14)¶

Veritabanı migrasyonu başarısız oldu. Otomatik olarak yeniden denemeyin. Konteyner günlüklerini inceleyin, sorunu düzeltin, ardından yeniden oluşturun veya geri alın. Bkz. Güncelleme ve Geri Alma.

Çevrimdışı Kurulum (Linux üretim)¶

Önerilen yol: CI’da derle ve paketle, ardından self-contained arşivden kur.

```bash

Development / CI (Go + Docker + kaynak var)¶

./scripts/release/build-docker-linux.sh ./scripts/release/package-docker-linux.sh ```

iqv-integration-api-<version>-linux-docker-amd64.tar.gz dosyasını Ubuntu sunucuya aktarın. SHA256 doğrulanır ve docker load çalışır. Git, Go, docker build, docker pull, curl/wget indirme veya apt yoktur.

Opsiyonel auto-update varsayılan kapalıdır; git pull değildir. Manuel offline güncelleme her zaman kullanılabilir.

Sağlık Kontrolleri¶

Dağıtım başarılı sayılmadan önce hem canlılık hem hazırlık kontrolleri geçmelidir:

Uç Nokta	Amaç
`GET /health/live`	İşlem hayatta
`GET /health/ready`	İşlem hayatta ve MongoDB erişilebilir

Kurulum betikleri her iki uç noktayı da otomatik olarak doğrular. Her iki kontrol de geçmedikçe başarı bildirmeyin.