المُطلِق المنتجات Bitnami التوثيقimaxe CLI المدوّنة اتصل بنا
imaxe.cloud/ imaxe CLI/ الوحدات/ tomcat
imaxe tomcat runtime v1.0.0

Upgrade Tomcat in place, roll back with one command

Installs, upgrades and rolls back Apache Tomcat on the instance without rebuilding the AMI: atomic symlink flip, automatic rollback on healthcheck failure and mandatory Tomcat↔Java matrix — your webapps/, conf/ and logs untouched.

$ imaxe tomcat status
Version
v1.0.0
Subcommands
7
Config
/etc/imaxe/tomcat.yml
Needs root
yes
Branches
9.0 · 10.1 · 11

What this module does #

Apache Tomcat is upgraded, in a stock install, by unpacking a new tarball on top of the old one or by rebuilding the machine. Both approaches are error-prone: the first mixes versions, the second loses the deployed apps.

The tomcat module solves that: it installs each version under its own /opt/tomcat/apache-tomcat-X.Y.Z, versioned and immutable, and flips a current symlink to switch between them. Your webapps/, conf/, lib/ and /var/log/tomcat live in CATALINA_BASE (/var/lib/tomcat) and are never touched by upgrade or rollback. Every install verifies sha512 and PGP signature against the branch KEYS from downloads.apache.org, and the mandatory Tomcat↔Java matrix stops you from running a version on the wrong JVM.

Before you start

Every mutating command needs root (use sudo). Upgrade downtime is seconds — the service is stopped, the symlink flipped and started back up — but the cache in memory is lost on each restart. Cross-major jumps (10→11) are blocked by default because of javax→jakarta; use --allow-major only after you have tested your apps.

Quick guidestep-by-step tasks

Quick guide #

Pick what you want to do. Every recipe comes with the command already written — just copy it and hit Copy.

Check the service status List installed versions Upgrade in place Roll back Run the doctor
1

Check the service status

See the active version, CATALINA_BASE, Java and the rollback target at a glance.

Connect to your instance over SSH with the ubuntu user.

Ask for the status:

terminal
$ sudo imaxe tomcat status

For a dashboard or a script, add --json:

terminal
$ sudo imaxe tomcat status --json
2

List installed versions

See which versions are on disk and which one is active (*).

Local versions:

terminal
$ sudo imaxe tomcat list

Last 10 releases of a branch upstream:

terminal
$ sudo imaxe tomcat list --remote 10.1
3

Upgrade in place

Install the newest release of the active branch, atomic flip, automatic rollback on failure.

Preview without touching anything:

terminal
$ sudo imaxe tomcat upgrade --dry-run

Apply it (downtime measured in seconds):

terminal
$ sudo imaxe tomcat upgrade

Pin the target and clean out work/+temp/:

terminal
$ sudo imaxe tomcat upgrade --to 10.1.30 --clear-work
If the healthcheck fails after the flip, the previous symlink is restored automatically. Exit code 30 means: the new version stayed on disk for you to inspect, and Tomcat is running on the old one.
4

Roll back to the previous version

Flip current back to the previous entry in the history.

terminal
$ sudo imaxe tomcat rollback
Exit code 20 means there is no previous version to roll back to. If you want to jump to a specific installed version, use switch <X.Y.Z>.
5

Run the doctor

Full healthcheck: service, HTTP, matrix, layout, NGINX.

terminal
$ sudo imaxe tomcat doctor
Reports OK/WARN/FAIL for the unit, GET http://127.0.0.1:8080/, the Tomcat↔Java pair, layout permissions, the logs symlink, AJP absent in server.xml, disk space and NGINX on 80/443.
CLI referencecommands, flags and files

Synopsis #

usage
imaxe tomcat <subcommand> [flags]

Every subcommand needs root. Add --json to status, list or doctor for machine-readable output.

Subcommands #

SubcommandWhat it doesRelevant flags
statusActive version, CATALINA_BASE, Java, ports, rollback target.--json
listInstalled versions (marks the active one with *); --remote lists upstream releases of a branch.--json --remote
installInstalls a version. Verifies sha512 and PGP signature, applies the matrix and installs Temurin if needed.--java --force-java
upgradeAtomic upgrade with healthcheck and automatic rollback on failure.--to --keep --clear-work --dry-run --allow-major
switchFlips current to an already-installed version.—
rollbackGoes back to the previous entry in the history.—
doctorFull healthcheck: unit, HTTP, matrix, layout, NGINX.--json

Arguments and flags #

FlagTypeDefaultDescription
--tostringlatest-<branch>In upgrade: target version (X.Y.Z, latest-9, latest-10.1, latest-11).
--javaintmatrixIn install: Temurin version to install; without it, the matrix default.
--force-javaboolfalseAllows a Tomcat↔Java pair outside the matrix. Logged to the state file.
--keepint2How many previous versions to keep after a prune.
--clear-workboolfalseEmpties work/ and temp/ after the flip.
--dry-runboolfalsePrints the plan; does not touch anything.
--allow-majorboolfalseAllows cross-major jumps (10→11, 11→12). Test your apps first: javax→jakarta.
--remotestring—In list: shows the latest releases of the branch on archive.apache.org.
--jsonboolfalseEmits the result as structured JSON on stdout.

Files and paths #

PathContents
/etc/imaxe/tomcat.ymlModule configuration: branch, mirrors, matrix, healthcheck.
/opt/tomcat/apache-tomcat-X.Y.ZVersioned and immutable CATALINA_HOME. One directory per installed release.
/opt/tomcat/currentSymlink pointing at the active release. Every upgrade/rollback flips it atomically.
/var/lib/tomcatCATALINA_BASE: conf/, webapps/, lib/, work/, temp/. Untouched by upgrade/rollback.
/var/log/tomcatLogs (symlinked from /var/lib/tomcat/logs). Own logrotate. catalina.out also captured by journald.
/var/lib/imaxe/state/tomcat/state.jsonState: active version, history, installed Java, matrix escapes.
/var/lib/imaxe/cache/tomcat/keys-<major>.gpgCached branch KEYS ring used by gpgv to verify signatures.

Exit codes and logs #

Every run returns a code you can check with echo $?:

0OKOperation completed successfully.
1USAGEBad usage or a Tomcat↔Java pair outside the matrix.
2VERIFYDownload or sha512/PGP verification failure. No files left behind.
20NOROLLBACKNo previous version to roll back to.
25BADMAJORCross-major jump blocked. Use --allow-major after testing your apps.
30HEALTHHealthcheck failed after the flip. Automatic rollback applied.

Follow the service live while you work:

terminal
$ sudo systemctl status tomcat
$ sudo journalctl -u tomcat -f

Troubleshooting #

SymptomLikely causeFix
Exit 2 on installsha512 or PGP verification failed.Retry: it may be a corrupted mirror. If it happens twice, check keys-<major>.gpg and the target URL in tomcat.yml.
Exit 25 on upgradeCross-major jump blocked (10→11, javax→jakarta).Test your apps and, if OK, re-run with --allow-major.
Exit 30 after upgradeThe healthcheck failed after the symlink flip; module rolled back automatically.Check journalctl -u tomcat. The new version stays on disk for you to inspect; delete it with rm -rf /opt/tomcat/apache-tomcat-X.Y.Z.
Manager returns 403/404 via the public URLCorrect: it only listens on loopback.Reach it through an SSH tunnel (ssh -L 8080:127.0.0.1:8080) and open http://127.0.0.1:8080/manager/html.
NGINX returns 502Tomcat is not up.sudo systemctl status tomcat, then imaxe tomcat doctor.

هل واجهتك مشكلة مع وحدة Tomcat؟

راسلنا مرفقًا مخرجات «imaxe <module> status --json» وسنرد عليك بسرعة.

التواصل مع الدعم