Apinizer Version Upgrade

Update Methods

Apinizer version upgrade operations can be performed using two different methods depending on whether your deployment has internet access:

Online Update

Used when your infrastructure has internet access. Docker images are pulled directly from Docker Hub and automatically updated. Provides a faster and easier update process.

When to Use:

If Kubernetes worker servers can access the internet
If Docker / Virtual Server hosts have outbound internet access
If you want to perform a quick and easy update
If you don't want to take extra steps for image transfer

Offline Update

Used when your infrastructure cannot access the internet or direct access is restricted due to security policies. Images are first pulled on a server with internet access, saved as .tar files, or uploaded to a local registry.

When to Use:

If Kubernetes worker servers cannot access the internet
If direct internet access is restricted due to security policies
If a local Docker registry (Nexus, Harbor, etc.) is used

Methods:

Manual Image Transfer (Docker/Containerd)
Local Registry Usage

uyarı

Reviewing release notes is recommended before upgrading.

1) Take a MongoDB Backup

MongoDB backup is taken before the update operation to prevent data loss. This command is run on the MongoDB server.

sudo mongodump \
  --host <PRIMARY_MONGODB_IP_ADDRESS> \
  --port=25080 \
  --username=apinizer \
  --password=<PASSWORD> \
  --authenticationDatabase=admin \
  --gzip \
  --archive=<BACKUP_DIRECTORY>/apinizer-backup--<CURRENT_VERSION>--<BACKUP_DATE>--01.archive

--host(string)required

Primary MongoDB server IP address

--port(number)

Default25080

MongoDB port number

--username(string)required

MongoDB username

--password(string)required

MongoDB password

--authenticationDatabase(string)

Defaultadmin

Authentication database

--gzip(boolean)

Compresses the backup file

--archive(string)required

Path and filename where the backup file will be saved

not

For detailed information about backup, you can check the Backup page.

2) Updating Apinizer Applications

The system basically consists of apimanager (manager in versions 2025.11.0 and earlier), worker, and cache applications. Depending on the license scope, integration and apiportal (portal in versions 2025.04.5 and earlier) applications may also be present.

Current version information can be accessed from Docker Hub or from the release notes page.

Update Strategy and Downtime Risk

The risk of traffic interruption during update may vary depending on factors such as pod count, update strategy, and adequacy of server resources.

Replica/Pod Count

If the application to be updated is running on only 1 pod, a short interruption may occur. It is recommended that the Api Manager component runs with 1 pod.

Update Strategy

Unless a special strategy is specified during installation, updates are performed using the RollingUpdate method with at least one pod remaining active. Recreate strategy can also be preferred for Api Manager and Cache components.

Server Resources

In environments where the number of Kubernetes worker servers is low and existing resources are used at the limit, manual intervention may be required during update and traffic flow interruption is likely.

not

Pick the tab matching your installation type.

Kubernetes
Helm
Docker
Virtual Server

2.1) Online Update

2.1.1) Apinizer Api Manager Update

uyarı

Apinizer Api Manager must be updated before updating other Apinizer components.

After Api Manager makes updates to the database, other Apinizer applications need to be fed from the database with current settings.

Therefore, after Api Manager is updated, make sure that Api Manager pods on Kubernetes are in "ready" status and then update other components.

Commands in this and subsequent steps are run on servers with Kubernetes Control Plane task.

Check deployment information

kubectl get deployments -Ao wide

Update Api Manager deployment image

kubectl set image deployment/<MANAGER_DEPLOYMENT_NAME> -n <MANAGER_NAMESPACE> <MANAGER_CONTAINER_NAME>=apinizercloud/apimanager:<NEW_VERSION>

Monitor pod status

Wait for the pod to be READY, monitor pod status and logs:

kubectl get pods -n <MANAGER_NAMESPACE>
kubectl get logs -f -n <MANAGER_NAMESPACE> <POD_NAME>

2.1.2) Apinizer Worker and Cache Update

After ensuring that the Apinizer Api Manager image is updated, Apinizer Worker and Cache applications are updated.

Update Worker and Cache deployment images

kubectl set image deployment/<WORKER_DEPLOYMENT_NAME> -n <WORKER_CACHE_NAMESPACE> <WORKER_CONTAINER_NAME>=apinizercloud/worker:<NEW_VERSION>
kubectl set image deployment/<CACHE_DEPLOYMENT_NAME> -n <WORKER_CACHE_NAMESPACE> <CACHE_CONTAINER_NAME>=apinizercloud/cache:<NEW_VERSION>

Monitor pod status

Wait for pods to be READY, monitor pod status:

kubectl get pods -n <WORKER_CACHE_NAMESPACE>
kubectl get logs -f -n <WORKER_CACHE_NAMESPACE> <POD_NAME>

2.1.3) Apinizer Portal and Integration Update

Apinizer Portal and Integration can be updated similarly.

Update Portal and Integration deployment images

kubectl set image deployment/<PORTAL_DEPLOYMENT_NAME> -n <PORTAL_NAMESPACE> <PORTAL_CONTAINER_NAME>=apinizercloud/apiportal:<NEW_VERSION>
kubectl set image deployment/<INTEGRATION_DEPLOYMENT_NAME> -n <INTEGRATION_NAMESPACE> <INTEGRATION_CONTAINER_NAME>=apinizercloud/integration:<NEW_VERSION>

Monitor pod statuses

Wait for pods to be READY, monitor pod statuses:

kubectl get pods -n <PORTAL_NAMESPACE>
kubectl get logs -f -n <PORTAL_NAMESPACE> <POD_NAME>
kubectl get pods -n <INTEGRATION_NAMESPACE>
kubectl get logs -f -n <INTEGRATION_NAMESPACE> <POD_NAME>

2.2) Offline Update

For offline systems that require updates in Kubernetes environments, two main methods can be used:

Manual Image Transfer

Pulling image files to a server with internet and docker/containerd application and transferring these image files to the target Kubernetes cluster.

Local Registry Usage

Using a repository application that the Kubernetes cluster will use (Nexus, Harbor, etc.).

2.2.1) Pulling Images from Online Server and Transferring to Offline Servers

If there is a machine with internet access and access to offline machines, the following steps can be performed.

2.2.1.1) Docker Usage

# All images required for upgrade are pulled from online server
docker pull apinizercloud/apimanager:<NEW_VERSION>
docker pull apinizercloud/worker:<NEW_VERSION>
docker pull apinizercloud/cache:<NEW_VERSION>
docker pull apinizercloud/apiportal:<NEW_VERSION>
docker pull apinizercloud/integration:<NEW_VERSION>

# To transfer relevant images to offline servers, images are saved in `.tar` format on online server
docker save apinizercloud/apimanager:<NEW_VERSION> -o apinizercloud-apimanager.<NEW_VERSION>.tar
docker save apinizercloud/worker:<NEW_VERSION> -o apinizercloud-worker.<NEW_VERSION>.tar
docker save apinizercloud/cache:<NEW_VERSION> -o apinizercloud-cache.<NEW_VERSION>.tar
docker save apinizercloud/apiportal:<NEW_VERSION> -o apinizercloud-apiportal.<NEW_VERSION>.tar
docker save apinizercloud/integration:<NEW_VERSION> -o apinizercloud-integration.<NEW_VERSION>.tar

# Each image is transferred to offline server
scp apinizercloud-*.tar <OFFLINE_MACHINE_USER>@<OFFLINE_MACHINE_IP>:<TARGET_DIRECTORY>

# Images are loaded on each offline server
docker load -i apinizercloud-apimanager.<NEW_VERSION>.tar
docker load -i apinizercloud-worker.<NEW_VERSION>.tar
docker load -i apinizercloud-cache.<NEW_VERSION>.tar
docker load -i apinizercloud-portal.<NEW_VERSION>.tar
docker load -i apinizercloud-integration.<NEW_VERSION>.tar

2.2.1.2) Containerd Usage

# All images required for upgrade are pulled from online server
ctr image pull docker.io/apinizercloud/apimanager:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/worker:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/cache:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/apiportal:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/integration:<NEW_VERSION>

# To transfer relevant images to offline servers, images are saved in `.tar` format on online server
ctr images export apinizercloud-apimanager.tar docker.io/apinizercloud/apimanager:<NEW_VERSION>
ctr images export apinizercloud-worker.tar docker.io/apinizercloud/worker:<NEW_VERSION>
ctr images export apinizercloud-cache.tar docker.io/apinizercloud/cache:<NEW_VERSION>
ctr images export apinizercloud-apiportal.tar docker.io/apinizercloud/apiportal:<NEW_VERSION>
ctr images export apinizercloud-integration.tar docker.io/apinizercloud/integration:<NEW_VERSION>

# Each image is transferred to offline kubernetes worker servers
scp docker.io-apinizercloud-*.tar <OFFLINE_MACHINE_USER>@<OFFLINE_MACHINE_IP>:<TARGET_DIRECTORY>

# Images are loaded on each offline server
ctr images import apinizercloud-apimanager.tar
ctr images import apinizercloud-worker.tar
ctr images import apinizercloud-cache.tar
ctr images import apinizercloud-apiportal.tar
ctr images import apinizercloud-integration.tar

2.2.2) Using Local Image Registry or Repository

Although different image registries and repositories work with different methods, in most of them, pulled images must be tagged and sent to the application.

bilgi

If the application is used as a reverse proxy, it is sufficient to provide the necessary definition for the apinizercloud repo at hub.docker.com.

2.2.2.1) Docker Usage

# All required images are pulled
docker pull apinizercloud/apimanager:<NEW_VERSION>
docker pull apinizercloud/worker:<NEW_VERSION>
docker pull apinizercloud/cache:<NEW_VERSION>
docker pull apinizercloud/apiportal:<NEW_VERSION>
docker pull apinizercloud/integration:<NEW_VERSION>

# Pulled images are retagged with necessary tag information
docker tag apinizercloud/apimanager:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/apimanager:<NEW_VERSION>
docker tag apinizercloud/worker:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/worker:<NEW_VERSION>
docker tag apinizercloud/cache:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/cache:<NEW_VERSION>
docker tag apinizercloud/apiportal:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/apiportal:<NEW_VERSION>
docker tag apinizercloud/integration:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/integration:<NEW_VERSION>

# Images are transferred to organization's local image registry:
docker push <LOCAL_REGISTRY>/apinizercloud/apimanager:<NEW_VERSION>
docker push <LOCAL_REGISTRY>/apinizercloud/worker:<NEW_VERSION>
docker push <LOCAL_REGISTRY>/apinizercloud/cache:<NEW_VERSION>
docker push <LOCAL_REGISTRY>/apinizercloud/apiportal:<NEW_VERSION>
docker push <LOCAL_REGISTRY>/apinizercloud/integration:<NEW_VERSION>

2.2.2.2) Containerd Usage

# All required images are pulled
ctr image pull docker.io/apinizercloud/apimanager:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/worker:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/cache:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/apiportal:<NEW_VERSION>
ctr image pull docker.io/apinizercloud/integration:<NEW_VERSION>

# Pulled images are retagged with necessary tag information
ctr image tag docker.io/apinizercloud/apimanager:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/apimanager:<NEW_VERSION>
ctr image tag docker.io/apinizercloud/worker:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/worker:<NEW_VERSION>
ctr image tag docker.io/apinizercloud/cache:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/cache:<NEW_VERSION>
ctr image tag docker.io/apinizercloud/apiportal:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/apiportal:<NEW_VERSION>
ctr image tag docker.io/apinizercloud/integration:<NEW_VERSION> <LOCAL_REGISTRY>/apinizercloud/integration:<NEW_VERSION>

# Images are transferred to organization's local image registry:
ctr images push <LOCAL_REGISTRY>/apinizercloud/apimanager:<NEW_VERSION>
ctr images push <LOCAL_REGISTRY>/apinizercloud/worker:<NEW_VERSION>
ctr images push <LOCAL_REGISTRY>/apinizercloud/cache:<NEW_VERSION>
ctr images push <LOCAL_REGISTRY>/apinizercloud/apiportal:<NEW_VERSION>
ctr images push <LOCAL_REGISTRY>/apinizercloud/integration:<NEW_VERSION>

2.2.3) Apinizer Api Manager Update

uyarı

Apinizer Api Manager must be updated before updating other Apinizer components.

After Api Manager makes updates to the database, other Apinizer applications need to be fed from the database with current settings.

Therefore, after Api Manager is updated, make sure that Api Manager pods on Kubernetes are in "ready" status and then update other components.

Commands in this and subsequent steps are run on servers with Kubernetes Control Plane task.

Check deployment information

kubectl get deployments -Ao wide

Update Api Manager deployment image

kubectl set image deployment/<MANAGER_DEPLOYMENT_NAME> -n <MANAGER_NAMESPACE> <MANAGER_CONTAINER_NAME>=<LOCAL_REGISTRY>/apinizercloud/apimanager:<NEW_VERSION>

Monitor pod status

Wait for the pod to be READY, monitor pod status:

kubectl get pods -n <MANAGER_NAMESPACE>
kubectl logs -f -n <MANAGER_NAMESPACE> <POD_NAME>

2.2.4) Apinizer Worker and Cache Update

After ensuring that the Apinizer Api Manager image is updated, Apinizer Worker and Cache applications are updated.

Update Worker and Cache deployment images

kubectl set image deployment/<WORKER_DEPLOYMENT_NAME> -n <WORKER_CACHE_NAMESPACE> <WORKER_CONTAINER_NAME>=<LOCAL_REGISTRY>/apinizercloud/worker:<NEW_VERSION>
kubectl set image deployment/<CACHE_DEPLOYMENT_NAME> -n <WORKER_CACHE_NAMESPACE> <CACHE_CONTAINER_NAME>=<LOCAL_REGISTRY>/apinizercloud/cache:<NEW_VERSION>

Monitor pod status

Wait for pods to be READY, monitor pod status:

kubectl get pods -n <WORKER_CACHE_NAMESPACE>
kubectl logs -f -n <WORKER_CACHE_NAMESPACE> <POD_NAME>

2.2.5) Apinizer Portal and Integration Update

Apinizer Portal and Integration can be updated similarly.

Update Portal and Integration deployment images

kubectl set image deployment/<PORTAL_DEPLOYMENT_NAME> -n <PORTAL_NAMESPACE> <PORTAL_CONTAINER_NAME>=<LOCAL_REGISTRY>/apinizercloud/apiportal:<NEW_VERSION>
kubectl set image deployment/<INTEGRATION_DEPLOYMENT_NAME> -n <INTEGRATION_NAMESPACE> <INTEGRATION_CONTAINER_NAME>=<LOCAL_REGISTRY>/apinizercloud/integration:<NEW_VERSION>

Monitor pod statuses

Wait for pods to be READY, monitor pod statuses:

kubectl get pods -n <PORTAL_NAMESPACE>
kubectl get logs -f -n <PORTAL_NAMESPACE> <POD_NAME>
kubectl get pods -n <INTEGRATION_NAMESPACE>
kubectl get logs -f -n <INTEGRATION_NAMESPACE> <POD_NAME>

Helm-installed Apinizer modules are upgraded with helm upgrade. In this flow only the image version (image.tag) changes; all other values are preserved from the existing release via --reuse-values.

uyarı

API Manager must be upgraded before the other components. API Manager runs the database (Mongock) migrations; upgrade the other modules only after its pods are Ready.

2.1) Online Update (Helm)

The chart and version (--version 0.2.0) stay the same for each module; only the new image tag is provided:

Upgrade API Manager

helm upgrade apimanager oci://registry-1.docker.io/apinizercloud/apinizer-apimanager \
  --version 0.2.0 --reuse-values \
  -n <API-Manager-Namespace> \
  --set image.tag="<NEW_VERSION>"

Wait until the pods are Ready:

kubectl -n <API-Manager-Namespace> rollout status deploy/apimanager

Upgrade Worker and Cache

helm upgrade worker oci://registry-1.docker.io/apinizercloud/apinizer-worker \
  --version 0.2.0 --reuse-values -n <Worker-Namespace> --set image.tag="<NEW_VERSION>"

helm upgrade cache oci://registry-1.docker.io/apinizercloud/apinizer-cache \
  --version 0.2.0 --reuse-values -n <Cache-Namespace> --set image.tag="<NEW_VERSION>"

Upgrade Integration and API Portal

helm upgrade integration oci://registry-1.docker.io/apinizercloud/apinizer-integration \
  --version 0.2.0 --reuse-values -n <Integration-Namespace> --set image.tag="<NEW_VERSION>"

helm upgrade portal oci://registry-1.docker.io/apinizercloud/apinizer-apiportal \
  --version 0.2.0 --reuse-values -n <API-Portal-Namespace> --set image.tag="<NEW_VERSION>"

not

--reuse-values keeps all values of the existing release; --set image.tag changes only the image version. Release names and namespaces must match the installation (each module in the namespace you used at install time).

2.2) Verification

helm list -n <NAMESPACE>     # repeat for each module's namespace
kubectl -n <NAMESPACE> get pods

2.3) Offline / Local Registry

If the cluster has no internet access, images are moved to a local registry (see the offline image-transfer steps in the Kubernetes tab above). When using a local registry, provide the repository together with the image tag:

helm upgrade apimanager oci://registry-1.docker.io/apinizercloud/apinizer-apimanager \
  --version 0.2.0 --reuse-values -n <API-Manager-Namespace> \
  --set image.repository=<LOCAL_REGISTRY>/apinizercloud/apimanager \
  --set image.tag="<NEW_VERSION>"

2.4) Rollback (Helm Rollback)

Helm stores every upgrade as a revision; you can return to a previous revision if needed:

helm history apimanager -n <API-Manager-Namespace>
helm rollback apimanager <REVISION> -n <API-Manager-Namespace>
kubectl -n <API-Manager-Namespace> rollout status deploy/apimanager

uyarı

Mongock migrations are forward-only. If the new version changed the DB schema, a rollback may prevent the old Manager from booting; always back up MongoDB before major upgrades (see section 1) and, if needed, apply the restore steps in section 3.

Apinizer Docker images are immutable — to move to a new version, pull the new tag and recreate the container. Some modules (Cache, Integration, Worker) are stateful and need a rolling-upgrade pattern.

bilgi

For the version strategy: Docker Overview — tag convention

2.1) Quick Reference

NEW=2026.04.6
docker pull apinizercloud/<module>:${NEW}

# docker-compose:
# 1) update the image tag in compose.yml
# 2) docker compose up -d <service>

# vanilla docker:
docker stop <container-name> && docker rm <container-name>
docker run -d --name <container-name> ... apinizercloud/<module>:${NEW}

2.2) Recommended Upgrade Order

MongoDB (if required — see MongoDB Upgrade)
API Manager — Mongock migrations run and update the schema
Cache (rolling — one node at a time)
Worker (rolling — one replica at a time; behind LB)
Integration (rolling — wait for the Quartz cluster check-in cycle)
API Portal — stateless, simple replace

2.3) Per-Module Details

API Manager

The Manager runs Mongock migrations, but you do not need to scale down to a single instance — the new Manager can start while the old one is still up. Migrations are idempotent.

docker pull apinizercloud/apimanager:${NEW}
docker compose up -d apimanager      # tag bumped in compose.yml
docker compose logs -f apimanager    # "Mongock finished" then "Started ApinizerManagerApp"

The first start can take 30–90 seconds for Mongock migrations.

uyarı

Back up MongoDB before major version jumps. Major version chains (e.g. 2026.04.x → 2026.05.x → 2026.06.x) must be stepped through one at a time, watching Mongock logs at each step.

Cache (rolling upgrade)

Cache nodes form a Hazelcast cluster — upgrade one node at a time:

docker pull apinizercloud/cache:${NEW}

# Node 1
docker stop -t 30 apinizer-cache-1 && docker rm apinizer-cache-1
docker run -d --name apinizer-cache-1 ... apinizercloud/cache:${NEW}

# Wait for 'Members {size:3, ver:N}' to appear again
docker logs apinizer-cache-1 | grep -E 'Members \{'

# Then node 2, then node 3...

The cluster keeps serving with one node missing (replication factor ≥ 1).

Worker

For Workers behind a load balancer, do a canary / blue-green replace:

docker pull apinizercloud/worker:${NEW}

# Take one replica out of the LB
# Replace the container
docker stop -t 60 apinizer-worker-1 && docker rm apinizer-worker-1
docker run -d --name apinizer-worker-1 ... apinizercloud/worker:${NEW}

# Once healthy, add it back to the LB
# Roll the remaining replicas

uyarı

docker stop -t 60 is required — in-flight HTTP / gRPC / WebSocket requests drain up to 60 s.

Integration (clustered Quartz)

Integration nodes form a cluster over MongoDB — while one node restarts, the others take over its triggers:

docker pull apinizercloud/integration:${NEW}

# Node 1
docker stop -t 120 apinizer-integration-1 && docker rm apinizer-integration-1
docker run -d --name apinizer-integration-1 ... apinizercloud/integration:${NEW}

# Wait for 'Quartz Scheduler Prod Environment Setup started'
# Then node 2, then node 3...

stop -t 120 is required — waitForJobsToCompleteOnShutdown=true lets in-flight jobs drain.

API Portal

Stateless — a simple recreate is enough:

docker pull apinizercloud/apiportal:${NEW}
docker compose up -d apiportal       # tag bumped

For multiple replicas, replace each one in turn behind the LB.

2.4) Troubleshooting

New Manager fails to boot: `Mongock lock acquired by another instance`

The old Manager was SIGKILLed before releasing the Mongock lock. In the Manager DB:

use apinizer
db.mongockLock.deleteMany({})

After clearing the lock, restart the Manager.

Worker on the new version cannot bind to the Environment

A major version may have changed the Environment schema. Check the Manager logs and verify the Environment is on the correct schema.

`image is being used by container` error in compose

docker compose up -d does not recreate the container unless the tag changes. Force:

docker compose up -d --force-recreate <service>

For Linux / VM installations the upgrade flow is: download the new tarball, extract next to the existing install, copy conf/application.env and conf/master.key over, re-register the systemd unit, restart the service.

bilgi

The conf/master.key file must not be lost — it is the only key that decrypts ENC(...) values. Always back it up before swapping versions.

2.1) Quick Reference

NEW=2026.04.6
sudo systemctl stop apinizer-<module>
sudo tar -xzf apinizer-<module>-${NEW}-linux-x64.tar.gz -C /opt
sudo cp /opt/apinizer-<module>/conf/application.env /opt/apinizer-<module>-${NEW}/conf/
sudo cp /opt/apinizer-<module>/conf/master.key      /opt/apinizer-<module>-${NEW}/conf/
sudo chown -R apinizer:apinizer /opt/apinizer-<module>-${NEW}/conf
sudo chmod 600 /opt/apinizer-<module>-${NEW}/conf/application.env
sudo chmod 400 /opt/apinizer-<module>-${NEW}/conf/master.key
sudo mv /opt/apinizer-<module> /opt/apinizer-<module>.bak
sudo mv /opt/apinizer-<module>-${NEW} /opt/apinizer-<module>
sudo /opt/apinizer-<module>/bin/<module>-install.sh    # re-register systemd unit
sudo systemctl start apinizer-<module>
sudo systemctl status apinizer-<module>
# After healthy:
sudo rm -rf /opt/apinizer-<module>.bak

2.2) Recommended Upgrade Order

MongoDB (if required)
API Manager — Mongock migrations
Cache — rolling, one node at a time
Worker — rolling behind LB
Integration — clustered Quartz, rolling
API Portal — stateless

2.3) Per-Module

API Manager

NEW=2026.04.6
sudo systemctl stop apinizer-apimanager

# Back up
sudo cp /opt/apinizer-manager/conf/application.env ~/manager-env-pre-${NEW}.bak
sudo cp /opt/apinizer-manager/conf/master.key      ~/manager-key-pre-${NEW}.bak

# Extract new package
curl -fSLO "https://packages.apinizer.com/apinizer-packages/apimanager/${NEW}/apinizer-apimanager-${NEW}-linux-x64.tar.gz"
sudo tar -xzf apinizer-apimanager-${NEW}-linux-x64.tar.gz -C /opt

# Move config
sudo cp /opt/apinizer-manager/conf/application.env /opt/apinizer-apimanager-${NEW}/conf/
sudo cp /opt/apinizer-manager/conf/master.key      /opt/apinizer-apimanager-${NEW}/conf/
sudo chown -R apinizer:apinizer /opt/apinizer-apimanager-${NEW}/conf
sudo chmod 600 /opt/apinizer-apimanager-${NEW}/conf/application.env
sudo chmod 400 /opt/apinizer-apimanager-${NEW}/conf/master.key

# Swap + reinstall
sudo mv /opt/apinizer-manager /opt/apinizer-manager.bak
sudo mv /opt/apinizer-apimanager-${NEW} /opt/apinizer-manager
sudo /opt/apinizer-manager/bin/apimanager-install.sh
sudo systemctl start apinizer-apimanager
sudo journalctl -u apinizer-apimanager -f          # watch Mongock log

The first start can take 30–90 s for Mongock. After Started ApinizerManagerApp:

curl -fsS http://127.0.0.1:8080/management/health
# If healthy:
sudo rm -rf /opt/apinizer-manager.bak

Cache (rolling upgrade)

Cache nodes are stateful Hazelcast members — upgrade one at a time:

# On node 1:
sudo systemctl stop apinizer-apicache
# (same flow as Manager: extract tarball, move conf, install, start)
# Then move to node 2 — wait for 'Members {size:3, ver:N}' in the log

The cluster keeps serving while one node is missing.

Worker

Roll each replica behind the LB in turn:

# Take replica 1 out of LB
sudo systemctl stop apinizer-apiworker     # SIGTERM + 60 s drain
# (tarball swap flow)
sudo systemctl start apinizer-apiworker
curl -fsS http://127.0.0.1:8091/server-status
# Healthy → add back to LB, move to replica 2

Integration

Quartz cluster check-in is 7.5 s — while one node restarts, the others take over its triggers:

sudo systemctl stop apinizer-apiintegration    # SIGTERM + waitForJobsToCompleteOnShutdown drain
# (tarball swap flow)
sudo systemctl start apinizer-apiintegration
sudo journalctl -u apinizer-apiintegration -f  # wait for 'Quartz Scheduler Prod Environment Setup started'

API Portal

Stateless — simple swap:

sudo systemctl stop apinizer-apiportal
# tarball swap
sudo systemctl start apinizer-apiportal

2.4) Troubleshooting

Service exits with "is not set" from the new package

The conf/application.env move step was skipped or permissions are broken. Manual check:

ls -la /opt/apinizer-<module>/conf/
# application.env must be mode 600 and owned by apinizer:apinizer
# master.key must be mode 400 and owned by apinizer:apinizer

"Master key file not found" at boot

master.key was not moved. Restore from backup:

sudo cp ~/manager-key-pre-${NEW}.bak /opt/apinizer-manager/conf/master.key
sudo chown apinizer:apinizer /opt/apinizer-manager/conf/master.key
sudo chmod 400 /opt/apinizer-manager/conf/master.key
sudo systemctl restart apinizer-apimanager

`Mongock lock acquired by another instance`

The previous Manager was killed before it could release the lock. In MongoDB:

use apinizer
db.mongockLock.deleteMany({})

Then restart the Manager.

3) Rolling Back Apinizer Application Updates

Version downgrade is not supported in Apinizer applications. However, if there are database backups, an updated version can be rolled back.

uyarı

When updates need to be rolled back for any reason, the first thing to do is check that MongoDB backup was taken before the update. If there is no database backup taken before the update, there is no way to roll back the changes Api Manager application will make to the database, so if there is a system backup of the database servers, you can return to the most recent backup at that date and return to that version.

This operation will cause loss of changes made since that date, so it should be done carefully. Since structural differences may occur with the update, this operation can only be considered for reference purposes.

3.1) MongoDB Database Restore

Before this operation, it should be confirmed that the Api Manager application is not in a restart loop. For the safest method, the Api Manager application should be stopped.

Kubernetes
Docker
Virtual Server

Stop Api Manager

Api Manager replica count is reduced to 0 and all pods are shut down:

kubectl scale deploy <MANAGER_DEPLOYMENT_NAME> -n <MANAGER_NAMESPACE> --replicas=0

Restore MongoDB backup

MongoDB should be returned to the most recent backup. The --drop parameter can be used to prevent possible conflicts during return. This will only drop collections that have a counterpart in the backup file and then perform the load.

Stop Api Manager container

docker compose down
# or: docker stop -t 60 apinizer-apimanager && docker rm apinizer-apimanager

Restore MongoDB backup

Stop Api Manager service

sudo systemctl stop apinizer-apimanager

Restore MongoDB backup

not

For detailed information, the MongoDB Database Backup and Restore page can be reviewed.

3.2) Rolling Back Api Manager Application Version

Kubernetes
Helm
Docker
Virtual Server

not

If a local registry will be used during rollback, commands should be updated accordingly.

Roll back Api Manager deployment image to old version

kubectl set image deployment/<MANAGER_DEPLOYMENT_NAME> -n <MANAGER_NAMESPACE> <MANAGER_CONTAINER_NAME>=apinizercloud/apimanager:<OLD_VERSION>

Increase replica count to 1

kubectl scale deploy <MANAGER_DEPLOYMENT_NAME> -n <MANAGER_NAMESPACE> --replicas=1

Monitor pod status

Wait for the pod to be READY, monitor pod status and logs:

kubectl get pods -n <MANAGER_NAMESPACE>
kubectl logs -f -n <MANAGER_NAMESPACE> <POD_NAME>

Roll back to the previous revision

Helm stores every upgrade as a revision; use helm history to pick the target revision and roll back to it:

helm history apimanager -n <API-Manager-Namespace>
helm rollback apimanager <REVISION> -n <API-Manager-Namespace>

Monitor pod status

Wait for the pod to be Ready:

kubectl -n <API-Manager-Namespace> rollout status deploy/apimanager
kubectl -n <API-Manager-Namespace> get pods

Stop the new Manager container

docker compose down
# or: docker stop -t 60 apinizer-apimanager && docker rm apinizer-apimanager

Revert compose.yml to the old tag

Update the image tag for the Manager service in your docker-compose.yml file to the previous version.

Start the old Manager

docker compose up -d apimanager
docker compose logs -f apimanager

Stop the new Manager

sudo systemctl stop apinizer-apimanager

Restore the previous installation

sudo mv /opt/apinizer-manager /opt/apinizer-manager.failed
sudo mv /opt/apinizer-manager.bak /opt/apinizer-manager
sudo /opt/apinizer-manager/bin/apimanager-install.sh

Start the old Manager

sudo systemctl start apinizer-apimanager
sudo systemctl status apinizer-apimanager

3.3) Rolling Back Other Applications' Versions

When the Api Manager application is running, other applications can be rolled back to the old version together.

Kubernetes
Helm
Docker
Virtual Server

not

If a local registry will be used during rollback, commands should be updated accordingly.

Roll back deployment images to old version

kubectl set image deployment/<WORKER_DEPLOYMENT_NAME> -n <WORKER_CACHE_NAMESPACE> <WORKER_CONTAINER_NAME>=apinizercloud/worker:<OLD_VERSION>
kubectl set image deployment/<CACHE_DEPLOYMENT_NAME> -n <WORKER_CACHE_NAMESPACE> <CACHE_CONTAINER_NAME>=apinizercloud/cache:<OLD_VERSION>
kubectl set image deployment/<PORTAL_DEPLOYMENT_NAME> -n <PORTAL_NAMESPACE> <PORTAL_CONTAINER_NAME>=apinizercloud/apiportal:<OLD_VERSION>
kubectl set image deployment/<INTEGRATION_DEPLOYMENT_NAME> -n <INTEGRATION_NAMESPACE> <INTEGRATION_CONTAINER_NAME>=apinizercloud/integration:<OLD_VERSION>

Check pod statuses

Wait for pods to be READY, monitor pod statuses and logs if necessary:

kubectl get pods -A

Roll back the other modules to their previous revisions

For each module, find the target revision with helm history <release> -n <namespace> and roll back:

helm rollback worker      <REVISION> -n <Worker-Namespace>
helm rollback cache       <REVISION> -n <Cache-Namespace>
helm rollback integration <REVISION> -n <Integration-Namespace>
helm rollback portal      <REVISION> -n <API-Portal-Namespace>

Check pod statuses

kubectl get pods -A

Update compose.yml with old tags

Revert the image tags for Worker, Cache, Portal, and Integration to their previous versions.

Recreate the containers

docker compose up -d worker cache apiportal integration
docker compose logs -f

Restore each module from .bak directory

For each module (Worker, Cache, Integration, Portal):

sudo systemctl stop apinizer-<module>
sudo mv /opt/apinizer-<module> /opt/apinizer-<module>.failed
sudo mv /opt/apinizer-<module>.bak /opt/apinizer-<module>
sudo /opt/apinizer-<module>/bin/<module>-install.sh
sudo systemctl start apinizer-<module>

Verify all modules are healthy

sudo systemctl status apinizer-apiworker
sudo systemctl status apinizer-apicache
sudo systemctl status apinizer-apiintegration
sudo systemctl status apinizer-apiportal

uyarı

Mongock migrations are forward-only. If the new version changed the DB schema, rolling back may prevent the old Manager from booting. Back up MongoDB before major upgrades.

Update Methods​

1) Take a MongoDB Backup​

2) Updating Apinizer Applications​

Update Strategy and Downtime Risk​

2.1) Online Update​

2.1.1) Apinizer Api Manager Update​

2.1.2) Apinizer Worker and Cache Update​

2.1.3) Apinizer Portal and Integration Update​

2.2) Offline Update​

2.2.1) Pulling Images from Online Server and Transferring to Offline Servers​

2.2.1.1) Docker Usage​

2.2.1.2) Containerd Usage​

2.2.2) Using Local Image Registry or Repository​

2.2.2.1) Docker Usage​

2.2.2.2) Containerd Usage​

2.2.3) Apinizer Api Manager Update​

2.2.4) Apinizer Worker and Cache Update​

2.2.5) Apinizer Portal and Integration Update​

2.1) Online Update (Helm)​

2.2) Verification​

2.3) Offline / Local Registry​

2.4) Rollback (Helm Rollback)​

2.1) Quick Reference​

2.2) Recommended Upgrade Order​

2.3) Per-Module Details​

API Manager​

Cache (rolling upgrade)​

Worker​

Integration (clustered Quartz)​

API Portal​

2.4) Troubleshooting​

New Manager fails to boot: Mongock lock acquired by another instance​

Worker on the new version cannot bind to the Environment​

image is being used by container error in compose​

2.1) Quick Reference​

2.2) Recommended Upgrade Order​

2.3) Per-Module​

API Manager​

Cache (rolling upgrade)​

Worker​

Integration​

API Portal​

2.4) Troubleshooting​

Service exits with "is not set" from the new package​

"Master key file not found" at boot​

Mongock lock acquired by another instance​

3) Rolling Back Apinizer Application Updates​

3.1) MongoDB Database Restore​

3.2) Rolling Back Api Manager Application Version​

3.3) Rolling Back Other Applications' Versions​

Update Methods

1) Take a MongoDB Backup

2) Updating Apinizer Applications

Update Strategy and Downtime Risk

2.1) Online Update

2.1.1) Apinizer Api Manager Update

2.1.2) Apinizer Worker and Cache Update

2.1.3) Apinizer Portal and Integration Update

2.2) Offline Update

2.2.1) Pulling Images from Online Server and Transferring to Offline Servers

2.2.1.1) Docker Usage

2.2.1.2) Containerd Usage

2.2.2) Using Local Image Registry or Repository

2.2.2.1) Docker Usage

2.2.2.2) Containerd Usage

2.2.3) Apinizer Api Manager Update

2.2.4) Apinizer Worker and Cache Update

2.2.5) Apinizer Portal and Integration Update

2.1) Online Update (Helm)

2.2) Verification

2.3) Offline / Local Registry

2.4) Rollback (Helm Rollback)

2.1) Quick Reference

2.2) Recommended Upgrade Order

2.3) Per-Module Details

API Manager

Cache (rolling upgrade)

Worker

Integration (clustered Quartz)

API Portal

2.4) Troubleshooting

New Manager fails to boot: `Mongock lock acquired by another instance`

Worker on the new version cannot bind to the Environment

`image is being used by container` error in compose

2.1) Quick Reference

2.2) Recommended Upgrade Order

2.3) Per-Module

API Manager

Cache (rolling upgrade)

Worker

Integration

API Portal

2.4) Troubleshooting

Service exits with "is not set" from the new package

"Master key file not found" at boot

`Mongock lock acquired by another instance`

3) Rolling Back Apinizer Application Updates

3.1) MongoDB Database Restore

3.2) Rolling Back Api Manager Application Version

3.3) Rolling Back Other Applications' Versions