Tomcat rollback after a failed upgrade: symlink switch or in-place reinstall — what are the limits?

Answer

With a proper CATALINA_HOME/CATALINA_BASE split, the symlink switch is the preferred rollback method unless your systemd unit hardcodes the versioned directory. In‑place reinstall does not improve auditability and carries the risk of leaving orphaned files. On rollback you must redeploy the original javax.* WARs and clear the entire work/ and temp/ directories—not just the JSP cache.

Limits of the symlink approach

The symlink itself poses no Tomcat‑side limit; Tomcat resolves CATALINA_HOME at startup regardless of whether it is a link. The only operational limit comes from how the systemd unit references that path:

• If the unit uses Environment=CATALINA_HOME=/opt/tomcat-current (or an EnvironmentFile with that variable), changing the symlink target requires only systemctl restart tomcat.
• If the unit hardcodes a versioned directory such as /opt/tomcat-10.1.30, every rollback forces you to edit the unit and run systemctl daemon-reload before restarting.

Thus the documented limit is self‑inflicted: hardcoded paths break the zero‑downtime advantage of symlinks.

When in‑place reinstall might be considered

Reinstalling the old version over the failed one is rarely preferable. It does not give a clearer audit trail because the versioned directory is overwritten, erasing evidence of which binary served a given deployment. It also risks leaving stray JARs from the failed upgrade on the classpath, which can cause subtle linkage errors. Only consider an in‑place reinstall if you cannot keep the old versioned directory (e.g., severe disk‑space constraints) and you accept the extra verification steps to ensure a clean classpath.

What to clear on rollback

1. Remove any expanded application directories under $CATALINA_BASE/webapps/ (and the webapps-javaee/ folder if the migration feature was used).
2. Redeploy the original javax.* WARs from your artifact repository—do not rely on existing files on disk.
3. Delete the entire $CATALINA_BASE/work/ directory; it holds compiled JSP classes and other version‑specific artifacts that can cause ClassCastException if stale.
4. Clear $CATALINA_BASE/temp/ for the same reason.

Verification steps

# Confirm symlink points to the intended version
ls -l /opt/tomcat-current
# Verify the running JVM sees the correct CATALINA_HOME
ps -ef | grep catalina.home
# Ensure work/ and temp/ are empty before restart
ls $CATALINA_BASE/work
ls $CATALINA_BASE/temp
# Check that a known‑good javax.* WAR is serving requests
curl -s http://localhost:8080/your-app/health

One missing diagnostic detail that would change the recommendation: does your systemd unit define CATALINA_HOME via an Environment variable (or EnvironmentFile) or does it hardcode the versioned path? If it hardcodes, you must update the unit and run systemctl daemon-reload before each rollback.