How to Upgrade the Apache Tomcat in miniOrange On-Premise IAM

This guide explains how to upgrade the Apache Tomcat engine bundled with the miniOrange On-Premise Identity Provider / IAM installation from one 9.0.x release to another (for example 9.0.108 → 9.0.120), without losing application data, configuration, or customizations.

Prerequisites

Ensure the following before starting the Tomcat upgrade:

Requirement	Windows	Linux
Access	Administrator access (elevated Command Prompt)	Root or sudo access
Tomcat package	Apache Tomcat 9.0.x Windows zip from the official archive	Apache Tomcat 9.0.x tar.gz from the official archive
Maintenance window	Required — the Identity Provider service will restart and briefly deregister from Eureka
Disk space	Enough free space for a full backup of the install directory
Dependent services	Stop miniOrange Redis and RabbitMQ before backup (IAM version 4.9.3 or later)
Additional	-	Correct file ownership after copying as root

Windows
Linux

Step 1: Discover the service configuration

Identify the service and confirm it is a procrun daemon:
```
sc qc miniorange
```

Locate the procrun registry key. On 64-bit Windows a 32-bit-registered daemon lives under WOW6432Node - check both hives:

# 1) reg query "HKLM\SOFTWARE\Apache Software Foundation\Procrun 2.0\miniorange\Parameters\Java"
# 2) reg query "HKLM\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\miniorange\Parameters\Java"

If both fail, search for the actual key path:

reg query "HKLM\SOFTWARE" /f "miniorange" /s /k

Record every value under the Java subkey (Jvm, Options, Options9, Classpath, JvmMs, JvmMx). Also record the Log subkey (Path, Prefix, StdOutput, StdError) — this controls the daemon's own stdout/stderr capture and is easy to lose during a re-registration:
```
reg query "HKLM\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\miniorange\Parameters\Log"
```

Step 2: Back up everything

Stop the miniOrange service:
```
net stop miniorange
```
Create a backup folder:
```
mkdir C:\Backups
```

Archive the Identity Provider install directory:

powershell -Command "Compress-Archive -Path 'C:\Program Files\miniOrange Identity Provider' -DestinationPath 'C:\Backups\moas_backup.zip'"

Export the service registry configuration:

reg export "HKLM\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\miniorange" "C:\Backups\service_config.reg" /y

Warning:
Stop all the services before backing up, including miniOrange Redis and RabbitMQ (required for IAM version 4.9.3 or later).

Step 3: Assemble the new version

Start from a clean extraction of the new Tomcat and bring your application into it. This guarantees every new engine file is present:

Rename the old miniOrange Identity Provider (current working directory) to any other name.
Extract the new Tomcat to the same miniOrange working location and rename it to miniOrange Identity Provider.
Replace conf\server.xml from the old directory into the new Apache directory.
Move the application and vendor pieces from the current install into the new folder: logs, moas, services, temp, uninstall, work, license.txt, and the miniorange.ico file.

Create a copy of the new bin\tomcat9.exe to bin\miniOrange.exe:

copy "C:\Program Files\miniOrange Identity Provider\bin\tomcat9.exe" "C:\Program Files\miniOrange Identity Provider\bin\miniOrange.exe" /Y

Note:
Keeping the final path identical: The registry stores the install path as literal text (catalina.home / catalina.base). If the final directory name and path match the original exactly, no registry path edits are needed — the service simply launches the new engine from the same location.

Step 4: Re-register the service

Uninstall the old registration first - use a daemon binary that still exists:
```
"<Old_InstallDir>\bin\miniorange.exe" //DS//miniorange
```
Confirm it reports that the service does not exist:
```
sc query miniorange
```

Re-register using the exact values recorded in Step 1 (note the Log parameters are folded in so the daemon log key is not lost):

"C:\Program Files\miniOrange Identity Provider\bin\miniorange.exe" //IS//miniorange ^
--DisplayName="miniOrange Identity Provider" ^
--Description="Identity Provider Authentication Server" ^
--Install="C:\Program Files\miniOrange Identity Provider\bin\miniorange.exe" ^
--Jvm="<path-to-jvm.dll>" ^
--Classpath="C:\Program Files\miniOrange Identity Provider\bin\bootstrap.jar;C:\Program Files\miniOrange Identity Provider\bin\tomcat-juli.jar" ^
--StartMode=jvm --StartClass=org.apache.catalina.startup.Bootstrap --StartParams=start ^
--StartPath="C:\Program Files\miniOrange Identity Provider" ^
--StopMode=jvm --StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop ^
--StopPath="C:\Program Files\miniOrange Identity Provider" ^
--JvmOptions="-Dcatalina.home=C:\Program Files\miniOrange Identity Provider;-Dcatalina.base=C:\Program Files\miniOrange Identity Provider;-Djava.io.tmpdir=C:\Program Files\miniOrange Identity Provider\temp;-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;-Djava.util.logging.config.file=C:\Program Files\miniOrange Identity Provider\conf\logging.properties;-Dspring.profiles.active=redis" ^
++JvmOptions9="--add-opens=java.base/java.lang=ALL-UNNAMED;--add-opens=java.base/java.io=ALL-UNNAMED;--add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED" ^
--JvmMs=256 --JvmMx=1024 ^
--LogPath="C:\Program Files\miniOrange Identity Provider\logs" --LogPrefix=commons-daemon ^
--StdOutput=auto --StdError=auto ^
--Startup=auto

Set the logon account to match the original (commonly Local Service):
```
sc config miniorange obj= "NT AUTHORITY\LocalService" password= ""
```

Note:
A warning such as Failed to grant service user write permissions to log path … during install is harmless - it concerns procrun's own diagnostic log location, not Tomcat or the application.

Step 5: Start dependencies, then the service

Navigate to Windows Services and start all the services. List all miniOrange services and start any that should be running:

Windows Services showing miniOrange services being started

powershell -Command "Get-Service | Where-Object {$_.DisplayName -like '*miniOrange*'} | Format-Table Name, Status, StartType -AutoSize"

Step 6: Verify

Check the Tomcat version banner in the container log — this is written by Tomcat itself and is the reliable place to confirm the version. Do not expect it in the application's own log (e.g. catalina-moas.out), which is produced by the application's logging framework and does not capture Tomcat's startup lines:
```
findstr /i "Server version name" "C:\Program Files\miniOrange Identity Provider\logs\catalina.<date>.log"
```

On Linux, miniOrange typically runs Tomcat under systemd. The service configuration lives in the unit file and, often, in bin/setenv.sh.

Note:

<ver> - Write miniOrange IAM version instead of this tag (e.g. 5.2.0).
<NewTomcatVer> - Write Apache Tomcat latest version instead of this tag (e.g. 9.0.120).

Step 1: Discover the service configuration

Confirm the install path, the symlink target, the running Tomcat, and the service configuration:

See the latest symlink and its target:
```
ls -la /opt/tomcat/
```
Resolve the real versioned folder:
```
readlink -f /opt/tomcat/latest
```
Running JVM: CATALINA_HOME, classpath, opts:
```
ps -ef | grep -i catalina | grep -v grep
```
Tomcat unit (ExecStart via catalina.sh):
```
systemctl cat mo-idp-miniorange.service
```
Shared env: MO_IDP_FOLDER, config/log paths:
```
cat /etc/mo-idp-server.env
```

Confirm the Tomcat unit uses ${MO_IDP_FOLDER} (pointing at the symlink) and that other services launch their JARs from ${MO_IDP_FOLDER}/services/*.jar - this is why re-pointing the symlink upgrades the whole stack at once.

Step 2: Back up the current install

Create a backup archive of the current install:

sudo tar -czf /opt/mo-idp-backup-<ver>-$(date +%Y%m%d).tar.gz \
-C /opt/tomcat --exclude='mo-idp-server-<ver>/services/logs' mo-idp-server-<ver>

Confirm the backup file was created:

ls -lh /opt/mo-idp-backup-<ver>-*.tar.gz

Verify the archive is valid:

sudo tar -tzf /opt/mo-idp-backup-<ver>-*.tar.gz > /dev/null && echo 'Archive OK'

Note: Excluding services/logs keeps the backup small (logs are disposable). Drop the --exclude for a full archive.

Step 3: Download and extract the new Tomcat

Go to the Tomcat directory:
```
cd /opt/tomcat
```

Download the new Tomcat package:

sudo wget https://archive.apache.org/dist/tomcat/tomcat-9/v<NewTomcatVer>/bin/apache-tomcat-<NewTomcatVer>.tar.gz

Extract the package:

sudo tar -xzf apache-tomcat-<NewTomcatVer>.tar.gz

Confirm the new folder exists:

ls -la /opt/tomcat/apache-tomcat-<NewTomcatVer>/

Step 4: Migrate data into the new folder (cp -a)

Use cp -a (copy, not move) so the old folder stays intact for instant rollback.

Configuration (preserves your server.xml Context):

sudo cp -a /opt/tomcat/latest/conf/. /opt/tomcat/apache-tomcat-<NewTomcatVer>/conf/

sudo grep -i moas /opt/tomcat/apache-tomcat-<NewTomcatVer>/conf/server.xml   # confirm Context copied

Application, license, runtime dirs:

# 1) sudo cp -a /opt/tomcat/latest/moas        /opt/tomcat/apache-tomcat-<NewTomcatVer>/moas

# 2) sudo cp -a /opt/tomcat/latest/license.txt /opt/tomcat/apache-tomcat-<NewTomcatVer>/license.txt

# 3) optional: carry historical logs / temp / work (or let them regenerate)
sudo rm -rf /opt/tomcat/apache-tomcat-<NewTomcatVer>/logs /opt/tomcat/apache-tomcat-<NewTomcatVer>/temp /opt/tomcat/apache-tomcat-<NewTomcatVer>/work

# 4) sudo cp -a /opt/tomcat/latest/logs /opt/tomcat/apache-tomcat-<NewTomcatVer>/logs

# 5) sudo cp -a /opt/tomcat/latest/temp /opt/tomcat/apache-tomcat-<NewTomcatVer>/temp

# 6) sudo cp -a /opt/tomcat/latest/work /opt/tomcat/apache-tomcat-<NewTomcatVer>/work

Microservice mesh (all JARs, config, certs — excluding bulky service logs):

# 1) sudo mkdir -p /opt/tomcat/apache-tomcat-<NewTomcatVer>/services

# 2) sudo rsync -a --exclude 'logs' \
/opt/tomcat/latest/services/ /opt/tomcat/apache-tomcat-<NewTomcatVer>/services/

# 3) sudo mkdir -p /opt/tomcat/apache-tomcat-<NewTomcatVer>/services/logs

Step 5: Fix ownership and verify

Fix ownership, then verify the JAR count, config/certs, catalina.sh, and disk space:

# 1) sudo chown -R root:root /opt/tomcat/apache-tomcat-<NewTomcatVer>

# 2) verify — JAR count auto-counts, so it matches whatever the mesh contains
sudo find /opt/tomcat/apache-tomcat-<NewTomcatVer>/services/ -maxdepth 1 -name '*.jar' | wc -l

# 3) sudo ls /opt/tomcat/apache-tomcat-<NewTomcatVer>/services/ | grep -E 'config|certs'

# 4) sudo ls /opt/tomcat/apache-tomcat-<NewTomcatVer>/                # bin conf lib logs moas services temp webapps work

# 5) sudo ls -la /opt/tomcat/apache-tomcat-<NewTomcatVer>/bin/catalina.sh   # must exist and be executable

# 6) df -h /opt

Confirm: the JAR count matches your service count, config/certs are present, moas exists, catalina.sh is executable, and disk is not near-full.

Step 6: Stop the stack

Stop all miniOrange services (discovered by pattern), then the infrastructure services:

# 1)MO_SERVICES=$(systemctl list-units 'mo-idp-*.service' --all --no-legend | awk '{print $1}')

# 2) sudo systemctl stop $MO_SERVICES

# 3) sudo systemctl stop nginx.service rabbitmq-server.service redis-server.service

# 4) systemctl list-units --type=service | grep -iE 'orange|redis|rabbit|nginx'   # confirm all stopped

Step 7: Change the symlink

Point the latest symlink at the new Tomcat folder, then confirm the target:

sudo ln -sfn /opt/tomcat/apache-tomcat-<NewTomcatVer> /opt/tomcat/latest

readlink -f /opt/tomcat/latest        # must show the new versioned folder

Step 8: Start the stack (infrastructure and dependencies first)

Bring infrastructure up first, then the registry and config services, then everything else. Seeding Eureka and Config first avoids transient registration failures:

# 1) infrastructure
sudo systemctl start redis-server.service rabbitmq-server.service nginx.service
sudo ss -tlnp | grep -E ':6379|:5672|:80'     # confirm listening

# 2) registry + config first
sudo systemctl start mo-idp-eurekaserver.service mo-idp-configserver.service
sleep 25

# 3) all remaining mo-idp services, discovered by pattern
sudo systemctl start $(systemctl list-unit-files 'mo-idp-*.service' --no-legend | awk '{print $1}')

Step 9: Verify

Check service status, Tomcat version, container logs, and the login endpoint:

# 1) systemctl list-units --type=service | grep -iE 'orange|redis|rabbit|nginx'

# 2) sudo /opt/tomcat/latest/bin/version.sh | grep 'Server version'

# 3) sudo tail -30 /opt/tomcat/latest/logs/catalina.$(date +%Y-%m-%d).log

# 4) curl -I -k https://<miniorange_URL> 2>&1 | head -5

Confirm the banner reads Apache Tomcat/9.0.120 (or your target version).
Confirm every mo-idp service plus nginx, RabbitMQ, and Redis is actively running.
Confirm the login / SSO endpoints respond and render correctly.

Note:
Where to check the version: The version banner appears via bin/version.sh and in logs/catalina.<date>.log written by Tomcat itself. It does not appear in the application's own log (catalina-moas.out).

Step 10: Rollback (instant)

Because the old versioned folder was never modified (cp -a), rollback is a single symlink flip plus a restart:

# 1) sudo systemctl stop $(systemctl list-units 'mo-idp-*.service' --all --no-legend | awk '{print $1}')

# 2) sudo ln -sfn /opt/tomcat/mo-idp-server-<ver> /opt/tomcat/latest

# 3) sudo systemctl start mo-idp-eurekaserver.service mo-idp-configserver.service && sleep 25 && \

# 4) sudo systemctl start $(systemctl list-unit-files 'mo-idp-*.service' --no-legend | awk '{print $1}')

Step 11: Cleanup (after a few days of stability)

Remove the old folder and the downloaded tarball. Keep the backup archive a while longer:

sudo rm -rf /opt/tomcat/mo-idp-server-<ver>            # old folder

sudo rm -f  /opt/tomcat/apache-tomcat-<NewTomcatVer>.tar.gz  # downloaded tarball
# keep /opt/mo-idp-backup-<ver>-*.tar.gz a while longer

Contents

How to Upgrade the Apache Tomcat in miniOrange On-Premise IAM

Prerequisites

Step 1: Discover the service configuration

Step 2: Back up everything

Step 3: Assemble the new version

Step 4: Re-register the service

Step 5: Start dependencies, then the service

Step 6: Verify

Step 1: Discover the service configuration

Step 2: Back up the current install

Step 3: Download and extract the new Tomcat

Step 4: Migrate data into the new folder (cp -a)

Step 5: Fix ownership and verify

Step 6: Stop the stack

Step 7: Change the symlink

Step 8: Start the stack (infrastructure and dependencies first)

Step 9: Verify

Step 10: Rollback (instant)

Step 11: Cleanup (after a few days of stability)

Further References

Want To Schedule A Demo?

Our Other Identity & Access Management Products

Single Sign-On

Multi-factor Authentication

Adaptive Authentication

Lifecycle Management