Ana içeriğe geç

Virtual Server Installation

Apinizer ships as self-contained standalone packages with bundled OpenJDK 25 — no host Java required. Sensitive configuration (MongoDB connection URI, etc.) is encrypted in place via a Jasypt master key; the JVM never sees ciphertext and the master key never leaves the host filesystem.

bilgi

The installer needs root privileges via sudo, but no interactive root login is required. This is compatible with hardened environments where direct root SSH is disabled (common in finance and regulated sectors).

Installation Flow​

Install modules in this order:

  1. MongoDB — Required, must be pre-configured and reachable
  2. API Manager — Required, the management console
  3. API Gateway (Worker) — Required, the API Gateway runtime
  4. Optional: Cache, Integration, API Portal

General Requirements​

Common requirements for all modules:

  • Linux x86-64 (glibc) — Ubuntu 20.04+, RHEL/Rocky/Alma 8+, Debian 11+, Oracle Linux 8+
  • An operator with sudo privilege (no root login required)
  • openssl, systemd, tar, curl (typically pre-installed)
  • A reachable Apinizer MongoDB instance (replica set recommended for production)
uyarı

MongoDB is mandatory; all other modules depend on it. Elasticsearch is optional.

not

Pre-installation: Decide which optional modules you need (Cache for quota state, Integration for task flows, API Portal for end-users). This determines which download steps to prepare in advance.

API Manager Installation​

The Apinizer Management Console (API Manager) is the component through which Apinizer is managed. It is the central hub for proxy configuration, environment management, user access control and monitoring.

1. Download​

Download the latest tarball from packages.apinizer.com:

VERSION=2026.04.2
curl -fSLO "https://packages.apinizer.com/apinizer-packages/apimanager/${VERSION}/apinizer-apimanager-${VERSION}-linux-x64.tar.gz"
curl -fSLO "https://packages.apinizer.com/apinizer-packages/apimanager/${VERSION}/checksums.sha256"
sha256sum -c checksums.sha256

2. Extract​

sudo mkdir -p /opt
sudo tar -xzf apinizer-apimanager-${VERSION}-linux-x64.tar.gz -C /opt
sudo mv /opt/apinizer-apimanager-${VERSION} /opt/apinizer-manager

The package layout is:

/opt/apinizer-manager/
├── bin/        # start / stop / install / encrypt scripts and systemd unit
├── conf/       # application.env (master.key generated by installer)
├── lib/        # Spring Boot fat jar + lib/jasypt/ helper jar
├── runtime/    # Bundled OpenJDK 25 (Temurin)
└── logs/       # Runtime logs (created on first start)

3. Configure​

Edit conf/application.env and provide the required parameters:

sudo vi /opt/apinizer-manager/conf/application.env
KeyDescription
SPRING_DATA_MONGODB_URIMongoDB connection string (e.g. mongodb://user:pass@host:25080/?replicaSet=rs0&authSource=admin)
SPRING_DATA_MONGODB_DATABASEDatabase name (e.g. apinizer)

Optional sections cover SSL, server port, JVM tuning, and logging path.

uyarı

Plaintext values are accepted at this point — do not start the service yet. The next step encrypts them in place.

4. Run the Installer​

The installer creates a dedicated apinizer system user, sets file permissions, generates a random Jasypt master key in conf/master.key, and registers the systemd service.

sudo /opt/apinizer-manager/bin/apimanager-install.sh

To delegate this to a non-root operator without granting full root, add a sudoers entry:

apinizer-admin ALL=(root) NOPASSWD: /opt/apinizer-manager/bin/apimanager-install.sh

After install, the master key is owned by apinizer:apinizer and is mode 400 — only the service user can read it.

5. Encrypt Sensitive Values​

Run the encrypt helper with no arguments to encrypt the standard fields in conf/application.env in place. Already-encrypted (or empty) values are skipped, and a timestamped backup is written next to the file.

sudo -u apinizer /opt/apinizer-manager/bin/apimanager-encrypt.sh

The standard fields it encrypts are:

  • SPRING_DATA_MONGODB_URI
  • SPRING_DATA_MONGODB_DATABASE

After it runs, the env file looks like this (values quoted so bash source does not choke on the parentheses):

SPRING_DATA_MONGODB_URI="ENC(eXq1J9z...kTu4=)"
SPRING_DATA_MONGODB_DATABASE="ENC(zMv3K7p...lQw9=)"

6. Start the Service​

sudo systemctl start apinizer-apimanager
sudo systemctl status apinizer-apimanager
sudo journalctl -u apinizer-apimanager -f

The service is enabled at install time, so it will also start automatically after a reboot.

7. Verify​

Confirm the API Manager is responding on the configured port (default 8080):

curl -fsS http://127.0.0.1:8080/management/health

Expected: a 200 OK response with health details (visible to authenticated admins; anonymous responses contain only the status).

Operations​

Status

sudo systemctl status apinizer-apimanager

Restart

sudo systemctl restart apinizer-apimanager

Stop

sudo systemctl stop apinizer-apimanager

Logs

sudo journalctl -u apinizer-apimanager -f

Manual control (without systemd):

sudo -u apinizer /opt/apinizer-manager/bin/apimanager-start.sh           # background
sudo -u apinizer /opt/apinizer-manager/bin/apimanager-start.sh -f        # foreground
sudo -u apinizer /opt/apinizer-manager/bin/apimanager-stop.sh

Security Model​

  • apinizer is a system account with /sbin/nologin — no interactive shell.
  • conf/master.key is mode 400, owned by apinizer. Only that user (and root) can read it.
  • conf/application.env is mode 600. ENC(...) values are decrypted by bin/apimanager-start.sh at boot (using the bundled lib/jasypt/jasypt-*.jar + the master key) and exported to the JVM as plain values. The JVM never sees the ciphertext; the master key never leaves the host filesystem.
  • The systemd unit applies hardening flags: NoNewPrivileges, PrivateTmp, ProtectSystem=strict, ProtectHome, ReadWritePaths=…/logs. Application can only write under logs/.
uyarı

Back up conf/master.key to your secrets vault. If the master key is lost, all ENC(...) values are unrecoverable and must be re-entered in plaintext, then re-encrypted with a new key.

not

For API Manager troubleshooting, see Troubleshooting.

For upgrading or uninstalling this module, see Version Upgrade and Uninstall pages.

Next Step — Gateway Installation (Mandatory)​

API Manager is now installed and running. You must now install at least one Gateway and define it as an environment in the Manager — this is Apinizer's actual API Gateway and is mandatory for routing API traffic.

API Gateway (Worker) Installation and Configuration​

The Gateway (Worker) is Apinizer's actual API Gateway module — the entry point for API requests and where policies are applied. On a virtual server, the Gateway is installed on a separate host (or the same host) and registered with the Manager as a Remote Environment.

1. Download​

Download the latest tarball from packages.apinizer.com:

VERSION=2026.04.2
curl -fSLO "https://packages.apinizer.com/apinizer-packages/worker/${VERSION}/apinizer-worker-${VERSION}-linux-x64.tar.gz"
curl -fSLO "https://packages.apinizer.com/apinizer-packages/worker/${VERSION}/checksums.sha256"
sha256sum -c checksums.sha256

2. Extract​

sudo mkdir -p /opt
sudo tar -xzf apinizer-worker-${VERSION}-linux-x64.tar.gz -C /opt
sudo mv /opt/apinizer-worker-${VERSION} /opt/apinizer-worker

The package layout is:

/opt/apinizer-worker/
├── bin/        # start / stop / install / encrypt scripts and systemd unit
├── conf/       # apinizer-worker.env (master.key generated by installer)
├── lib/        # Worker shaded launcher jar + lib/jasypt/ helper jar
├── runtime/    # Bundled OpenJDK 25 (Temurin)
└── logs/       # Runtime logs (created on first start)

3. Configure​

Edit conf/apinizer-worker.env and provide the required parameters:

sudo vi /opt/apinizer-worker/conf/apinizer-worker.env
KeyDescription
SPRING_DATA_MONGODB_URIMongoDB connection string (e.g. mongodb://user:pass@host:25080/?replicaSet=rs0&authSource=admin)
SPRING_DATA_MONGODB_DATABASEDatabase name (e.g. apinizer)
APINIZER_ENVIRONMENT_NAMEName of the Environment to bind this Worker to. Must exactly match an Environment created in API Manager (Server Management → Environments). In Kubernetes the Worker reads this from the pod namespace; in standalone mode you must set it explicitly. Setting this also flips ApiGateway.standalone=true and is logged at startup.
WORKER_TIMEZONETimezone offset (e.g. +03:00)

Optional sections cover JVM tuning, Undertow thread/buffer sizes, HTTP/2, WebSocket, gRPC, CORS defaults, X-Forwarded-For parsing and multipart upload limits. Recommended defaults for production:

JAVA_OPTS="-server -XX:MaxRAMPercentage=75.0 -Dhttp.maxConnections=4096 -Dlog4j.formatMsgNoLookups=true"
tuneWorkerThreads=1024
tuneWorkerMaxThreads=4096
tuneBufferSize=16384
tuneIoThreads=4
tuneBacklog=10000
tuneRoutingConnectionPoolMaxConnectionPerHost=1024
tuneRoutingConnectionPoolMaxConnectionTotal=4096
tuneReadTimeout=30000
tuneNoRequestTimeout=60000
ipucu

If the Gateway type will serve HTTP + WebSocket traffic, set http2Enabled=false. Many WebSocket clients do not negotiate HTTP/2 cleanly, so leaving HTTP/2 off avoids handshake regressions.

uyarı

Plaintext values are accepted at this point — do not start the service yet. The next step encrypts them in place.

4. Run the Installer​

The installer creates a dedicated apinizer system user, sets file permissions, generates a random Jasypt master key in conf/master.key, and registers the systemd service.

sudo /opt/apinizer-worker/bin/apiworker-install.sh

To delegate this to a non-root operator without granting full root, add a sudoers entry:

apinizer-admin ALL=(root) NOPASSWD: /opt/apinizer-worker/bin/apiworker-install.sh

After install, the master key is owned by apinizer:apinizer and is mode 400 — only the service user can read it.

5. Encrypt Sensitive Values​

Run the encrypt helper with no arguments to encrypt the standard fields in conf/apinizer-worker.env in place. Already-encrypted (or empty) values are skipped, and a timestamped backup is written next to the file.

sudo -u apinizer /opt/apinizer-worker/bin/apiworker-encrypt.sh

The standard fields it encrypts are:

  • SPRING_DATA_MONGODB_URI
  • SPRING_DATA_MONGODB_DATABASE

After it runs, the env file looks like this (values quoted so bash source does not choke on the parentheses):

SPRING_DATA_MONGODB_URI="ENC(eXq1J9z...kTu4=)"
SPRING_DATA_MONGODB_DATABASE="ENC(zMv3K7p...lQw9=)"

6. Start the Service​

sudo systemctl start apinizer-apiworker
sudo systemctl status apinizer-apiworker
sudo journalctl -u apinizer-apiworker -f

The service is enabled at install time, so it will also start automatically after a reboot.

7. Verify​

The Worker is a non-Spring traffic gateway — it does not expose a /management/health endpoint. To verify it has started, watch the journal log for the listener line:

sudo journalctl -u apinizer-apiworker -f | grep -E 'Listener|started|ApiGateway'

You should see Undertow bind to the configured ports (HTTP/HTTPS/gRPC depending on which Gateway Runtimes you have deployed from the Manager).

Operations​

Status

sudo systemctl status apinizer-apiworker

Restart

sudo systemctl restart apinizer-apiworker

Stop

sudo systemctl stop apinizer-apiworker

Logs

sudo journalctl -u apinizer-apiworker -f

Manual control (without systemd):

sudo -u apinizer /opt/apinizer-worker/bin/apiworker-start.sh           # background
sudo -u apinizer /opt/apinizer-worker/bin/apiworker-start.sh -f        # foreground
sudo -u apinizer /opt/apinizer-worker/bin/apiworker-stop.sh

Security Model​

  • apinizer is a system account with /sbin/nologin — no interactive shell.
  • conf/master.key is mode 400, owned by apinizer. Only that user (and root) can read it.
  • conf/apinizer-worker.env is mode 600. ENC(...) values are decrypted by bin/apiworker-start.sh at boot (using the bundled lib/jasypt/jasypt-*.jar + the master key) and exported to the JVM as plain values. The JVM never sees the ciphertext; the master key never leaves the host filesystem.
  • The systemd unit applies hardening flags: NoNewPrivileges, PrivateTmp, ProtectSystem=strict, ProtectHome, ReadWritePaths=…/logs. Application can only write under logs/.
  • File handle limit (LimitNOFILE=1048576) and process limit (LimitNPROC=65536) are raised — the Worker terminates a high number of concurrent client sockets and benefits from generous ulimits.
uyarı

Back up conf/master.key to your secrets vault. If the master key is lost, all ENC(...) values are unrecoverable and must be re-entered in plaintext, then re-encrypted with a new key.

not

For Gateway (Worker) troubleshooting, see Troubleshooting.

For upgrading or uninstalling this module, see Version Upgrade and Uninstall pages.

Defining the Gateway as an Environment in the Manager​

After the Gateway server is installed on Linux and the apinizer-apiworker.service is running, navigate to Manager UI Server Management → Gateway Runtimes → New.

Remote Gateway environment registration form

Form Fields​

FieldValue
PlatformVirtual Server
Management TypeRemote Gateway
Environment TypeDEV / TEST / PROD
Communication Protocol TypeMatches the service you exposed (HTTP / HTTPS / gRPC / WebSocket)
Environment NameMust exactly match the APINIZER_ENVIRONMENT_NAME env value (case-sensitive)
Environment KeyAPI URL prefix (e.g., prod)
Access URLGateway external access URL (e.g., https://gateway.example.com)

Gateway Node List (Manual URL Table)​

When Remote Gateway is selected, a Gateway Node List table appears on the form. For each node:

FieldDescription
NameIdentifier (e.g., node-1)
Gateway Management API URLhttp://<NODE_IP>:8091 (Gateway Management API endpoint)
Cache Management API URLhttp://<CACHE_IP>:8092 (Cache Management API endpoint, if used)
uyarı

These URLs must be reachable from Manager. Manager uses these addresses for proxy push, health checks, and diagnostics on the Gateway. Make sure firewall rules and port forwarding allow Manager → Worker 8091 traffic.

Publishing the Environment​

Click Create. For a virtual-server Gateway, Apinizer does NOT perform any deployment — the Gateway was already installed on Linux in the steps above. Manager only records the connection metadata and attempts to connect to the Gateway. If successful, the environment is marked as published.

bilgi

After publishing, you can deploy API Proxies to this Remote Gateway. Manager pushes API Proxy YAMLs to the Gateway's Management API endpoint.

not

For Gateway additional variables (JVM tuning, gRPC, WebSocket, CORS, security, etc.) and configurations (System Settings, Backup, etc.), see Gateway Settings.

Common Settings​

JVM Tuning​

API Manager and Gateway both support heap and GC parameter tuning:

For API Manager, edit conf/application.env:

JAVA_OPTS="-Xms1g -Xmx2g -XX:+UseG1GC"
jvmOverride=true

For Gateway, edit conf/apinizer-worker.env:

JAVA_OPTS="-server -XX:MaxRAMPercentage=75.0 -XX:+UseG1GC"
jvmOverride=true

When jvmOverride=true, your JAVA_OPTS take precedence over the auto-detection defaults.

Timezone Synchronization​

All Apinizer modules must use the same timezone or quota rollovers, cron jobs and scheduled task flows will drift:

  • API Manager: Set via application.env (optional, defaults to host)
  • Gateway (Worker): Set via WORKER_TIMEZONE in apinizer-worker.env (e.g. +03:00 or IANA zone id)
  • Cache (if used): Set via CACHE_QUOTA_TIMEZONE in apinizer-cache.env
  • Integration (if used): Set via INTEGRATION_TIMEZONE in apinizer-integration.env (IANA zone id, e.g. Europe/Istanbul)

Verify all values match before starting the services.

Log Management​

Logs are stored in multiple locations:

  • systemd journal: sudo journalctl -u apinizer-apimanager -f or -u apinizer-apiworker
  • Local logs directory: /opt/apinizer-manager/logs/ or /opt/apinizer-worker/logs/
  • Log rotation: Handled by systemd and logrotate (if configured at the OS level)

For production, configure a centralized log aggregator (Elasticsearch, Splunk, etc.) via the Manager UI under Admin → Log Connectors.

Optional Modules​

Install any of the following modules based on your deployment needs:

(Optional) — This module is only needed if you run quotas, OIDC sessions or circuit-breaker policies. Skip this tab if you do not need distributed state.

The Apinizer Cache (Hazelcast data grid) backs quota counters, OIDC session tokens, circuit-breaker state and client-flow banners across all Gateways.

Requirements​

  • Linux x86-64 (glibc) — Ubuntu 20.04+, RHEL/Rocky/Alma 8+, Debian 11+, Oracle Linux 8+
  • An operator with sudo privilege (no root login required)
  • openssl, systemd, tar, curl (typically pre-installed)
  • A reachable Apinizer Manager-managed MongoDB instance (replica set recommended for production)
  • Open ports between Cache nodes and Workers:
    • 5701/tcp — Hazelcast wire protocol (member-to-member)
    • 8090/tcp — Spring Boot HTTP (Worker → Cache REST calls)

1. Download​

VERSION=2026.04.2
curl -fSLO "https://packages.apinizer.com/apinizer-packages/cache/${VERSION}/apinizer-cache-${VERSION}-linux-x64.tar.gz"
curl -fSLO "https://packages.apinizer.com/apinizer-packages/cache/${VERSION}/checksums.sha256"
sha256sum -c checksums.sha256

2. Extract​

sudo mkdir -p /opt
sudo tar -xzf apinizer-cache-${VERSION}-linux-x64.tar.gz -C /opt
sudo mv /opt/apinizer-cache-${VERSION} /opt/apinizer-cache

3. Configure​

Edit conf/apinizer-cache.env:

sudo vi /opt/apinizer-cache/conf/apinizer-cache.env
KeyDescription
SPRING_DATA_MONGODB_URIMongoDB connection string (same as Manager and Gateway)
SPRING_DATA_MONGODB_DATABASEDatabase name (must match Manager and Gateway)
CACHE_QUOTA_TIMEZONEQuota window timezone offset (e.g. +03:00). Must match the Worker and Manager values or quota rollovers will drift.

For single-node deployment, no further settings are needed. For multi-node cluster:

APINIZER_CACHE_CLUSTER_MEMBERS=10.0.0.11,10.0.0.12,10.0.0.13
ipucu

All members of the cluster must list exactly the same set of IPs. TCP/IP discovery in Hazelcast is symmetric — if node B does not list A, B will not accept A as a member even though A reaches B.

4. Install and Encrypt​

sudo /opt/apinizer-cache/bin/apicache-install.sh
sudo -u apinizer /opt/apinizer-cache/bin/apicache-encrypt.sh

5. Start the Service​

sudo systemctl start apinizer-apicache
sudo systemctl status apinizer-apicache
sudo journalctl -u apinizer-apicache -f

Expected startup logs:

Cache running in STANDALONE mode (cluster: apnz-hz-cluster)
Standalone Hazelcast cluster members: 10.0.0.11,10.0.0.12,10.0.0.13
Members {size:3, ver:3} [
    Member [10.0.0.11]:5701 - ...
    Member [10.0.0.12]:5701 - ...
    Member [10.0.0.13]:5701 - ...
]

If only one member is listed in a multi-node setup, check firewall rules on 5701/tcp and that every node lists the same peers.

6. Wire the Gateway to the Cache​

Each Worker (apinizer-worker) must reach all Cache nodes on 5701/tcp and use the same Hazelcast cluster name. The Worker reads the cluster name from its own configuration; no Worker-side change is needed beyond keeping the names in sync.

7. Register Cache in the Manager​

In the Manager UI, navigate to Admin → Cache Servers and add:

FieldValue
HostCache server hostname/IP
Port8090
not

For upgrading or uninstalling this module, see Version Upgrade and Uninstall.

Production Checklist​

Before going live, verify:

  • MongoDB replica set is running and reachable from all modules
  • All module timezones match (Manager, Gateway, Cache, Integration)
  • Master keys are backed up to a secure location (lost keys = unrecoverable encrypted values)
  • Gateway Environment name exactly matches APINIZER_ENVIRONMENT_NAME in the Worker config
  • At least one Gateway Runtime is deployed from the Manager to the Gateway Environment
  • Cache (if used) and Workers can reach each other on the correct ports (5701/tcp, 8090/tcp)
  • Integration (if used) is registered in the Manager and reachable on port 8092
  • API Portal (if used) has valid API credentials from the Manager
  • Firewall rules permit traffic between modules on required ports
  • Log aggregation is configured (optional but recommended for production)
  • systemd services are enabled so modules restart after a host reboot
En son tarihinde güncellendi