Helm ile kurulum

Bu sayfa Gereksinimler sayfasındaki her şeyin hazır olduğunu varsayar: bir Kubernetes kümesi, ingress-nginx, cert-manager ve bir veritabanı kararı.

Örneklerdeki hostname’ler (panel.ornek.com gibi) yer tutucudur. Kendi adreslerinizle değiştirin.

1. Chart’ı edinin

git clone https://github.com/shftco/flowdesk-kubernetes.git
cd flowdesk-kubernetes

2. Ad alanını oluşturun

kubectl create namespace flowdesk

3. Üç secret’ı hazırlayın (out-of-band)

Chart hiçbir gerçek credential’ı kendi şablonlarına gömmez: bu üç secret chart dışında, sizin tarafınızdan oluşturulur.

a) JWT anahtar çifti

API, oturum jetonlarını bu çiftle imzalar/doğrular. Kaybı tüm oturumları düşürür.

openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private.pem -pubout -out public.pem
kubectl -n flowdesk create secret generic flowdesk-jwt \
  --from-file=private.pem --from-file=public.pem

b) GHCR imaj çekme secret’ı

ghcr.io/shftco/flowdesk-{api,web,tracker} imajları özeldir (private). SHFT size özel bir erişim jetonu (personal access token) verir; bu jetonu bir GitHub kullanıcı adıyla birlikte aşağıdaki secret’a girerek imajları çekersiniz:

kubectl -n flowdesk create secret docker-registry ghcr-pull \
  --docker-server=ghcr.io \
  --docker-username=<github-kullanici-adi> \
  --docker-password=<read:packages-yetkili-PAT> \
  --docker-email=<sizin-e-postaniz>

c) Uygulama secret’ı

Veritabanı, mesaj kuyruğu, token şifreleme anahtarı, Keycloak client secret’ı ve lisans anahtarı: hepsi flowdesk-secret içinde. Anahtar adları veritabanı/mesajlaşma seçiminize göre değişir; aşağıdaki örnek PostgreSQL + RabbitMQ + Keycloak için:

kubectl -n flowdesk create secret generic flowdesk-secret \
  --from-literal=POSTGRES_PASSWORD='<güçlü-bir-parola>' \
  --from-literal=CONNECTION_STRING='Host=postgres;Port=5432;Database=flowdesk;Username=flowdesk;Password=<güçlü-bir-parola>;Search Path=dbo' \
  --from-literal=RABBITMQ_USER='<rabbitmq-kullanici>' \
  --from-literal=RABBITMQ_PASS='<rabbitmq-parola>' \
  --from-literal=TOKEN_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
  --from-literal=KEYCLOAK_CLIENT_SECRET='<keycloak-client-secret>' \
  --from-literal=License__Key='<SHFT-den-aldiginiz-lisans-anahtari>'

Notlar:

Chart varsayılan olarak kendi PostgreSQL’ini kümenize kurar (postgres.enabled: true, demo/tek-replika kalitesinde). Yukarıdaki CONNECTION_STRING örneği (Host=postgres) bunu varsayar. SQL Server kullanacaksanız ya da kendi yönetilen veritabanınızı göstereceğiniz bir PostgreSQL’iniz varsa values.yaml’da postgres.enabled: false yapıp CONNECTION_STRING’i kendi sunucunuza göre yazın; biçimi için bkz. Yapılandırma. Aynı mantık redis.enabled ve rabbitmq.enabled için de geçerlidir.
CONNECTION_STRING’deki parola POSTGRES_PASSWORD ile birebir aynı olmalı. SQL Server kullanıyorsanız bağlantı dizesinin biçimi farklıdır; bkz. Yapılandırma.
Kafka kullanıyorsanız RABBITMQ_USER/RABBITMQ_PASS yerine KAFKA_SASL_PASSWORD girin (SASL kullanmıyorsanız o da gerekmez).
Application:Environment=Production iken guest/guest RabbitMQ credential’ı API tarafından reddedilir. Gerçek bir kullanıcı/parola verin.
License__Key olmadan da kurulum çalışır (lisanssız, sınırsız, “beklemede” durumunda). Anahtarı elinizde yoksa bu satırı atlayabilirsiniz. Ayrıntı: Yapılandırma.

4. `values.yaml`’ı kendi kurulumunuza göre ayarlayın

En az aşağıdakileri kendi değerlerinizle değiştiren bir my-values.yaml yazın:

api:
  image:
    tag: <api-sürümü> # bkz. Sürüm Notları, çalıştıracağınız API sürümü
web:
  image:
    tag: <dashboard-sürümü>
tracker:
  image:
    tag: <tracker-sürümü>

database:
  provider: PostgreSql # veya SqlServer

ingress:
  clusterIssuer: letsencrypt-prod
  hosts:
    dashboard: panel.ornek.com
    api: api.ornek.com
    tracker: takip.ornek.com

auth:
  authority: 'https://<keycloak-sunucunuz>/realms/<realm>'
  clientId: flowdesk-web
  redirectUris:
    - 'https://panel.ornek.com/api/auth/callback/keycloak'

secrets:
  existingSecret: flowdesk-secret # 3.c adımında oluşturduğunuz secret

İmaj etiketlerini pinleyin: boş bırakırsanız chart’ın appVersion’ına düşer, bu da beklemediğiniz bir sürümü çalıştırmanıza yol açabilir. Hangi etiketlerin mevcut olduğunu Sürüm Notları sayfasından ve ilgili deponun GitHub Releases sayfasından görebilirsiniz.

5. Kurun

helm upgrade --install flowdesk ./charts/flowdesk \
  -n flowdesk --create-namespace \
  -f my-values.yaml

kubectl -n flowdesk get pods -w

İlk açılışta API veritabanı şemasını kendisi oluşturur ve yönetici kullanıcıyı tohumlar (admin@shft.co). Bu birkaç dakika sürebilir. startupProbe bu ilk açılışa yaklaşık 5 dakika tolerans tanır; bu sürede pod’un Ready görünmemesi normaldir.

6. Doğrulayın

# Deployment'ların ayağa kalktığını doğrulayın
kubectl -n flowdesk rollout status deploy/flowdesk-api
kubectl -n flowdesk rollout status deploy/flowdesk-web
kubectl -n flowdesk rollout status deploy/flowdesk-tracker

# Sertifikaların çıktığını ve hostname'lerin doğru olduğunu doğrulayın
kubectl -n flowdesk get ingress

# API sağlık kontrolü, 200 dönmeli
curl -s -o /dev/null -w '%{http_code}\n' https://api.ornek.com/health

/health 200 dönüyorsa, panel adresiniz açılıp Keycloak (veya seçtiğiniz sağlayıcı) üzerinden oturum açılabiliyorsa ve takip adresiniz açılıyorsa kurulum tamamlanmıştır.

Yükseltme ve geri alma

Yükseltmeden önce

Değiştireceğiniz her image tag’i için ilgili bileşenin notlarını okuyun: Sürüm Notları. FlowDesk dört bileşenden oluşur (API, Dashboard, Tracker, Knowledge Base) ve her biri kendi sürümünü bağımsız izler; yalnızca API’nin notlarına bakmak yeterli değildir.
### Changed ve ### Removed başlıklarındaki maddelere, bir yapılandırma anahtarından bahseden maddelere ve bir migration’dan bahseden maddelere dikkat edin.
Notlarda bir migration geçiyorsa bir bakım penceresi planlayın: şema migration’ları API açılışında otomatik uygulanır ve sıfır kesintili olması garanti değildir. Rolling update sırasında eski sürümü çalıştıran bir pod yeni şemayla uyumsuz kalıp hata dönebilir.
Veritabanı yedeği alın; aşağıdaki “Geri alma neyi kapsar” bölümüne bakın.

helm upgrade flowdesk ./charts/flowdesk -n flowdesk -f my-values.yaml \
  --set api.image.tag=v0.1.2
kubectl -n flowdesk rollout status deploy/flowdesk-api
kubectl -n flowdesk rollout undo deploy/flowdesk-api   # gerekirse geri alma

Üç bileşeni (API, Dashboard, Tracker) birlikte yükseltin, sürüm etiketleri SHFT tarafından birbiriyle uyumlu olarak verilir.

Geri alma neyi kapsar, neyi kapsamaz

kubectl rollout undo yalnızca pod’un çalıştırdığı imajı bir önceki sürüme döndürür, veritabanı şemasını geri almaz. Migration’lar API açılışında otomatik ve yalnızca ileri yönde uygulanır; olağan işleyişte bir geri alma (down) migration’ı çalıştırılmaz. Bir şema migration’ı (ör. bir tablonun yeniden adlandırılması) çalıştıktan sonra eski imaja dönerseniz, eski kod artık var olmayan bir tablo veya kolon adını sorgulamaya devam eder ve hata almayı sürdürürsünüz: rollout undo yalnızca migration içermeyen bir sürüme dönerken güvenlidir. Migration içeren bir yükseltme sorun çıkardıysa tek güvenli yol, yükseltmeden önce aldığınız veritabanı yedeğinden geri yüklemektir.

Sırada ne var

Kurulum ayakta; şimdi Yapılandırma sayfasından kimlik doğrulama, lisans ve ortam ayarlarını, E-posta ayarları sayfasından da giden/gelen postayı tamamlayın.