API Portal — Docker
Bu rehber Apinizer API Portal'ın Docker konteyneri olarak nasıl çalıştırılacağını anlatır. Portal geliştirici-yüzlü UI'dır: API'leri listeler, abonelikleri yönetir, dokümantasyonu sunar. Veriyi Apinizer Manager REST API'sinden alır — Portal'dan doğrudan MongoDB bağlantısı yoktur.
Portal stateless'tır: her konteyner restart'ı güvenlidir, yatay ölçeklendirme için bir load balancer arkasında birden fazla replika çalıştırılabilir.
Gereksinimler
- Docker Engine 24+ kurulu bir Linux x86-64 host
- Erişilebilir bir Apinizer Manager ve geçerli bir Manager API key
- Boş bir TCP port (varsayılan
8080; Manager ile aynı host'taysa8081'e remap edin)
1. İmajı çekin
VERSION=<APINIZER_VERSION>
docker pull apinizercloud/apiportal:${VERSION}
2. Portal'ı Manager'a kaydedin
Konteyneri başlatmadan önce Manager UI'da Portal'ı bir kez kaydedin:
- Manager UI'da Portal → Portals → Create. Üretilen Portal ID'yi not edin.
- Portal → API Keys → Generate ile API key oluşturun (sadece bir kez gösterilir).
- Bu API key için ayrı bir Manager kullanıcısı kullanın ve ona yalnız Portal Developer rolünü verin. Her Portal çağrısı için bir portal rolü gerekir. Portal Ayarları → Güvenlik → Management API Anahtarı Kullanıcıları listesinde kayıt varsa kullanıcıyı bu listeye de ekleyin. Liste boşsa rol yeterlidir. Aksi halde Manager Portal'ın tüm çağrılarını 403 ile reddeder. Bkz. Portal'ın Management API Anahtarı.
3. Yapılandırma
Zorunlu:
| Değişken | Açıklama |
|---|---|
API_PORTAL_ID | 2. adımdan gelen Portal kimliği |
API_PORTAL_MANAGEMENT_API_BASE_URL | Manager REST API base URL (örn. https://manager.example.com) |
API_PORTAL_MANAGEMENT_API_KEY | 2. adımdan gelen API key |
Opsiyonel:
| Değişken | Varsayılan | Açıklama |
|---|---|---|
SERVER_PORT | 8080 | Konteyner içi HTTP portu |
SPRING_PROFILES_ACTIVE | prod | Üretimde böyle kalsın |
SSL_ENABLED | false | true yapılırsa konteyner içinde TLS sonlandırılır |
JAVA_OPTS | boş | Ek JVM bayrakları |
4. Konteyneri çalıştır
docker run -d \
--name apinizer-apiportal \
-p 8081:8080 \
--memory=2g \
-e API_PORTAL_ID='portal-prod-01' \
-e API_PORTAL_MANAGEMENT_API_BASE_URL='https://manager.example.com' \
-e API_PORTAL_MANAGEMENT_API_KEY='<api-key>' \
-e SPRING_PROFILES_ACTIVE=prod \
--restart unless-stopped \
apinizercloud/apiportal:${VERSION}
API Manager zaten host 8080'i kullanıyorsa konteynerin 8080'ini host 8081'e map edin.
5. docker-compose
services:
apiportal:
image: apinizercloud/apiportal:<APINIZER_VERSION>
container_name: apinizer-apiportal
restart: unless-stopped
mem_limit: 2g
ports:
- "8081:8080"
environment:
API_PORTAL_ID: portal-prod-01
API_PORTAL_MANAGEMENT_API_BASE_URL: https://manager.example.com
SPRING_PROFILES_ACTIVE: prod
env_file:
- ./secrets/apiportal.env # API_PORTAL_MANAGEMENT_API_KEY=… içerir
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/apinizer/management/health | grep -q OK || exit 1"]
interval: 30s
timeout: 5s
retries: 5
start_period: 60s
6. Doğrulama
curl -fsS http://127.0.0.1:8081/apinizer/management/health
Tarayıcıda http://<host>:8081/ açın. İlk sayfa yüklemesi katalogu Manager'dan çeker — Manager URL veya API key yanlışsa 502/timeout banner görünür.
7. Operasyon
| Eylem | Komut |
|---|---|
| Durum | docker ps --filter name=apinizer-apiportal |
| Log | docker logs -f apinizer-apiportal |
| Yeniden başlat | docker restart apinizer-apiportal |
| Durdur | docker stop apinizer-apiportal |
İ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.
8. TLS sonlandırma
İki yaygın yaklaşım:
-
Önünde reverse proxy (önerilen): nginx, Traefik veya bir LB üzerinde TLS sonlandır; konteynerde
SSL_ENABLED=falsekalsın. -
Konteyner içi TLS: PKCS#12 keystore mount edin:
environment:SSL_ENABLED: "true"SSL_KEY_STORE: /run/keystore/portal.p12SSL_KEY_STORE_TYPE: PKCS12SSL_KEY_STORE_PASSWORD: <password>SSL_KEY_ALIAS: apinizerSSL_PROTOCOLS: TLSv1.2,TLSv1.3volumes:- ./secrets/portal.p12:/run/keystore/portal.p12:ro
9. Çoklu replika
Portal stateless. Çoklu replika için:
- Her replikaya aynı
API_PORTAL_ID'yi verin. - Önüne bir LB koyun.
- Sticky session gerekmez.
Sorun Giderme
Konteyner sürekli restart, log'da Required configuration is missing
Portal başlarken üç değişkeni denetler ve eksik olanları log mesajında yazar. Üçünü de verin: API_PORTAL_ID, API_PORTAL_MANAGEMENT_API_BASE_URL, API_PORTAL_MANAGEMENT_API_KEY.
Ana sayfa 502 Bad Gateway dönüyor
Portal Manager REST API'ye erişemiyor. Konteyner içinden kontrol:
docker exec apinizer-apiportal sh -lc \
"wget --header='Authorization: $API_PORTAL_MANAGEMENT_API_KEY' \
-qO- $API_PORTAL_MANAGEMENT_API_BASE_URL/apiportal/management/hello"