Backup first
Make copies of these files
lucee-server/context/.CFconfig.json
- 6.0+lucee-server/context/lucee-server.xml
- 5.xwebroot/WEB_INF/lucee/lucee-web.xml.cfm
- 5.4 context specific config(s)
In place upgrades
Lucee, unlike Adobe CF has always allowed easy upgrades/downgrades between versions via the admin.
There was a restriction in older Lucee versions which meant you couldn’t downgrade to an older version than your current Lucee loader version, but that restriction has been removed in 6.2 (note to self, I need to update the admin text)
As always, you can simply do an in place upgrade, as Tomcat 9.0 is still supported by 6.2, it’s just java 8 is no longer supported.
There are multiple ways to do an in place upgrade of Lucee
Core update (.lco
)
- via the admin
- or by dropping a core .
lco
into thelucee-server/deploy/
folder, i.e https://cdn.lucee.org/6.2.1.77-RC.lco - with 6.2, you can just set the env var
LUCEE_VERSION=6.2.0.321
and Lucee will load that version on startup
Loader update (lucee.jar
aka the fat jar)
Updating your Loader is also recommended
- stopping Lucee and replacing the
lucee.jar
in thelucee/lib
directory, i.e. https://cdn.lucee.org/lucee-6.2.1.77-RC.jar
The difference between a Core update and a Loader update?
- the core
.lco
only contains the minimum files required to update, Lucee will then dynamically download any missing bundles / jars required. - the fat
lucee.jar
includes all the required bundles / jars to run Lucee, so no additional downloads are required.
During an in place upgrade, Lucee 6 will automatically convert/import your xml
and convert it to json
.
The original xml
files are left in place, so you can also downgrade again, just keep in mind any configuration changes made while running 6 do not update the xml
files.
So once you have done an in place upgrade, you’ll have your CFConfig.json
available, but you are still running older versions of Java and Tomcat, sooo…
Fresh Install, highly recommended
Generally speaking, the best way to upgrade from Lucee 5.4 is always going to be a new install.
Any 5.4 install is mostly likely already going to be using rather old versions of Tomcat and Java.
Consider doing an in place upgrade via the admin, to grab your running config from lucee-server/context/.CFconfig.json
and then doing a fresh install. Just stop the server after installing and copy the .CFconfig.json
file into the new server and restart it.
Side by side installs
The Lucee installer has supported side by side installs since a while, i.e. into different folders on different ports.
I have locally, c:\Lucee
and c:\lucee6
both pointing to the same webroots
Copying your Configuration over
For most Lucee installs, there are only one or two files needed to duplicate your server config.
lucee-server/context/.CFconfig.json
- 6.0+lucee-server/context/lucee-server.xml
- 5.xwebroot/WEB_INF/lucee/lucee-web.xml.cfm
- 5.4 context specific config
The only additional files you need to consider are any jars you have installed into Tomcat or context lib dirs, like urlrewrite
etc
Have you made any custom configuration changes made to the Tomcat configuration? i.e. tomcat/conf/
use a diff tool to copy them over.
But you had already documented all these additional changes for disaster recovery? If not, I’d highly recommend doing that as part of this upgrade process.
Upgrade Considerations
Lucee 6 only supports Java 11+, with Lucee 6.2 we recommend Java 21, so not java 8.
Also, Lucee 6.2 supports the newer jakarta based servlet API, i.e. Tomcat 10.1 and Tomcat 11, as well as Java 21.
Due to the change to the Jakarta namespace, with Tomcat 10+ you will need updated versions of jars like urlrewrite
v5.0 UrlRewriteFilter - Rewrite URL's in Java Web Application Servers
Configuration syntax changes
The Lucee Admin is your friend, use it to configure your server, it will show you the supported configuration with snippets at the bottom of most edit pages.
If something isn’t working like an older datasource connection in an Application.cfc
, go and try configuring it in the Lucee Admin and compare to your code.
You can always just grab the running config from your lucee-server/context/.CFconfig.json
.
Deploying
I have prepared some detailed documents on how to deploy Lucee configuration.
Rolling your own Tomcat install
Please refer to Lucee Express to see the recommended Tomcat configuration required to run Lucee
Here is the source code for building the installer from the original Tomcat sources
TL;DR? You’ll need to manually add the javax servlets to Tomcat 11, but why not just use our Installers or Lucee Express which are pre configured and known to work?
Questions?
Need professional support? I am available for consultancy, just message me
Ask below!