✓ Yayında

On-Premise Kurulum Rehberi

Captivo'yu kendi sunucunuza kurmak için adım adım rehber. Docker kurulu bir Linux sunucu ile tüm süreç 30 dakikadan kısa sürer.

1. Önkoşullar

Sunucunuzda aşağıdakilerin kurulu olduğundan emin olun:

İşletim SistemiLinux x86_64 — Ubuntu 22.04+, Debian 12+, RHEL 9+ önerilir

RAMEn az 2 GB (üretim için 4 GB önerilir)

DiskEn az 10 GB (yedekler için 20 GB+ önerilir)

Docker Engine24+ — docker --version ile kontrol edin

Docker Compose v2docker compose version (tire değil boşluk; v1 desteklenmez)

opensslopenssl version ile kontrol edin

Docker hızlı kurulum (Ubuntu/Debian):

curl -fsSL https://get.docker.com | sh

Giriş (Inbound) Portları

Sunucuya dışarıdan gelen bağlantılar. NAS/gateway ve (varsa) syslog kaynağı bunlara erişebilmelidir.

Port	Protokol	Kullanım
3000	TCP	Yönetim paneli (TLS yokken HTTP)
80 / 443	TCP	TLS etkinleştirildiğinde Caddy
1812	UDP	RADIUS kimlik doğrulama (yalnızca NAS IP'lerinden)
1813	UDP	RADIUS accounting (yalnızca NAS IP'lerinden)
514	UDP/TCP	Syslog — yalnızca 5651 log modülü kullanılıyorsa (yalnızca gateway/NAS IP'lerinden)

Veritabanı portu (5432) dışarı açılmaz — yalnızca konteynerler arası dahili ağda erişilir.

Çıkış (Outbound) Kuralları

Bu entegrasyonları kullanacaksanız sunucudan dışarı giden bağlantılara izin verin. Kısıtlı (deny-all outbound) bir ağdaysanız yalnızca kullandığınız satırları açmanız yeterlidir.

Port	Hedef	Ne zaman gerekli
TCP 587 / 465	Posta sunucunuz (SMTP)	E-posta gönderimi (doğrulama, rapor, bildirim)
TCP 443	SMS sağlayıcı API'si	SMS ile misafir doğrulama
TCP 443	Webhook hedef adresleriniz	Webhook entegrasyonu kullanılıyorsa
TCP 443	PMS / otel sistemi (adrese göre)	Otel PMS entegrasyonu kullanılıyorsa
TCP 443	app.captivo.io	Lisans doğrulama (standart profil; air-gapped'de gerekmez)
TCP 80	*.kamusm.gov.tr	5651 KamuSM zaman damgası kullanılıyorsa
TCP 80 / 443	Let's Encrypt	TLS profili — sertifika alma/yenileme (bkz. §4)

Test/dahili kullanım için sabit bir LAN IP yeterlidir. Üretimde genel erişimli bir alan adı ve TLS önerilir (bkz. §4). Otel PMS entegrasyonu bugün Captivo'ya gelen webhook ile çalışır; PMS sunucusunun panelin adresine (3000 veya 80/443) erişebilmesi yeterlidir.

2. Kurulum (Tek Komut)

Önerilen kurulum yolu Docker Hub üzerinden çalışır: image'lar herkese açıktır, küçük bir dağıtım deposunu klonlar ve kurulum betiğini tek komutla çalıştırırsınız. İnternet erişimi olmayan ortamlar için §9'daki air-gapped (çevrimdışı) alternatifi kullanın.

2.1 Dağıtım Deposunu Klonlayın

Kaynak kodu içermeyen, yalnızca docker compose dosyası ve kurulum betiğini barındıran dağıtım paketi (captivo.io/onprem) tek komutla indirilir —install.sh betiği buradan gelir:

curl -fsSL https://captivo.io/onprem/captivo-onprem.tar.gz | tar xz
cd captivo-onprem

2.2 Kurulum Betiğini Çalıştırın

chmod +x onprem/install.sh
./onprem/install.sh

Betik, sunucu adresini kurulum sırasında sorar ve LAN IP'nizi otomatik önerir. Alan adı + otomatik HTTPS kullanacaksanız TLS bölümüne bakın.

Betik şunları yapar:

docker ve openssl bağımlılıklarını kontrol eder.
.env.onprem dosyasını oluşturur ve tüm sırları (POSTGRES_PASSWORD, AUTH_SECRET, DATA_ENCRYPTION_KEY vb.) openssl rand ile rastgele üretir.
docker compose pull ile herkese açık image'ları Docker Hub'dan indirir, ardından up -d ile başlatır.
migrator servisi veritabanı şemasını uygular.
Tamamlandığında panel adresini yazdırır.

Docker Hub Image'ları

Aşağıdaki image'lar herkese açıktır ve docker compose pull ile otomatik indirilir:

Image	Rol
captivoio/captivo-onprem	Yönetim paneli + captive portal (Next.js)
captivoio/captivo-radius	FreeRADIUS kimlik doğrulama / accounting
captivoio/captivo-logd	5651 log sunucusu (isteğe bağlı — bkz. §6)

İnternete kapalı (air-gapped) ortamlar için image'lar önceden bir .tar dosyasına paketlenip docker load ile aktarılabilir — bkz. §9 Çevrimdışı Kurulum.

Örnek çıktı:

✓ Sırlar üretildi (.env.onprem)

✓ Servisler başlatılıyor...

✔ Container captivo-postgres Started

✔ Container captivo-migrator Exited

✔ Container captivo-radius Started

✔ Container captivo-web Started

✓ Kurulum tamamlandı!

Panel: http://localhost:3000

ÖNEMLİ — DATA_ENCRYPTION_KEY: .env.onprem dosyasındaki DATA_ENCRYPTION_KEY, misafir MAC adresi ve diğer şifreli verilerin şifreleme anahtarıdır. Bu dosyayı sunucu dışında güvenli bir yerde (parola yöneticisi, şifreli USB vb.) mutlaka yedekleyin. Anahtar kaybolursa şifreli veriler kalıcı olarak okunamaz hale gelir.

2.3 Güncelleme

Yeni sürüme geçmek için — verileriniz ve .env.onprem korunur:

docker compose -f docker-compose.onprem.yml --env-file .env.onprem pull
docker compose -f docker-compose.onprem.yml --env-file .env.onprem up -d
docker image prune -f   # eski (etiketsiz) imaj katmanlarını temizle

Her güncelleme önceki imajları etiketsiz bırakır ve bunlar sürüm başına ~1-2 GB birikir; temizlenmezse disk zamanla dolar ve bir sonraki güncelleme yarıda kalabilir.docker image prune -f yalnızca etiketsiz katmanları siler — çalışan container'lara ve yeni çekilen imajlara dokunmaz.

migrator yeni şema değişikliklerini otomatik ve eklemeli uygular; veritabanı ile şifreler değişmez. Yıkıcı bir şema değişikliği (nadir) veri kaybını önlemek için güncellemeyi güvenle durdurur — bu durumda ilgili sürüm notundaki elle adımlar izlenir.

Güncelleme .env.onprem ve veritabanı volume'üne dokunmaz; şifreler tutarlı kalır. Yeni image'lar Docker Hub'dan çekilir, container'lar yeniden oluşturulur.

3. İlk Açılış — Kurulum Sihirbazı

Panel adresini (http://<sunucu-ip>:3000) ilk açtığınızda otomatik olarak /setup sihirbazına yönlendirilirsiniz. Sihirbaz 10 adımdan oluşur:

Yönetici Hesabı

Süper yönetici e-posta ve parola tanımı.

Kurum

Şirket/kurum adı, logo, dil tercihi.

Sunucu Adresi

Panelin misafirlere görüneceği kalıcı adres (e-posta linkleri + indirilen portal) — isteğe bağlı.

Portal Görünümü

Captive portal tasarımı (arka plan, renkler, başlık).

RADIUS

RADIUS shared secret ve NAS yapılandırması.

Giriş Yöntemleri

Sosyal giriş, SMS OTP, misafir formu seçenekleri.

SMS

SMS sağlayıcı seçimi (Netgsm, Twilio vb.) — isteğe bağlı.

SMTP

Giden e-posta sunucusu (bildirimler için) — isteğe bağlı.

Lisans

.lic dosyası yükleme veya 15 günlük deneme başlatma.

Tamamlandı

Kurulum özeti ve panele giriş.

SMS ve SMTP adımları isteğe bağlıdır; atlanabilir ve sonradan Ayarlar menüsünden yapılandırılabilir.

4. TLS / HTTPS (Üretim için Önerilir)

Varsayılan http://localhost:3000 yalnızca yerel test içindir. Üretimde HTTPS zorunludur.

4.1 Alan Adını Yapılandırın

.env.onprem dosyasını düzenleyin:

NEXTAUTH_URL=https://wifi.firma.com
SITE_DOMAIN=wifi.firma.com

4.2 Caddy'yi TLS Profiliyle Başlatın

docker compose -f docker-compose.onprem.yml \
  --profile tls \
  --env-file .env.onprem \
  up -d

Caddy, SITE_DOMAIN değişkenini kullanarak Caddyfile aracılığıyla captivo-web:3000'e ters proxy yapar ve Let's Encrypt'ten otomatik TLS sertifikası alır. Koşul: Alan adının DNS'i bu sunucunun genel IP'sine çözümlenmeli ve 80/443 portları dışarıdan erişilebilir olmalıdır.

4.3 Kurumsal CA ile TLS (Kapalı Ağ / İç FQDN)

Kapalı bir ağda iç alan adı (ör. captivo.acme.local) kullanıyorsanız Let's Encrypt uygulanamaz. Bunun yerine kurumunuzun kendi CA'sından (ör. AD CS) türettiğiniz bir sertifikayı Caddy'ye tanıtırsınız.

SAN alanı iç FQDN olan bir sunucu (server-auth) sertifikası üretin (kurumsal CA / AD CS). İki dosyaya ihtiyaç var: cert.pem(sunucu sertifikası + ara zincir) ve key.pem(parolasız özel anahtar). Bu iki dosyayı sunucuda onprem/certs/ dizinine koyun.
.env.onprem dosyasını düzenleyin:

SITE_DOMAIN=captivo.acme.local
CADDY_TLS_BLOCK=tls /certs/cert.pem /certs/key.pem

Ardından §4.2'deki --profile tlskomutuyla servisleri başlatın. (CADDY_TLS_BLOCKboş bırakılırsa Caddy otomatik ACME dener; tls internalyalnız test içindir — cihazlar güvenmez.)

Misafir cihazı uyarısı — kritik: Misafir BYOD cihazları iç CA'nıza güvenmez. Tarayıcılar sayfa-içi fetch/XHR çağrılarında sertifika doğrulamasını atlayamaz, bu yüzden misafir portal adresi bir iç-CA HTTPS FQDN'i olursa portal SMS/voucher istekleri sessizce başarısız olur. Çözüm — çift yüz: personel paneli kurumsal-CA'lı https://captivo.acme.local; misafir portalı ise Ayarlar → Sistem → Sunucu Adresi'nde düz HTTP LAN adresinde (http://LAN-IP:3000) kalır. İki yüz aynı kutuda paralel çalışır.

5. RADIUS — NAS Cihazınızı Bağlama

FreeRADIUS konteyneri otomatik olarak başlar ve UDP 1812/1813 portlarını dinler. NAS veya gateway cihazınızda şu ayarları yapın:

Ayar	Değer
RADIUS sunucu IP	Bu sunucunun LAN IP adresi
Kimlik doğrulama portu	1812 UDP
Accounting portu	1813 UDP
RADIUS yöntemi	PAP
Shared secret	Sihirbaz Adım 5'te üretilen veya Ayarlar → RADIUS'ta görüntülenen değer

NAS'ınızdaki “walled garden” veya “unauthenticated pass-through” listesine Captivo sunucusunun LAN IP'sini ekleyin — misafirlerin kimlik doğrulama öncesinde panele ulaşabilmesi gerekir.

Desteklenen NAS/gateway modelleri: pfSense, OPNsense, MikroTik, FortiGate, Cisco Meraki, UniFi, Ruijie ve PAP/CHAP destekleyen diğer cihazlar.

6. 5651 Log Sunucusu (İsteğe Bağlı)

captivo-logd servisi, güvenlik duvarınızdan gelen trafik loglarını (syslog) toplar, bunları RADIUS üzerinden misafir kimliğiyle eşleştirir, günlük olarak imzalar ve 5651 sayılı kanun gereği 2 yıl saklar; süre dolduğunda KVKK uyumu için otomatik siler. İsteğe bağlı bir modüldür — 5651 log yükümlülüğü olan kurulumlar için etkinleştirin.

6.1 Servisi Etkinleştirin

Log servisi 514 portunu (UDP/TCP) dinler. Güvenlik duvarınızın syslog çıktısını bu sunucuya yönlendirin:

Ayar	Değer
Syslog hedef adresi	<sunucu-ip>:514
Protokol	UDP veya TCP (514)
Kaynak cihazlar	pfSense, OPNsense, MikroTik, FortiGate, Cisco Meraki, UniFi, Ruijie

Güvenlik duvarı → sunucu yönünde 514 portunun erişilebilir olduğundan emin olun. Aksi halde loglar sunucuya ulaşmaz.

6.2 Panelde İnceleyin

Toplanan loglar yönetim panelinde Ayarlar → Log Sunucusu altında yönetilir:

•Kaynaklar — log gönderen güvenlik duvarlarını listeler
•Arama — eşleştirilmiş misafir kimliğiyle log sorgulama
•İmzalı arşiv — günlük imzalanmış log paketleri
•Doğrula — arşiv bütünlüğünü doğrulama
•Ayarlar — saklama süresi ve diğer parametreler

Loglar günlük olarak öz-imza ile imzalanır; nitelikli (TÜBİTAK KamuSM) zaman damgası entegrasyonu mevcuttur ve panelden yapılandırılır — hem test hem üretim KamuSM ortamı desteklenir.

2 yıllık ham log önemli disk alanı kaplayabilir. Saklama süresi Ayarlar → Log Sunucusu altından yapılandırılabilir — disk kapasitenizi buna göre planlayın.

7. Lisans

Kurulumdan sonra 15 günlük ücretsiz deneme otomatik başlar; deneme süresinde tüm özellikler aktiftir.

Lisans almak için (şu an ücretsiz — yalnızca kayıt amaçlı):

Web panelinde Ayarlar → Lisans sayfasına gidin ve Kurulum Kimliği'ni kopyalayın.
support@captivo.io adresine ad, soyad, kurum, kurulum kimliği ve e-posta bilgilerinizle bir e-posta gönderin. (Paneldeki “E-posta ile talep et” butonu bu e-postayı hazır doldurur.)
Size iletilen .lic dosyasını aynı sayfadan yükleyin; lisans bilgileri (geçerlilik tarihi, kota) ekranda görüntülenir.

Deneme veya lisans süresi dolduğunda sistem kademeli olarak kapanır: önce uyarı, ardından salt okunur mod (yeni misafir kaydı durur, mevcut veriler görünür), son olarak panel erişimi kısıtlanır.

Air-gapped ortamda lisans doğrulama için internet bağlantısı gerekmez.

8. Yedekleme

KRİTİK UYARI: .env.onprem dosyasını sunucu dışında güvenli bir yerde yedekleyin. İçindeki DATA_ENCRYPTION_KEY olmadan veritabanı yedeğindeki şifreli veriler (MAC adresleri vb.) kalıcı olarak okunamaz hale gelir.

Veritabanı Yedeği

onprem/backup.sh betiği PostgreSQL'den pg_dump alır, sıkıştırır ve saklar (7 gün rotasyon).

Manuel çalıştırma:

POSTGRES_USER=captivo BACKUP_DIR=/opt/captivo-backups \
  ./onprem/backup.sh

Cron ile otomatikleştirme (her gün 03:15):

15 3 * * * POSTGRES_USER=captivo BACKUP_DIR=/opt/captivo-backups \
  /opt/captivo-onprem/onprem/backup.sh >> /var/log/captivo-backup.log 2>&1

Sunucu arızasında yerel yedekler de kaybolur. Yedekleri S3, R2, NAS veya şifreli harici disk gibi ikincil bir konuma düzenli olarak kopyalayın.

Uygulama Zamanlanmış Görevleri (İsteğe Bağlı)

Bazı özellikler periyodik tetikleme ile çalışır: zamanlı raporlar, MAC beyaz-liste süre dolumu, KVKK/5651 saklama temizliği, oturum webhook'ları ve SMS anomali uyarısı. Bunları kullanacaksanız .env.onprem'e bir CRON_SECRET ekleyin (ör. openssl rand -hex 32), container'ı yeniden başlatın ve aşağıdaki cron satırlarını kurun:

# Oturum webhook'ları (session.started/ended) — accounting açıksa; dakikada bir
*/1 * * * *  curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/session-events       >> /var/log/captivo-cron.log 2>&1
# MAC beyaz-liste süre dolumu — saatte bir
10 * * * *   curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/mac-whitelist-expiry >> /var/log/captivo-cron.log 2>&1
# Zamanlı raporlar — saatte bir
0 * * * *    curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/scheduled-reports    >> /var/log/captivo-cron.log 2>&1
# KVKK/5651 saklama temizliği — günde bir
30 3 * * *   curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/kvkk-retention       >> /var/log/captivo-cron.log 2>&1
# SMS kullanım anomalisi — 15 dakikada bir
*/15 * * * * curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/sms-anomaly          >> /var/log/captivo-cron.log 2>&1

Bu görevler isteğe bağlıdır — yalnızca kullandığınız satırları ekleyin. (trial-expiry yalnız SaaS aboneliği içindir, on-prem'de gerekmez.)

9. Çevrimdışı (Air-Gapped) Kurulum

İnternete bağlı olmayan ağlar için Docker Hub'dan çekme yerine image'lar önceden bir .tar dosyasına paketlenip hedef sunucuya aktarılabilir. Bu, §2'deki Docker Hub yolunun çevrimdışı alternatifidir.

İnternetli makinede paket oluşturun

# Varsayılan: latest sürümü paketler
./scripts/onprem/build-offline-bundle.sh

# Belirli sürüm için:
./scripts/onprem/build-offline-bundle.sh 1.0.0

Oluşan dosya: captivo-onprem-1.0.0.tar (web + RADIUS + logd + postgres + caddy image'larını içerir)

Bu paketleme betiği satıcı dağıtım araçlarındadır; müşteri kurulum paketinde bulunmaz. İnternet erişimi olmayan kurulumlarda image .tar'ını satıcıdan temin edin — hedef makinede yalnızca aşağıdaki docker load+ install.sh adımları gerekir.

Hedef makinede yükleyin

# Image'ları Docker'a yükle
docker load -i captivo-onprem-1.0.0.tar

# Kurulum betiğini çalıştır (internet gerekmez)
./onprem/install.sh

Air-gapped ortamda Let's Encrypt sertifikası alınamaz. TLS için kurumsal CA sertifikanızı kullanın veya dahili ağda HTTP'yi tercih edin.

10. Sorun Giderme

Panel açılmıyor

•docker compose … ps — tüm konteynerler Up durumunda mı?
•migrator servisi başarıyla tamamlandı mı (Exited (0))?
•Güvenlik duvarınızda 3000. porta erişim açık mı?
•Loglar: docker compose … logs web

RADIUS bağlantı hatası (misafir giriş yapamıyor)

•NAS'ta RADIUS sunucu IP adresi doğru mu? (Bu sunucunun LAN IP'si)
•UDP 1812/1813 portlarına NAS'tan erişim var mı?
•Shared secret NAS'ta ve Captivo panelinde birebir aynı mı?
•captivo-radius konteyneri çalışıyor mu? (docker logs captivo-radius)

SMS gelmiyor

•Sihirbaz Adım 7'de SMS sağlayıcı bilgileri girildi mi?
•NAS walled garden listesinde bu sunucunun IP'si tanımlı mı?

E-posta bildirimleri gitmiyor

•Sihirbaz Adım 8'de SMTP ayarları yapılandırıldı mı?
•SMTP port ve şifre ayarlarını konteyner loglarından doğrulayın.

Genel log inceleme

# Tüm servis logları (son 50 satır)
docker compose -f docker-compose.onprem.yml \
  --env-file .env.onprem \
  logs --tail=50

# FreeRADIUS logları
docker logs captivo-radius

Sorularınız için destek ekibimizle iletişime geçin.

İletişime Geçin Şirket İçi sayfasına dön