How To: Upgrade from Railo 3.x to Railo 4.x

Most of the time, upgrading Railo is a simple matter of using the Services>Update page in the Railo Server Admin. However, because Railo 4 is major release, it requires changes that cannot be performed by this tool - this page describes the steps to be taken to do this.

As always, it is recommended to ensure you have valid backups of any important files before proceeding.

1. Download the new Railo 4.x JAR files

Since this is an upgrade, it isn't necessary to download the entire Jetty/Tomcat package again.

Go to the download page at getrailo.org/download and select the "Jar Files (56MB)" option under "Railo Custom" (select either zip or tar.gz as preferred).

2. Stop Railo's servlet engine (Tomcat/Jetty/etc)

The method for this will vary depending on how you installed Railo and what Operating System you are on.

If you used the Railo Installer, details are available here:

• Starting and Stopping Railo on Windows
• Starting and Stopping Railo on Linux

3. Replace existing JAR files with new JAR files.

To locate the directory where your existing JAR files are installed you can search for railo.jar within your installation dir - in most cases it will be either {install-dir}/lib/ext or {install-dir}/lib (but might be in another location if you have a non-standard install).

The archive may contain a directory, e.g. named "railo-4.0.2.002-jars", when extracting make sure the contents of this directory are what you replace the existing files with.

Remove any old patches from {install-dir}/lib/railo-server/patches/

4. Remove ehcache.jar, railo-sl4j.jar and slf4j-api.jar files.

These three files will be replaced in a later step, however they must be manually removed now so that the files do not get locked by the servlet engine. You can either delete them outright, or rename the files to have a non-JAR extension, for example ehcache.jar.old.

5. Configure the REST servlet mappings.

If you will be using Railo 4's REST functionality, you will need to add the servlet definition and mappings for this.

To do this, add the following to your global web.xml (i.e. {tomcat}/conf/web.xml or {jetty}/etc/webdefault.xml or equivalent):

<servlet id="RestServlet">
	<servlet-name>RestServlet</servlet-name>
	<servlet-class>railo.loader.servlet.RestServlet</servlet-class>

	<load-on-startup>2</load-on-startup>
</servlet>

<servlet-mapping>
	<servlet-name>RestServlet</servlet-name>
	<url-pattern>/rest/*</url-pattern>
</servlet-mapping>

The load-on-startup value should be the same or higher as the equivalent value for the Railo CFMLServlet.

6. Start Railo's servlet engine (Tomcat/Jetty/etc)

The method for this will vary depending on how you installed Railo and what Operating System you are on.

If you used the Railo Installer, details are available here:

• Starting and Stopping Railo on Windows
• Starting and Stopping Railo on Linux

7. Use the Railo Update facility to ensure you have the latest patch and JARs.

Login to your Railo Server Admin, and go to Services > Update.

If there is an update available, press the "Execute Update" button to get it. If your JARs need updating, press the "Update JARs" button to update these.

For further upgrades of Railo 4.x versions this final step is all you should need to do.