Worker (Gateway) — Docker
This guide walks through running the Apinizer Worker (the API Gateway runtime) as a Docker container. The Worker terminates HTTP / HTTPS / gRPC / WebSocket requests, runs the deployed proxy policy pipelines, and emits traffic logs.
The Worker image is built on Ubuntu noble (glibc) — not Alpine — because the brotli4j native compression library has no musl build. Do not rebuild against Alpine.
Requirements
- A Linux x86-64 host with Docker Engine 24+
- The same MongoDB instance used by the Manager
- An Environment entry registered in the Manager UI (Server Management → Environments)
- A reachable Apinizer Cache (Hazelcast cluster) if you use quotas, OIDC sessions, circuit breakers
- Free TCP ports on the host:
8091/tcp— HTTP gateway listener8443/tcp— HTTPS gateway listener (when enabled in the Environment)8094/tcp— gRPC gateway listener (optional; only when the Environment uses the gRPC communication protocol)9091/tcp— Prometheus metrics (optional; only whenMETRICS_ENABLED=true)
1. Pull the image
VERSION=<APINIZER_VERSION>
docker pull apinizercloud/worker:${VERSION}
2. Configure
Required:
| Variable | Description |
|---|---|
SPRING_DATA_MONGODB_URI | MongoDB connection string |
SPRING_DATA_MONGODB_DATABASE | MongoDB database name |
APINIZER_ENVIRONMENT_NAME | Environment name. Must exactly match an Environment in the Manager UI. |
Recommended:
| Variable | Default | Description |
|---|---|---|
WORKER_TIMEZONE | container time zone | Time zone of the Worker JVM: IANA zone ID or offset (e.g. +03:00). Recommended. If empty, the container time zone is used. |
JAVA_OPTS | empty | "-server -XX:MaxRAMPercentage=75.0 -Dhttp.maxConnections=4096 -Dlog4j.formatMsgNoLookups=true" for production |
Optional (Undertow / gateway tuning):
| Variable | Default | Description |
|---|---|---|
tuneWorkerThreads | CPU × 8 | XNIO worker pool |
tuneWorkerMaxThreads | CPU × 16 | Hard cap on the worker pool |
tuneIoThreads | CPU core count | XNIO I/O selectors (set to vCPU count) |
tuneBufferSize | 16384 | Read/write buffer size (bytes) |
tuneDirectBuffers | true | Off-heap buffers (less GC pressure) |
tuneBacklog | 1000 | Kernel TCP listen backlog |
APINIZER_WORKER_NODE_IP | auto | Override the reported node IP (multi-NIC hosts) |
3. Run the container
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}
Optional ports: add -p 8094:8094 if the Environment uses the gRPC protocol, and -e METRICS_ENABLED=true -p 9091:9091 to expose Prometheus metrics.
The Worker is throughput-sensitive: it benefits from --ulimit nofile=1048576:1048576 for high concurrent connection counts.
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" # optional: gRPC gateway (Environment uses the gRPC protocol)
# - "9091:9091" # optional: Prometheus metrics (needs METRICS_ENABLED=true)
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. Verify
curl -fsS http://127.0.0.1:8091/apinizer/management/health
Send a test request through a deployed proxy:
curl -fsS http://127.0.0.1:8091/echo -H 'X-Trace: 1'
Expected boot logs:
ApiGateway standalone=true (env: prod-dc1)
HTTP listener bound: 0.0.0.0:8091
HTTPS listener bound: 0.0.0.0:8443 (only if Environment enables HTTPS)
Loaded N proxies for environment prod-dc1
6. Operations
| Action | Command |
|---|---|
| Status | docker ps --filter name=apinizer-worker |
| Logs | docker logs -f apinizer-worker |
| Restart | docker restart apinizer-worker |
| Stop (drain) | docker stop -t 60 apinizer-worker |
The images write logs to the container console, so no log volume is needed. Read them with docker logs.
Use a generous stop timeout (docker stop -t 60) so in-flight HTTP / gRPC / WebSocket requests can drain. Without -t, Docker kills with SIGTERM after 10 s.
7. Networking
Inbound
| Port | Purpose |
|---|---|
8091 | HTTP gateway |
8443 | HTTPS gateway |
8094 | gRPC gateway (optional) |
9091 | Prometheus metrics (optional, METRICS_ENABLED=true) |
Outbound
- MongoDB (proxy config + traffic log writes)
- Cache REST API on
8090/tcp, when quotas/OIDC/CB are used - Each backend service every deployed proxy is wired to
8. Multi-Worker (horizontal scale)
Run the same image with the same APINIZER_ENVIRONMENT_NAME on each replica. Quota counters, OIDC sessions and circuit-breaker state are shared through the Apinizer Cache (Hazelcast). Without a shared Cache, each Worker has its own counters.
9. Resources
| Workload | mem_limit | cpus |
|---|---|---|
| Smoke / staging (<200 rps) | 2 GB | 2 |
| Production (1–3 krps per Worker) | 4–6 GB | 4 |
| High throughput (5+ krps) | 8 GB | 4–8 |
Always load-test on the target hardware before changing JVM flags.
Troubleshooting
APINIZER_ENVIRONMENT_NAME mismatch → container starts but proxies don't load
If the name does not match an Environment in the Manager UI exactly (case sensitive), no proxy snapshot is fetched and every request returns 404. Fix: correct the env var or create the Environment.
UnsatisfiedLinkError: brotli
You are running a custom build of the Worker on Alpine. Switch back to the official apinizercloud/worker image (Ubuntu noble base).
EMFILE: too many open files
Add --ulimit nofile=1048576:1048576 to docker run. Also check that /etc/security/limits.conf / the host's LimitNOFILE allows it.