Kurulum, güncelleme ve yedekleme

Bu sayfa Spitfire'ı Docker, Kubernetes ya da Windows (Docker Desktop) üzerine kurmayı, ilk yöneticiyi oluşturmayı, güncellemeyi, geri almayı, yedeklemeyi ve kaldırmayı anlatır. Uzak lokasyonlara runner kurmak ayrı bir konudur: Runner'lar ve lokasyonlar.

#Ne işe yarar

Kurulum betiği (install.sh, Windows'ta install.ps1) şunları tek komutla yapar:

• Sürümün kurulum paketini (install.sh, uninstall.sh, Compose/Kubernetes dosyaları; kaynak kod yok) spitfire.tr/download'dan indirir, SHA-256'sını doğrular ve ~/spitfire klasörüne açar.
• İmajı Docker Hub'dan çeker: algebransoft/spitfire:<VERSION> (public, amd64 + arm64). Go ve Node gerekmez.
• Postgres, controller (web arayüzü + API) ve runner'ları başlatır.
• Gizli anahtarları (SPITFIRE_SECRET_KEY, SPITFIRE_JWT_SECRET, kurulum kodu…) bir kez üretir ve sonraki her çalıştırmada aynen korur.
• Sonunda arayüz adresini ve ilk yönetici için kurulum kodunu basar.

Aynı komutu yeniden çalıştırmak güncellemedir.

#Ne zaman kullanılır

• İlk kurulumda.
• Yeni bir sürüm çıktığında (arayüzde mavi "Spitfire X çıktı" bandı).
• Controller'ın portunu, runner sayısını ya da proxy'sini değiştirmek istediğinizde (seçenekle yeniden çalıştırın).
• Bir güncelleme ters gittiğinde (--rollback).
• Destek ekibi bir destek paketi istediğinde ve arayüz açılmıyorsa (--support-bundle).

#Gereksinimler

Kurulum betiği eksik bir şey bulursa HATA: satırıyla durur ve altında bir Çözüm: satırı yazar; önce onu okuyun.

#Docker ile kurulum

1. Docker'ın çalıştığını doğrulayın: docker info hatasız dönmeli.

2. Kurulum komutunu çalıştırın:

   bashKopyala

   curl -fsSL https://spitfire.tr/install.sh | bash -s -- docker

   Bu, tek makineye Postgres + controller + 2 runner kurar. Başka bir sürüm için SPITFIRE_VERSION=0.5.3, başka bir klasör için SPITFIRE_DIR=/opt/spitfire yazın (ikisi de bash'ten önce):

   bashKopyala

   curl -fsSL https://spitfire.tr/install.sh | SPITFIRE_DIR=/opt/spitfire bash -s -- docker

3. Kurulum Kurulum tamamlandı. Tarayıcıda açın: http://... satırıyla biter. Hemen altındaki Kurulum kodu: XXXX-XXXX-XXXX satırını kopyalayın.

4. Adresi tarayıcıda açın ve İlk giriş ve kurulum kodu bölümüne geçin.

Varsayılan portlar: arayüz ve API 8470, uzak runner'lar için gRPC (TLS) 8471. Değiştirmek için:

~/spitfire/install.sh docker --port 8480 --grpc-port 8481 --runners 4

#Kubernetes ile kurulum

1. kubectl config current-context ile doğru cluster'da olduğunuzu kontrol edin.

2. Kurulum komutunu çalıştırın:

   bashKopyala

   curl -fsSL https://spitfire.tr/install.sh | bash -s -- kubernetes

   Varsayılan namespace spitfire, context aktif context'tir. Değiştirmek için --namespace NS ve --context C.

3. Arayüz varsayılan olarak NodePort 30470'te açılır (--node-port N ile değişir; --service-type LoadBalancer ya da ClusterIP da seçilebilir). Arayüz bu makineden NodePort ile açılamıyorsa kurulum arka planda bir kubectl port-forward başlatır (deploy/kubernetes/.port-forward.pid).

4. Kurulum kodunu çıktıdan kopyalayın ve adresi açın.

Kubernetes kurulumunun güvenlik ayarları: pod'lar root olmadan, salt okunur kök dosya sistemiyle, yetkisiz (capabilities yok) ve RuntimeDefault seccomp ile çalışır. NetworkPolicy'ler (CNI destekliyorsa) Postgres'e yalnız controller'ın, düz metin runner portuna (8475) yalnız bu kurulumun runner'larının erişmesine izin verir. Controller durdurulurken aktif koşuları durdurup sonuçlarını kaydeder (30 sn'ye kadar; pod'a 45 sn tanınır).

Sık kullanılan Kubernetes seçenekleri:

#Windows ile kurulum

1. Docker Desktop'ı başlatın.

2. PowerShell'de:

   powershellKopyala

   irm https://spitfire.tr/install.ps1 | iex

   Bu docker modunda kurar; paket %USERPROFILE%\spitfire klasörüne açılır ($env:SPITFIRE_DIR ile değişir, $env:SPITFIRE_VERSION ile sürüm seçilir).

3. Seçenek vermek için betiği bir scriptblock olarak çağırın:

   powershellKopyala

   & ([scriptblock]::Create((irm https://spitfire.tr/install.ps1))) docker -Port 8480 -GrpcPort 8481 -Runners 4

install.ps1 seçenekleri install.sh ile aynı anlamdadır: -Runners N, -Location AD, -Version V, -Image IMAGE, -AdminEmail/-AdminPassword, -Port N, -GrpcPort N, -GrpcPublicAddr H:P, -NoBackup, -Rollback, -SupportBundle, -Yes, -Help.

Docker'sız bir Windows sunucuda yalnızca runner kurmak istiyorsanız arayüzde Runner'lar → token penceresi → Windows sekmesindeki komutu kullanın: Runner'lar.

#Kurulum seçenekleri

~/spitfire/install.sh --help hepsini listeler. En sık kullanılanlar:

#İlk giriş ve kurulum kodu

İlk açılışta arayüz İlk admin'i oluşturun ekranını gösterir. Bu ekran yalnızca bir kez, henüz hiç kullanıcı yokken görünür.

İlk admin'i oluşturun ekranı: Kurulum kodu, Ad, E-posta, Parola ve Parola (tekrar) alanları

1. Kurulum kodu alanına kurulumun sonunda basılan XXXX-XXXX-XXXX kodunu yapıştırın.
2. Ad, E-posta ve Parola (en az 8 karakter) girin, Parola (tekrar) ile doğrulayın.
3. Admin'i oluştur ve giriş yap'a tıklayın.

Oluşan hesap kurulum yöneticisidir: lisans, kullanıcılar, SSO, sistem olayları gibi kurulum ayarları yalnızca bu roldedir. Kod ilk yöneticiyle birlikte geçersiz olur.

Kodu kaybettiyseniz (kod, ilk yönetici oluşana kadar geçerli kalır ve yeniden üretilmez):

• Docker: grep SPITFIRE_SETUP_CODE ~/spitfire/deploy/docker/.env

• Kubernetes: kubectl -n spitfire get secret spitfire-secrets -o jsonpath='{.data.SPITFIRE_SETUP_CODE}' | base64 -d

• Controller logunda setup_code= satırı:

  bashKopyala

  docker compose -p spitfire -f deploy/docker/docker-compose.yml logs controller | grep -i setup
  kubectl -n spitfire logs deploy/spitfire-controller | grep -i setup

• Kurulum komutunu yeniden çalıştırmak kodu tekrar gösterir (kod değişmez).

Kodu hiç kullanmadan ilk yöneticiyi kurulumda oluşturmak için: install.sh docker --admin-email admin@ornek.com --admin-password '...' (Windows: -AdminEmail/-AdminPassword).

Giriş yaptıktan sonraki adım genellikle lisanstır: Lisans.

#Güncelleme

#Yeni sürümü nasıl fark edersiniz

Controller günde bir kez spitfire.tr'ye yeni sürüm olup olmadığını sorar (yalnızca kendi sürümünü gönderir). Yeni sürüm varsa admin'ler her sayfanın üstünde Spitfire X çıktı bandını görür:

• Neler yeni, nasıl güncellenir? sürüm notlarını ve bu kuruluma uygun güncelleme komutunu açar (Linux/macOS Docker, Windows PowerShell, Kubernetes ve başka lokasyonlardaki runner sunucuları için ayrı ayrı).
• Bu sürüm için gizle bandı o sürüm için kapatır. Güvenlik güncellemesi bandı (kırmızı) gizlenmez; her ziyarette yeniden görünür.

Lisans sayfasındaki Sürüm ve güncellemeler kartı kurulu sürümü, kurulum türünü, son kontrolün sonucunu, Çıkış proxy'si'ni ve Güncelleme komutu'nu gösterir; Şimdi kontrol et beklemeden kontrol eder.

Lisans sayfasındaki Sürüm ve güncellemeler kartı: kurulu sürüm, kurulum türü, güncelleme kontrolü ve Şimdi kontrol et düğmesi

#Adım adım güncelleme

1. Süren bir koşu olmadığından emin olun (güncelleme controller'ı yeniden başlatır).

2. Controller'ın kurulu olduğu sunucuda kurulumdaki komutun aynısını çalıştırın:

   bashKopyala

   curl -fsSL https://spitfire.tr/install.sh | bash -s -- docker
   curl -fsSL https://spitfire.tr/install.sh | bash -s -- kubernetes --context C --namespace NS

   Windows'ta: irm https://spitfire.tr/install.ps1 | iex.

3. Betik son sürümün paketini aynı klasöre açar ve imajı çeker. Üretilen anahtarlar (deploy/docker/.env ya da spitfire-secrets Secret'ı) ve veriler korunur.

4. Sürüm değişiyorsa önce veritabanı ~/spitfire/backups/*.dump olarak yedeklenir (son 5 yedek tutulur; --no-backup atlar).

5. Başka lokasyonlardaki runner'ları da güncelleyin: Runner'lar → Runner güncelleme. Runner'lar sayfası controller'dan farklı sürümdeki runner'ları sarı eski sürüm etiketiyle işaretler.

#Geri alma (rollback)

Bir güncelleme ters giderse:

~/spitfire/install.sh docker --rollback          # Kubernetes: install.sh kubernetes --rollback

Windows'ta .\install.ps1 -Rollback. Betik önce şimdiki veritabanını yedekler, backups/ altındaki en yeni yedeği (ya da verdiğiniz dosyayı: --rollback backups/<dosya>.dump) geri yükler ve o yedeği alan sürüme döner. Yedekten sonra yapılan değişiklikler geri gelmez. Terminalsiz çalışırken --yes gerekir.

#Proxy arkasında kurulum

Kurumsal bir HTTPS proxy'si arkasındaysanız kurulum komutunu HTTPS_PROXY (ve gerekirse HTTP_PROXY, NO_PROXY) tanımlıyken çalıştırın:

export HTTPS_PROXY=http://proxy.ornek.com:3128
export NO_PROXY=.ornek.local
curl -fsSL https://spitfire.tr/install.sh | bash -s -- docker

Betik bu değerleri controller'a aktarır (Docker: deploy/docker/.env; Kubernetes: spitfire-proxy Secret'ı). Controller güncelleme kontrolünü, webhook'ları ve SSO çağrılarını bu proxy üzerinden yapar. Kurulumun kendi adları (localhost, postgres, controller…) NO_PROXY'ye kendiliğinden eklenir. İç ağdaki SSO sağlayıcınızın ya da webhook hedeflerinizin adlarını NO_PROXY'ye siz ekleyin. Sonraki bir çalıştırmada proxy vermezseniz önceki ayar korunur.

İnternetsiz bir kurulumda güncelleme kontrolünü kapatın: controller'da SPITFIRE_UPDATE_CHECK=off; sürüm notlarını spitfire.tr/surum-notlari'dan takip edin. Kendi aynanızı kullanıyorsanız SPITFIRE_UPDATE_FEED ile verin; aynada releases.json.sig dosyası da bulunmalıdır.

#Yedekleme ve SPITFIRE_SECRET_KEY

Spitfire'ın verileri Postgres'tedir; bağlantı secret'ları ise SPITFIRE_SECRET_KEY ile şifrelenir. İkisini birlikte yedekleyin:

1. Anahtarlar: Docker'da ~/spitfire/deploy/docker/.env dosyası, Kubernetes'te spitfire-secrets Secret'ı. Bu dosyayı güvenli bir yere (parola kasası gibi) kopyalayın.
2. Veritabanı: Güncellemeler sürüm değiştiğinde otomatik ~/spitfire/backups/*.dump alır; bu dosyalar pg_restore ile geri yüklenir. Düzenli yedek için bu klasörü ya da Postgres volume'ünü kendi yedekleme sisteminize ekleyin.

#Portlar ve ağ

Runner'lar controller'a dışarı doğru bağlanır; runner sunucusunda gelen port açmanız gerekmez.

Arayüzün önünde bir ters vekil (ingress, nginx) varsa, istemci adresi X-Forwarded-For'dan yalnız istek loopback'ten ya da özel ağdan geldiğinde alınır. Genel adresli bir vekili (bulut yük dengeleyici, Cloudflare) SPITFIRE_TRUSTED_PROXIES ile (virgülle ayrılmış CIDR'ler) tanıtın; aksi hâlde audit log ve giriş sınırları vekilin adresini görür.

Giriş denemeleri sınırlıdır: bir istemci adresi art arda 30 deneme yapabilir, sonra 2 sn'de bir; bir hesap 10 yanlış parolayı kabul eder, sonra dakikada bir. Çok kullanıcı tek bir proxy/NAT arkasındaysa ilk sınırı SPITFIRE_SIGNIN_BURST ile artırın.

#TLS ve runner pin temelleri

• 8471 portu her zaman TLS'tir. Controller ilk açılışta kendi kimliğini üretir ve veritabanında (SPITFIRE_SECRET_KEY ile şifreli) saklar.
• Uzak runner controller'ı bu anahtarın pin'i (sha256:…) ile doğrular. Pin ve hazır kurulum komutu Runner'lar sayfasındaki token penceresindedir. Bağlantı secret'ları bu hattan runner'lara gittiği için pin zorunludur.
• Kendi sertifikanızı kullanmak isterseniz controller'a SPITFIRE_GRPC_TLS_CERT ve SPITFIRE_GRPC_TLS_KEY verin; runner'lar o zaman pin yerine --tls (sistem CA'ları) ya da --ca <PEM dosyası> ile doğrular.
• Uzak runner'ların gördüğü controller adresi kurulumda --grpc-public-addr HOST:PORT ya da SPITFIRE_GRPC_PUBLIC_ADDR ile verilir.

Ayrıntılar: Runner'lar → TLS pin ve sertifikalar.

#Kaldırma

~/spitfire/uninstall.sh docker
~/spitfire/uninstall.sh kubernetes --context C --namespace NS
~/spitfire/uninstall.sh runner          # install.sh runner ile kurulan uzak runner'lar

Windows: .\uninstall.ps1 docker ya da .\uninstall.ps1 runner.

Varsayılan olarak veriler (Postgres volume'ü / PVC) ve üretilen anahtarlar (.env / spitfire-secrets) korunur; daha sonra install.sh her şeyi geri getirir. Her şeyi silmek için --purge (Windows: -Purge).

#Sık karşılaşılan sorunlar

Belirti: HATA: Docker daemon'una ulaşılamıyor. Neden: Docker çalışmıyor ya da kullanıcınız docker grubunda değil. Çözüm: Docker Desktop'ı başlatın ya da sudo systemctl start docker; kullanıcınızı docker grubuna ekleyip oturumu yenileyin.

Belirti: HATA: Docker Compose bulunamadı. Neden: Compose v2 eklentisi kurulu değil. Çözüm: Docker Compose v2 eklentisini kurun (https://docs.docker.com/compose/install/).

Belirti: HATA: Port 8470 başka bir uygulama tarafından kullanılıyor. Neden: Makinede o portu kullanan başka bir servis var. Çözüm: Başka port seçin: install.sh docker --port 8480 --grpc-port 8481.

Belirti: HATA: İmaj indirilemedi: algebransoft/spitfire:... Neden: Makine Docker Hub'a çıkamıyor ya da sürüm yanlış. Çözüm: docker pull ile internet erişimini deneyin; proxy arkasındaysanız Docker daemon'unun proxy ayarını yapın; sürüm numarasını kontrol edin.

Belirti: Kurulum ekranı "Kurulum kodu yanlış" diyor. Neden: Kod eksik kopyalandı ya da başka bir kurulumun kodu. Çözüm: Kodu .env dosyasından ya da controller logundan yeniden kopyalayın (İlk giriş ve kurulum kodu).

Belirti: Kurulum ekranı yerine giriş sayfası açılıyor; "Kurulum zaten tamamlanmış" yazıyor. Neden: İlk yönetici zaten oluşturulmuş (belki --admin-email ile). Çözüm: O hesapla giriş yapın. Parolası bilinmiyorsa sunucuda spitfire-controller reset-password kullanın: Kullanıcılar ve erişim.

Belirti: HATA: Controller 180 sn içinde hazır olmadı. Neden: Controller başlarken hata verdi (veritabanı, eksik ayar…). Çözüm: docker compose -p spitfire -f deploy/docker/docker-compose.yml logs -f controller ile logu okuyun; çözemezseniz ./install.sh --support-bundle ile destek paketi hazırlayın (Sorun giderme).

Belirti: Sürüm ve güncellemeler kartında Kontrol başarısız görünüyor. Neden: Controller spitfire.tr'ye ulaşamıyor. Çözüm: Proxy arkasındaysanız kurulum komutunu HTTPS_PROXY tanımlıyken yeniden çalıştırın; internetsiz kurulumda SPITFIRE_UPDATE_CHECK=off.

Belirti: Yeniden kurulumdan sonra kayıtlı bağlantılar çalışmıyor; secret'lar okunamıyor ya da Test başarısız oluyor. Neden: SPITFIRE_SECRET_KEY değişmiş (ör. .env silinip yeniden kurulmuş). Çözüm: Yedeklediğiniz .env'i geri koyup kurulumu yeniden çalıştırın; yedek yoksa secret'ları yeniden girin.

#İlgili sayfalar

• Başlarken
• Lisans
• Kullanıcılar ve erişim
• Runner'lar ve lokasyonlar
• Sorun giderme