Installing with Docker Compose

Kurumun kendi sunucusunda, tek bir kurum (tek tenant) için tek sunucu kurulumu. Postgres, Valkey ve Keycloak pakete dahildir. Katalog, video ve eğitim paketleri platform konsolundan gelir; kursiyerlerin kişisel verisi kurumun sunucusunda kalır.

Dosya	Ne yapar
compose.yaml	Servisler: postgres, valkey, keycloak, training-api, training-web
.env.example	Ayarlar: sürüm, adresler, kurum, konsol kimlik bilgileri, parolalar, anahtarlar

İmajlar (training-api, training-web, keycloak) aynı sürüm numarasını taşır (FLEET_VERSION).

Gereksinimler

• Linux sunucu, en az 2 çekirdek, 4 GB bellek, 20 GB disk
• Docker Engine ve Docker Compose 2.23 ya da üstü
• TLS sertifikası olan bir ters vekil sunucu (nginx, Traefik, Caddy ya da yük dengeleyici) ve üç DNS adı
• Dışarıya çıkış: izin listesi. Tamamen internetsiz kurulum desteklenmez: katalog, lisans ve paketler konsoldan, videolar Cloudflare’den gelir.

Kurulum

1. Bu klasörü sunucuya kopyalayın ve ayarları doldurun:

   cp .env.example .env
   chmod 600 .env

   Sürüm, imaj deposu ve konsol değerleri (FLEET_*, CONSOLE_*) kurulum kaydıyla birlikte verilir. Parolalar ve anahtarlar kurulumda bir kez üretilir (dosyadaki açıklamalar). .env’i ve veritabanı yedeklerini birlikte saklayın: TRAINING_CRYPTO_SECRET_KEY olmadan şifreli alanlar okunamaz.

2. Ters vekil sunucuda üç adı yayınlayın (BIND_IP varsayılanı 127.0.0.1):

   Ad	Hedef	Not
   PANEL_HOST	http://127.0.0.1:8080	Eğitim paneli
   API_HOST	http://127.0.0.1:8081	training-api (panel ve mobil uygulama)
   AUTH_HOST	http://127.0.0.1:8180	Keycloak; X-Forwarded-* başlıkları iletilmeli

   AUTH_HOST için /admin yolunu yalnızca kurumun ağından açmanız önerilir.

3. İmaj deposuna konsol kimlik bilgisiyle bir kez giriş yapın, sonra açın. Ayrı bir depo hesabı yoktur: kullanıcı adı CONSOLE_CLIENT_ID, parola CONSOLE_CLIENT_SECRET. Depo lisans geçerliyken çekmeye izin verir; lisans biterse yeni sürüm çekilemez, çalışan sistem durmaz.

   # parola sorulunca CONSOLE_CLIENT_SECRET
   docker login egitim-registry.xenopsoftware.com -u <CONSOLE_CLIENT_ID>
   docker compose pull
   docker compose up -d

   İlk açılışta Keycloak fleet realm’ini kurar, training-api veritabanını oluşturur ve kurumun tenant’ını (TENANT_SLUG) ilk yöneticisiyle (TENANT_ADMIN_EMAIL) açar. Durum:

   docker compose ps
   curl -fsS http://127.0.0.1:8081/actuator/health/readiness

4. https://PANEL_HOST adresinde ilk yöneticiyle (TENANT_ADMIN_EMAIL, TENANT_ADMIN_PASSWORD) girin; parola ilk girişte değiştirilir. TENANT_ADMIN_PASSWORD artık kullanılmaz, .env’den silebilirsiniz.

TENANT_SLUG sonradan değiştirilemez; değiştirilirse training-api ikinci bir tenant açmak yerine açılmayı reddeder.

Çıkış adresleri

Kurumun güvenlik duvarında açılması gerekenler (HTTPS, 443). Bunların dışında çıkış gerekmez.

Kaynak	Hedef	Ne için
Sunucu	CONSOLE_URL ve CONSOLE_TOKEN_URI’deki adlar	Katalog, lisans, heartbeat, paketler
Sunucu	FLEET_REGISTRY’deki ad (egitim-registry.xenopsoftware.com)	İmajlar; arşivle kurulumda gerekmez
Sunucu	Kurumun SMTP sunucusu, kimlik sistemi, OTLP	Yalnızca ayarlandıysa
Kursiyer cihazları	PANEL_HOST, API_HOST, AUTH_HOST	Panel, API ve giriş
Kursiyer cihazları	*.cloudflarestream.com, videodelivery.net	Video oynatma
Mobil uygulama	CONSOLE_URL’deki ad	Firma koduyla sunucu keşfi

Kapalı ağ

Sunucu imaj deposuna çıkamıyorsa sürümün release’indeki fleet-egitim-<sürüm>-images.tar.gz kullanılır. Arşivde compose.yaml’daki bütün imajlar (postgres ve valkey dahil, linux/amd64) vardır ve compose’un beklediği adlarla yüklenir. Arşivi internete çıkabilen bir makinede indirip doğrulayın, sonra sunucuya taşıyın:

cosign verify-blob --key cosign.pub --bundle SHA256SUMS.bundle SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

Sunucuda:

docker load -i fleet-egitim-<sürüm>-images.tar.gz
docker compose up -d

docker compose pull çalıştırmayın. .env’deki FLEET_REGISTRY ve FLEET_VERSION release’teki env.example’daki gibi kalmalı, imajlar o adlarla yüklenir. Güncelleme aynı yoldan yapılır: yedek, yeni arşivin docker load’u, FLEET_VERSION, docker compose up -d.

Kimlik sistemi ve e-posta

• Kurumun kimlik sistemi (Active Directory, Entra ID, OIDC/SAML) Keycloak’a bağlanır: Kimlik sistemini bağlama. Keycloak yönetim konsolu: https://AUTH_HOST/admin, kullanıcı admin, parola KEYCLOAK_ADMIN_PASSWORD.
• Davet e-postaları Keycloak’un SMTP’siyle gider: yönetim konsolunda fleet → Realm settings → Email altında kurumun SMTP sunucusunu girin, sonra .env’de INVITE_MODE=email yapıp docker compose up -d çalıştırın. SMTP yoksa davette geçici parola panelde gösterilir.

Yedek

Yedek iki veritabanıdır (training, keycloak) ve .env’dir. Paket önbelleği (training_tmp) yedeklenmez; konsoldan yeniden çekilir.

docker compose exec -T postgres pg_dump -U postgres -Fc training > training-$(date +%F).dump
docker compose exec -T postgres pg_dump -U postgres -Fc keycloak > keycloak-$(date +%F).dump

Güncelleme

Güncellemeyi kurum başlatır; otomatik güncelleme yoktur.

1. Yedek alın (yukarıda). Migration’lar yalnızca ileri yönlüdür; geri dönüş yedekten yapılır.

2. .env’de FLEET_VERSION’ı yeni sürüme çekin.

3. Açın:

   docker compose pull
   docker compose up -d

Aynı ana sürüm içinde en fazla bir minör sürüm atlanabilir (1.2 → 1.4 olur, 1.2 → 1.5 olmaz); LTS’ten bir sonraki LTS’e doğrudan geçilebilir. Desteklenmeyen bir geçişte training-api veritabanına dokunmadan durur ve önce hangi sürüme geçileceğini loglar (docker compose logs training-api).

İmza doğrulama

İmajlar cosign ile imzalıdır ve SBOM’ları (SPDX) imaja eklidir. Sürümün cosign.pub ve images.txt dosyalarıyla:

cosign verify --key cosign.pub <imaj>@<digest>
cosign verify-attestation --key cosign.pub --type spdxjson <imaj>@<digest>

İnternetsiz ağda --insecure-ignore-tlog=true ekleyin (şeffaflık kaydına erişilemez, yalnızca anahtar doğrulanır).

Geri dönüş

Eski imajı yeni şemayla açmak desteklenmez; training-api açılmayı reddeder. Geri dönmek için:

docker compose stop training-api keycloak
docker compose exec -T postgres dropdb -U postgres training
docker compose exec -T postgres createdb -U postgres -O training_app training
docker compose exec -T postgres pg_restore -U postgres -d training --no-owner --role=training_app < training-<tarih>.dump
# keycloak veritabanı da aynı şekilde (sahibi keycloak)
# .env'de FLEET_VERSION'ı önceki sürüme alın
docker compose up -d