All-in-One Docker Kurulumu
Bu sayfa Apinizer'ın çekirdek modüllerinin Docker üzerinde kurulumunu tek yerde gösterir. Sıra önemli: önce Manager (kayıt + Environment), sonra Cache, sonra Worker. Integration sadece task-flow scheduler kullanılacaksa kurulur. API Portal ayrı bir sayfada kurulur — Manager kurulumundan sonra yapılır.
- Genel Bakış
- 1. API Manager
- 2. API Worker
- 3. API Cache
- 4. API Integration (Opsiyonel)
Apinizer Docker Hub üzerinde resmi imaj olarak yayınlanır. İmajlar Eclipse Temurin 25 üzerine kuruludur; entrypoint container memory limit'ini okuyup heap / direct memory / metaspace değerlerini otomatik ayarlar.
Hassas değerler (MongoDB URI, secret'lar) Docker akışında plaintext environment variable olarak gönderilir — konteyner, Linux paketindeki boot-time ENC(...) decrypt sürecini çalıştırmaz. Güvenli aktarım için Docker Secret (Compose / Swarm) veya Kubernetes Secret kullanın.
Tüm modülleri tek docker-compose.yml ile birlikte ayağa kaldırmak istiyorsanız:
5 modülün hep birlikte tek docker-compose.yml ile kurulduğu referans örnek
Önerilen Kurulum Sırası
- MongoDB (önceden kurulu olmalı — bkz. MongoDB Kurulumu)
- API Manager → MongoDB ile bağlantı doğrulanır, Mongock migration'ları çalışır
- Worker → Manager'da oluşturulan Environment bilgisini MongoDB'den okur
- Cache → Hazelcast cluster (Worker quota/OIDC/CB kullanacaksa)
- Integration (opsiyonel) → Quartz scheduler ayağa kalkar, Manager'a register edilir
- API Portal → Manager REST API'sine bağlanır, dokümantasyonu sunar
İmaj Konvansiyonu
Tüm imajlar apinizercloud/<modul> altında yayınlanır:
| Modül | İmaj |
|---|---|
| API Manager | apinizercloud/apimanager |
| API Portal | apinizercloud/apiportal |
| Worker | apinizercloud/worker |
| Cache | apinizercloud/cache |
| Integration | apinizercloud/integration |
Tag konvansiyonu
| Tag | Kanal | Not |
|---|---|---|
<MAJOR.MINOR.PATCH> (örn. 2026.04.5) | release | Production'a yükseltilebilir |
<MAJOR.MINOR.PATCH>.qa.<N> (örn. 2026.04.5.qa.1) | QA | Pre-release, değişebilir |
<MAJOR.MINOR.PATCH>-rc.<id> | release candidate | Donmuş, immutable |
<MAJOR.MINOR.PATCH>-SNAPSHOT | develop | Yuvarlanan, prod'da kullanmayın |
latest tag'i yayınlanmaz — daima açık bir versiyon tag'ine pin'leyin.
Apple Silicon (M1/M2/M3/M4) Üzerinde
İmajlar şu an yalnızca linux/amd64 için yayınlanır. Apple Silicon Mac'lerde Docker Desktop uyarı verir ("Image may have poor performance, or fail, if run via emulation"). Çözüm:
- Docker Desktop → Settings → General → "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" seçeneğini açın. QEMU yerine Apple Rosetta ile çalışır, performans büyük oranda artar.
- Üretim için x86_64 Linux host kullanın.
Ortak Gereksinimler
Tüm modüller aynı MongoDB veritabanına bağlanır
Hangi modülün hangi portu kullandığını gösteren tablo
Güncelleme
Docker üzerinde güncelleme için: Docker Üzerinde Güncelleme
API Manager, Apinizer'ın yönetim düzlemidir: REST API, iş mantığı, Angular UI ve MongoDB üzerinde proxy/policy/environment kayıtlarını barındırır. Bu modülün başarıyla ayağa kalkması ve UI'da en az bir Environment tanımlanması, sonraki adımların (Cache, Worker) ön koşuludur.
Bu rehber Apinizer API Manager Docker imajının bir Linux host üzerinde nasıl çalıştırılacağını anlatır. İmaj uygulamayı, bağımlılıklarını ve OpenJDK 25 runtime'ını içinde taşır — host üzerinde Java gerekmez. Entrypoint, başlangıçta konteyner memory limit'ini okur ve heap / direct memory / metaspace değerlerini otomatik olarak seçer.
Hassas değerler (MongoDB URI, secret'lar) Docker akışında plaintext environment variable olarak gönderilir — konteyner Linux paketinde kullanılan boot-time ENC(...) decrypt sürecini çalıştırmaz. Güvenli aktarım için Docker Secret (Compose / Swarm) veya Kubernetes Secret kullanın.
Gereksinimler
- Docker Engine 24+ kurulu bir Linux x86-64 host (veya Docker Desktop)
docker.io(veyaapinizercloud/apimanagerimajını barındıran bir mirror) erişimi- Erişilebilir bir MongoDB (üretim için replica set önerilir)
- Manager'ı dışarı açacak boş bir TCP port (varsayılan
8080)
1. İmajı çekin
VERSION=<APINIZER_VERSION>
docker pull apinizercloud/apimanager:${VERSION}
Tag konvansiyonu için: Docker — Genel Bakış.
2. Yapılandırma
Zorunlu environment variable'lar (imaj bunları başlamadan önce denetlemez; eksik ya da yanlış değer docker logs içinde MongoDB bağlantı hatası olarak görünür):
| Değişken | A çıklama |
|---|---|
SPRING_DATA_MONGODB_URI | MongoDB connection string (örn. mongodb://user:pass@host:25080/?replicaSet=rs0&authSource=admin) |
SPRING_DATA_MONGODB_DATABASE | Veritabanı adı (örn. apinizer) |
SPRING_PROFILES_ACTIVE | prod (varsayılan — üretimde böyle kalsın) |
Opsiyonel:
| Değişken | Varsayılan | Açıklama |
|---|---|---|
SERVER_PORT | 8080 | Konteyner içi HTTP portu |
JAVA_OPTS | boş | Ek JVM bayrakları (tier varsayılanları ile birleşir) |
jvmOverride | false | true yapıldığında JAVA_OPTS tier varsayılanlarını ezer |
APIMANAGER_TIMEZONE | boş | Manager saat dilimi (IANA, örn. Europe/Istanbul); boşsa container saat dilimi |
APINIZER_CLIENT_SECRET_KEK | boş | API istemci secret'ları için kuruluma özel kurtarma anahtarı (KEK): Base64, tam 32 byte. Tüm Manager'larda aynı olmalı ve yedeklenmeli; bkz. Kubernetes kurulumu |
APINIZER_CLIENT_SECRET_KEK_VERSION | 1 | Kurtarma anahtarı sürüm etiketi (pozitif tamsayı) |
JHIPSTER_SLEEP | 0 | Başlangıç gecikme süresi (MongoDB aynı compose'da başlatılıyorsa kullanışlı) |
3. Konteyneri çalıştır
docker run -d \
--name apinizer-apimanager \
-p 8080:8080 \
--memory=4g \
-e SPRING_DATA_MONGODB_URI='mongodb://user:pass@mongo:25080/?authSource=admin' \
-e SPRING_DATA_MONGODB_DATABASE='apinizer' \
-e SPRING_PROFILES_ACTIVE=prod \
--restart unless-stopped \
apinizercloud/apimanager:${VERSION}
--memory=4g limit'i JVM tier auto-tuner tarafından okunur — vermezseniz JVM host'un tüm belleğini görür ve heap'i fazla büyütebilir. Manager'a gerçekten ayırmak istediğiniz değeri verin.
4. docker-compose (önerilen)
services:
apimanager:
image: apinizercloud/apimanager:<APINIZER_VERSION>
container_name: apinizer-apimanager
restart: unless-stopped
mem_limit: 4g
ports:
- "8080:8080"
environment:
SPRING_PROFILES_ACTIVE: prod
SPRING_DATA_MONGODB_DATABASE: apinizer
JAVA_OPTS: "-XX:+ExitOnOutOfMemoryError"
env_file:
- ./secrets/apimanager.env # SPRING_DATA_MONGODB_URI=… içerir
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/management/health | grep -q '\"status\":\"UP\"'"]
interval: 30s
timeout: 5s
retries: 5
start_period: 90s
Başlatma:
docker compose up -d
docker compose logs -f apimanager
5. Doğrulama
curl -fsS http://127.0.0.1:8080/management/health
Beklenen: 200 OK. İlk başlangıçta Mongock migration'ları çalışır, veritabanı boyutuna göre 30–90 saniye sürebilir.
6. Operasyon
| Eylem | Komut |
|---|---|
| Durum | docker ps --filter name=apinizer-apimanager |
| Log (follow) | docker logs -f apinizer-apimanager |
| Yeniden başlat | docker restart apinizer-apimanager |
| Durdur | docker stop apinizer-apimanager |
| Shell | docker exec -it apinizer-apimanager sh |
İmajlar logları konteyner konsoluna yazar; log volume'u gerekmez. Logları docker logs ile okuyun. Spring Boot ayrıca Manager ve Portal konteynerlerinde /tmp/spring.log adlı dönen bir dosyaya yazar; bu dosya kalıcı değildir.
7. Ağ
- Inbound: yalnızca
8080/tcpPortal node'larından ve admin kullanıcılarından erişilebilir olmalı. - Outbound: Manager MongoDB'ye ve yapılandırılmış backend servislere (LDAP, OIDC, SMTP) bağlanır. Steady state'te internet erişimi gerekmez.
- Çoklu konteyner kurulumlarda tüm Apinizer servislerini aynı user-defined Docker network'üne koyup service adıyla referans verin.
8. Kaynak
| Yük | mem_limit |
|---|---|
| Smoke test / tek tenant | 2 GB |
| Üretim (≤ 200 aktif proxy) | 4 GB |
| Büyük kurulum / çok eşzamanlı admin | 6–8 GB |
CPU: minimum 2 vCPU, önerilen 4 vCPU.
Sorun Giderme
Konteyner başlangıçta MongoDB bağlantı hatası veriyor
İmaj SPRING_DATA_MONGODB_URI ve SPRING_DATA_MONGODB_DATABASE değişkenlerini başlamadan önce denetlemez. Biri boş ya da yanlışsa hata docker logs içinde görünür. İki değişkeni de verip konteyneri yeniden oluşturun. ?replicaSet=…&authSource=… shell quoting'ine dikkat — -e SPRING_DATA_MONGODB_URI="…" çift tırnaklı veya env-file ile geçirin.
Health endpoint 503 OUT_OF_SERVICE dönüyor
MongoDB erişilemez durumda. Konteyner içinden test:
docker exec apinizer-apimanager nc -zv -w 3 <mongo-host> 25080
Host 32 GB olduğu hâlde log'da JVM tier: 1GB (heap 50%…) görünüyor
--memory / mem_limit vermediniz. Cgroup default'u max ve auto-tuner host belleğine düşer. mem_limit'i konteynerin gerçekten kullanmasını istediğiniz değere set edin.
MongoDB bağlantısı timeout
- Ağ erişimini doğrulayın:
docker exec apinizer-apimanager sh -lc 'nc -zv mongo 25080'. - URI'da
replicaSet=veauthSource=doğru mu? - MongoDB'ye TLS gerekiyorsa
&tls=trueekleyin ve CA dosyasını mount edin.
API Worker, Apinizer'ın gateway runtime'ıdır: gelen HTTP/HTTPS/gRPC/WebSocket isteklerini sonlandırır, deploy edilmiş proxy policy pipeline'larını çalıştırır ve trafik log'unu yazar. Manager UI'da en az bir Environment kayıtlı olmalı ve quota/OIDC/CB kullanıyorsanız Cache önce ayakta olmalıdır.
Bu rehber Apinizer Worker'ın (API Gateway runtime) Docker konteyneri olarak nasıl çalıştırılacağını anlatır. Worker HTTP / HTTPS / gRPC / WebSocket isteklerini sonlandırır, deploy edilmiş proxy policy pipeline'larını çalıştırır ve trafik log'u yazar.
Worker imajı Ubuntu noble (glibc) üzerine kuruludur, Alpine değil — çünkü brotli4j native compression library'sinin musl build'i yok. Alpine üzerinde custom build yapmayın.
Gereksinimler
- Docker Engine 24+ kurulu bir Linux x86-64 host
- Manager'ın kullandığı aynı MongoDB
- Manager UI'da kayıtlı bir Environment girdisi (Server Management → Environments)
- Quota, OIDC session, circuit breaker kullanılıyorsa erişilebilir bir Apinizer Cache cluster
- Boş TCP portları:
8091/tcp— HTTP gateway listener8443/tcp— HTTPS gateway listener (Environment'ta HTTPS açıksa)8094/tcp— gRPC gateway listener (isteğe bağlı; yalnız Environment gRPC protokolünü kullanıyorsa)9091/tcp— Prometheus metrikleri (isteğe bağlı; yalnızMETRICS_ENABLED=trueise)
1. İmajı çekin
VERSION=<APINIZER_VERSION>
docker pull apinizercloud/worker:${VERSION}
2. Yapılandırma
Zorunlu:
| Değişken | Açıklama |
|---|---|
SPRING_DATA_MONGODB_URI | MongoDB connection string |
SPRING_DATA_MONGODB_DATABASE | MongoDB veritabanı adı |
APINIZER_ENVIRONMENT_NAME | Environment adı. Manager UI'daki bir Environment ile tam eşleşmeli (case-sensitive). |
Önerilen:
| Değişken | Varsayılan | Açıklama |
|---|---|---|
WORKER_TIMEZONE | container saat dilimi | Worker JVM'inin saat dilimi: IANA zone ID veya offset (örn. +03:00). Önerilir. Boşsa container saat dilimi kullanılır. |
JAVA_OPTS | boş | Üretim için: "-server -XX:MaxRAMPercentage=75.0 -Dhttp.maxConnections=4096 -Dlog4j.formatMsgNoLookups=true" |
Opsiyonel (Undertow / gateway tuning):
| Değişken | Varsayılan | Açıklama |
|---|---|---|
tuneWorkerThreads | CPU × 8 | XNIO worker pool |
tuneWorkerMaxThreads | CPU × 16 | Worker pool hard cap |
tuneIoThreads | CPU çekirdek sayısı | XNIO I/O selectors (vCPU sayısına eşitleyin) |
tuneBufferSize | 16384 | Read/write buffer boyutu (bayt) |
tuneDirectBuffers | true | Off-heap buffer (GC baskısını azaltır) |
tuneBacklog | 1000 | Kernel TCP listen backlog |
APINIZER_WORKER_NODE_IP | otomatik | Node IP override (çok NIC'li host'lar için) |
3. Konteyneri çalıştır
docker run -d \
--name apinizer-worker \
-p 8091:8091 \
-p 8443:8443 \
--memory=8g \
--cpus=4 \
-e SPRING_DATA_MONGODB_URI='mongodb://user:pass@mongo:25080/?authSource=admin' \
-e SPRING_DATA_MONGODB_DATABASE='apinizer' \
-e APINIZER_ENVIRONMENT_NAME='prod-dc1' \
-e WORKER_TIMEZONE='+03:00' \
-e JAVA_OPTS='-server -XX:MaxRAMPercentage=75.0 -Dhttp.maxConnections=4096 -Dlog4j.formatMsgNoLookups=true' \
--restart unless-stopped \
--ulimit nofile=1048576:1048576 \
apinizercloud/worker:${VERSION}
İsteğe bağlı portlar: Environment gRPC protokolünü kullanıyorsa -p 8094:8094, Prometheus metriklerini açmak için -e METRICS_ENABLED=true -p 9091:9091 ekleyin.
Worker throughput-sensitive: yüksek eşzamanlı bağlantı sayısı için --ulimit nofile=1048576:1048576 kritik.
4. docker-compose
services:
worker:
image: apinizercloud/worker:<APINIZER_VERSION>
container_name: apinizer-worker
restart: unless-stopped
mem_limit: 8g
cpus: 4
ports:
- "8091:8091"
- "8443:8443"
# - "8094:8094" # isteğe bağlı: gRPC gateway (Environment gRPC protokolünü kullanıyorsa)
# - "9091:9091" # isteğe bağlı: Prometheus metrikleri (METRICS_ENABLED=true gerekir)
environment:
SPRING_DATA_MONGODB_DATABASE: apinizer
APINIZER_ENVIRONMENT_NAME: prod-dc1
WORKER_TIMEZONE: "+03:00"
JAVA_OPTS: "-server -XX:MaxRAMPercentage=75.0 -Dhttp.maxConnections=4096 -Dlog4j.formatMsgNoLookups=true"
tuneWorkerThreads: "1024"
tuneIoThreads: "4"
env_file:
- ./secrets/worker.env
ulimits:
nofile:
soft: 1048576
hard: 1048576
healthcheck:
test: ["CMD-SHELL", "bash -c 'exec 3<>/dev/tcp/127.0.0.1/8091 && printf \"GET /apinizer/management/health HTTP/1.0\\r\\n\\r\\n\" >&3 && grep -q OK <&3'"]
interval: 30s
timeout: 5s
retries: 5
start_period: 60s
5. Doğrulama
curl -fsS http://127.0.0.1:8091/apinizer/management/health
Deploy edilmiş bir proxy üzerinden test isteği:
curl -fsS http://127.0.0.1:8091/echo -H 'X-Trace: 1'
Beklenen boot log'u:
ApiGateway standalone=true (env: prod-dc1)
HTTP listener bound: 0.0.0.0:8091
HTTPS listener bound: 0.0.0.0:8443 (Environment HTTPS açıksa)
Loaded N proxies for environment prod-dc1
6. Operasyon
| Eylem | Komut |
|---|---|
| Durum | docker ps --filter name=apinizer-worker |
| Log | docker logs -f apinizer-worker |
| Yeniden başlat | docker restart apinizer-worker |
| Durdur (drain) | docker stop -t 60 apinizer-worker |
İmajlar logları konteyner konsoluna yazar; log volume'u gerekmez. Logları docker logs ile okuyun.
Cömert stop timeout kullanın (docker stop -t 60) — in-flight HTTP / gRPC / WebSocket istekleri drain olabilsin. -t vermezseniz Docker 10 saniye sonra SIGKILL atar.
7. Ağ
Inbound
| Port | Amaç |
|---|---|
8091 | HTTP gateway |
8443 | HTTPS gateway |
8094 | gRPC gateway (isteğe bağlı) |
9091 | Prometheus metrikleri (isteğe bağlı, METRICS_ENABLED=true) |
Outbound
- MongoDB (proxy config + trafik log yazımı)
- Cache REST API
8090/tcp, quota/OIDC/CB kullanılıyorsa - Deploy edilmiş her proxy'nin bağlandığı backend servisleri
8. Çoklu Worker (yatay ölçeklendirme)
Aynı imajı aynı APINIZER_ENVIRONMENT_NAME ile her replikada çalışt ırın. Quota sayaçları, OIDC session'ları ve circuit-breaker durumu Apinizer Cache (Hazelcast) üzerinden paylaşılır. Cache paylaşılmazsa her Worker'ın kendi sayaçları olur.
9. Kaynak
| Yük | mem_limit | cpus |
|---|---|---|
| Smoke / staging (<200 rps) | 2 GB | 2 |
| Üretim (Worker başına 1–3 krps) | 4–6 GB | 4 |
| Yüksek throughput (5+ krps) | 8 GB | 4–8 |
JVM bayraklarını değiştirmeden önce hedef donanımda yük testi yapın.
Sorun Giderme
APINIZER_ENVIRONMENT_NAME uyuşmazlığı → konteyner başlıyor ama proxy yüklenmiyor
İsim Manager UI'daki bir Environment ile case-sensitive eşleşmiyorsa proxy snapshot çekilmez ve her istek 404 döner. Çözüm: env var'ı düzeltin veya Environment oluşturun.
UnsatisfiedLinkError: brotli
Alpine üzerinde custom build çalıştırıyorsunuz. Resmi apinizercloud/worker (Ubuntu noble) imajına geri dönün.
EMFILE: too many open files
docker run'a --ulimit nofile=1048576:1048576 ekleyin. Host tarafında /etc/security/limits.conf / daemon'un LimitNOFILE değerinin de izin verdiğinden emin olun.
API Cache, Hazelcast tabanlı dağıtık bir data grid'tir: quota sayaçları, OIDC session'ları, circuit-breaker durumu ve client-flow banner'larını Worker'lar arasında paylaşır. Çoklu Worker veya quota/OIDC kullanan tek-Worker kurulumlarda Worker'dan önce ayağa kaldırılır.
Bu rehber Apinizer Cache'in (quota, OIDC session, circuit-breaker durumu ve client-flow banner'ları besleyen Hazelcast data grid) Docker konteyneri olarak nasıl çalıştırılacağını anlatır. Cache, Hazelcast MapStore üzerinden MongoDB'ye dayanıklı counter snapshot yazar ve Worker'a Spring Boot HTTP portu üzerinden hizmet verir.
Standalone modu otomatik tespit edilir: konteynerde Kubernetes service-account namespace dosyası yoksa Cache Hazelcast discovery'sini Kubernetes plug-in'den TCP/IP'ye çevirir.
Gereksinimler
- Docker Engine 24+ kurulu bir Linux x86-64 host
- Erişilebilir bir Apinizer Manager-managed MongoDB
- Boş TCP portları:
5701/tcp— Hazelcast wire protocol (member-to-member)8090/tcp— Spring Boot HTTP (Worker → Cache REST)9091/tcp— Prometheus metrikleri (isteğe bağlı)
- Çoklu node cluster için: Cache node'ları arasında çift yönlü
5701/tcperişimi
1. İmajı çekin
VERSION=<APINIZER_VERSION>
docker pull apinizercloud/cache:${VERSION}
2. Yapılandırma
Zorunlu:
| Değişken | Açıklama |
|---|---|
SPRING_DATA_MONGODB_URI | MongoDB connection string |
SPRING_DATA_MONGODB_DATABASE | MongoDB veritabanı (Manager/Worker ile aynı) |
Önerilen:
| Değişken | Varsayılan | Açıklama |
|---|---|---|
CACHE_QUOTA_TIMEZONE | container saat dilimi | Quota pencerelerinin saat dilimi (örn. +03:00). Önerilir; Worker ve Manager ile aynı değeri verin. Boşsa container saat dilimi kullanılır. |
HAZELCAST_CLUSTER_NAME | apnz-hz-cluster | Logical cluster adı. Aynı LAN'da birden fazla bağımsız Apinizer kurulumu varsa override edin. Cache node'ları arasında uyumsuzluk → sessiz split-brain. |
APINIZER_CACHE_CLUSTER_MEMBERS | boş | Çoklu node TCP/IP discovery için comma-separated peer listesi |
SERVER_PORT | 8090 | Spring Boot HTTP portu |
3. Tek-node Cache
docker run -d \
--name apinizer-cache \
-p 5701:5701 \
-p 8090:8090 \
--memory=4g \
-e SPRING_DATA_MONGODB_URI='mongodb://user:pass@mongo:25080/?authSource=admin' \
-e SPRING_DATA_MONGODB_DATABASE='apinizer' \
-e CACHE_QUOTA_TIMEZONE='+03:00' \
--restart unless-stopped \
apinizercloud/cache:${VERSION}
İsteğe bağlı port: Prometheus metriklerini açmak için -p 9091:9091 ekleyin.
Beklenen boot log'u:
Cache running in STANDALONE mode (cluster: apnz-hz-cluster)
Standalone Hazelcast cluster members: 127.0.0.1
Members {size:1, ver:1} [ Member [127.0.0.1]:5701 - ... ]
4. Çoklu-node Cache cluster
Her node'da aynı peer listesi ve aynı cluster adı olmalı.