Linux systemd Kurulumu¶
Üretim Önerisi
systemd, Linux üretim ortamları için önerilen yerel servis yöneticisidir. Docker ayrı bir dağıtım türüdür — konteyner tercih ediyorsanız Docker Kurulumu sayfasına bakın.
Doğrulama kanıtı
IMPLEMENTED = YES · AUTOMATED TESTED = YES.
Offline kurulum / reboot / NO-OP update: LIVE PASS.
Fonksiyonel inbound POST: BLOCKED / RETEST REQUIRED (üretilen rastgele aktör ObjectID mevcut kullanıcıya karşılık gelmedi).
Aktör/installer düzeltmesi: IMPLEMENTED / AUTOMATED TESTED / LIVE RETEST REQUIRED.
Bkz. Linux systemd E2E.
PRODUCTION KURULUM (önerilen)¶
- Offline prebuilt Linux amd64 paketi
- Go yok, kaynak derleme yok, git yok, internet yok
- Müşteri makinesinde Ubuntu/systemd ve mevcut MongoDB yeterlidir
GELİŞTİRME DERLEMESݶ
- Go + kaynak +
scripts/release/build-linux.sh/package-linux.sh - Yalnız development/CI makinesinde; production installer bu yolu çağırmaz
Ön Koşullar¶
- Ubuntu 20.04+ veya uyumlu systemd tabanlı Linux dağıtımı (64-bit)
- Bu sunucudan erişilebilir MongoDB 6.0+
bash,systemd/systemctl, coreutils (sha256sum,cp,install)sudo/ root yetkileri- Offline prebuilt release paketi
- İlk kurulumda MongoDB URI / veritabanı / port / public base URL (installer
config/.env.exampleüzerinden runtime env üretir) - Üretim sunucusunda Go, git veya internet gerekmez. Derleme development/CI makinesinde yapılır.
MongoDB Ayrı Bir Servistir
Kurulum betiği MongoDB kurmaz veya yönetmez. IQV Integration API'yi kurmadan önce MongoDB kurulu ve çalışır durumda olmalıdır. Kuruluşunuzun veritabanı operasyon dokümantasyonuna bakın.
Çalışma Zamanı Dizin Yapısı¶
Kurulum sonrasında servis şu yolları kullanır:
```text /opt/iqvizyon/iqv-integration-api/ bin/ # Uygulama ikili dosyası deployment/ # Dağıtım meta verileri
/etc/iqvizyon/iqv-integration-api.env # install.sh paket örneği + CLI ile oluşturur (update korur)
/var/log/iqvizyon/iqv-integration-api/ # Uygulama günlükleri
/var/lib/iqvizyon/iqv-integration-api/ backups/ # Güncelleme öncesi yedekler ```
Kurulum¶
1. Kurulum Betiğini Çalıştırın (açılmış offline paketten)¶
Installer config/.env.example okur ve /etc/iqvizyon/iqv-integration-api.env oluşturur (0640). Mevcut dosyanın üzerine yazılmaz. İsteğe bağlı --env-file PATH hâlâ kabul edilir.
bash
sudo ./scripts/install.sh \
--external-mongodb \
--mongo-uri "mongodb://DB_HOST:27017" \
--mongo-database "champion" \
--integration-actor-user-id "GERCEK_KULLANICI_OBJECT_ID" \
--port 4242 \
--public-base-url "http://API_HOST:4242"
Örnek (lab topolojisi):
bash
sudo ./scripts/install.sh \
--external-mongodb \
--mongo-uri "mongodb://<MONGODB_HOST>:27017" \
--mongo-database "champion" \
--integration-actor-user-id "GERCEK_KULLANICI_OBJECT_ID" \
--port 4242 \
--public-base-url "http://<API_HOST>:4242"
INTEGRATION_ACTOR_USER_ID, entegrasyonun denetim alanları için kullanacağı mevcut ve aktif MongoDB kullanıcısının ObjectID’sidir. Rastgele ObjectID değildir. Installer asla rastgele ID üretmez. İlk kurulumda --integration-actor-user-id zorunludur (24 karakter hexadecimal). --env-file geçerli bir aktör sağlayabilir; mevcut runtime env üzerine yazılmaz.
Go indirilmez, kaynak derlenmez, git/curl/wget gerekmez. MongoDB URI, secret ve aktör ObjectID loglanmaz.
Kurulum betiği şunları yapar:
- Root, systemd, mimari, ELF ve SHA256 doğrular.
- Production env oluşturur veya korur (değerler yazdırılmaz).
- Eksik/geçersiz aktör biçiminde deployment mutation başlamadan durur.
- Servis kullanıcısı ve dizinleri oluşturur.
- Mevcut kurulumu yedekler, env + prebuilt binary dağıtır.
- Salt okunur
iqv-integration-api checkçalıştırır (MongoDB ping + aktör var/aktif). - Migrasyon çalıştırır (
--skip-migrationdeğilse). - systemd birimini yazar, etkinleştirir ve başlatır.
/health/liveve/health/readydoğrular.- Deployment metadata yazar.
3. Doğrulama¶
bash
sudo systemctl status iqv-integration-api.service
Servis active (running) durumunda görünmelidir.
bash
curl -s http://localhost:8080/health/live
curl -s http://localhost:8080/health/ready
Kurulum başarılı sayılmadan önce her iki uç nokta da HTTP 200 döndürmelidir.
Servis Yönetimi¶
Durum¶
bash
sudo bash ./scripts/linux/service/status.sh
Veya doğrudan:
bash
sudo systemctl status iqv-integration-api.service
Güncelleme¶
bash
sudo bash ./scripts/linux/service/update.sh
Güncelleme betiği değişiklikleri uygulamadan önce /var/lib/iqvizyon/iqv-integration-api/backups/ altında bir yedek oluşturur. Tam güncelleme prosedürü için Güncelleme ve Geri Alma sayfasına bakın.
Kaldırma¶
bash
sudo bash ./scripts/linux/service/uninstall.sh
MongoDB Verileri
Kaldırma betiği MongoDB verilerini asla silmez. Servis kaldırıldıktan sonra veritabanınız bozulmadan kalır.
İkili Servis Komutları¶
İkili dosyanın kendisi servis yaşam döngüsü komutlarını destekler:
bash
./iqv-integration-api service install --env-file /etc/iqvizyon/iqv-integration-api.env
./iqv-integration-api service uninstall
./iqv-integration-api service start
./iqv-integration-api service stop
./iqv-integration-api service restart
./iqv-integration-api service status
./iqv-integration-api service run --env-file /etc/iqvizyon/iqv-integration-api.env
--env-file bayrağı servise ortam yapılandırmasını nereden yükleyeceğini bildirir.
Güvenlik Duvarı Yapılandırması¶
ufw ile API portunu (varsayılan 8080) açın:
bash
sudo ufw allow 8080/tcp comment "IQV Integration API"
Veya iptables ile:
bash
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
Port Çakışmaları
Port 8080 zaten kullanılıyorsa servis başlatılamaz. Ortam dosyanızdaki portu değiştirin veya çakışan işlemi durdurun.
Günlükleme¶
Uygulama slog çıktısı süreç stdout’udur. systemd bunu journal’a yazar. /var/log/iqvizyon/iqv-integration-api birimde yazılabilir yoldur; Go süreci uygulama log dosyasını oraya yazmaz. Journal:
bash
sudo journalctl -u iqv-integration-api.service -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¶
Uygulama MongoDB'ye ulaşamıyor. Kontrol edin:
- MongoDB servisi çalışıyor:
sudo systemctl status mongod. - Ortam dosyasındaki
MONGODB_URIdoğru ve bu sunucudan erişilebilir. - MongoDB kimlik doğrulama bilgileri geçerli.
- Güvenlik duvarı MongoDB portuna giden bağlantılara izin veriyor.
Port Çakışması (Çıkış Kodu 6)¶
Yapılandırılmış portu başka bir işlem kullanıyor. Bulun:
bash
sudo ss -tlnp | grep 8080
Migrasyon Hatası (Çıkış Kodu 14)¶
Veritabanı migrasyonu başarısız oldu. Otomatik olarak yeniden denemeyin. Migrasyon günlüklerini inceleyin, sorunu düzeltin, ardından yeniden deneyin veya geri alın. Bkz. Güncelleme ve Geri Alma.
Kirli Depo (Çıkış Kodu 15)¶
Gelen binary SHA256SUMS ile uyuşmuyorsa kurulum durur ve mevcut çalışma kurulumu değiştirilmez. Production Linux native yolu git pull kullanmaz.
Çevrimdışı Kurulum¶
İnternet erişimi olmayan ortamlar için:
- Sürüm arşivini internet erişimi olan bir makinede indirin.
- Arşivi güvenli bir ortam aracılığıyla hedef sunucuya aktarın (USB, yerel ağ üzerinden SCP).
- Arşivi çıkartın ve kurulum betiğini yukarıda belgelendiği şekilde çalıştırın.
- MongoDB'nin hedef sunucudan erişilebilir olduğundan emin olun.
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 ve güncelleme betikleri her iki uç noktayı da otomatik olarak doğrular. Her iki kontrol de geçmedikçe başarı bildirmeyin.