Alfresco: upgrade your version of Apache Tomcat

Different versions of Alfresco can be installed with different versions of Tomcat. Alfresco provide a default version with its installer but when installing Alfresco manually, an administrator can choose to install Alfresco using a different version of Apache Tomcat. Usually, each version of Alfresco is officially supported for only one specific version of Apache Tomcat and that’s fine for some use cases but I think that most Alfresco administrators will not follow this specific recommendation, at least for the Community Edition.

You can find the list of supported versions for the Alfresco Enterprise software on the Alfresco Web Site and we can also use this as a base for the Community Edition even if there is no official support for the CE. Now the question is then which version of the Apache Tomcat should be used for the Alfresco Community Edition? I would tend to say that it is probably best to always use the latest available patch of the Apache Tomcat version that is supported by Alfresco. Here is an example for an Alfresco Community Edition 4.2.x:

1. Download the file “Supported Platforms for Alfresco Enterprise 4.2.x.pdf”
2. Based on this file, Alfresco Enterprise 4.2.0 support Apache Tomcat 7.0.42
3. Open the Apache Tomcat WebSite
4. Select the Apache Tomcat 7.0 version (left panel) and download the latest stable minor release which is 7.0.68 today

I would tend not to upgrade Apache Tomcat to the next major release (Tomcat 8 or 9) because it can imply an upgrade of the JRE and some other changes which can bring some issues with Alfresco, aso… Apache is trying to keep all minor releases fully backwards compatible which make this minor upgrade generally possible without much trouble.
If you choose the latest available minor version during the installation that’s good but after some time, you might want/need to upgrade this version for several reasons:

• Bug fix
• Security fix
• Preventive actions
• aso…

Therefore in this blog, I will show you the minimum commands to properly upgrade Apache Tomcat. These commands might change a little bit depending on your actual Operating System and versions of Alfresco and/or Tomcat but you should catch the idea. Therefore I will base my commands on one of my test environment with the following characteristics:

• RedHat Enterprise Linux 6.1
• Alfresco Community Enterprise 4.2.c installed in /opt/alfresco-4.2.c/
• Upgrade Apache Tomcat from 7.0.30 to 7.0.68

So first of all, let’s download the software:

alfresco@vmdevalf02:$ cd /opt/alfresco-4.2.c/
alfresco@vmdevalf02:$ wget http://mirror.switch.ch/mirror/apache/dist/tomcat/tomcat-7/v7.0.68/bin/apache-tomcat-7.0.68.tar.gz
alfresco@vmdevalf02:$ mv apache-tomcat-7.0.68/ tomcat-7.0.68

Once done, the idea is simply to transfer all specific customization from your old Tomcat version to the new one. This include the specific JVM parameters setup in the setenv.sh and usually, there is nothing more to do for the tomcat/bin folder. Another point to not miss is the definition of the shared.loader in the catalina.properties:

alfresco@vmdevalf01:$ cp tomcat/bin/setenv.sh tomcat-7.0.68/bin/setenv.sh
alfresco@vmdevalf01:$ sed -i 's/shared.loader=/shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar/' tomcat-7.0.68/conf/catalina.properties

After that comes the ‘big part’ which is clearly not that big! The next step in our upgrade is to modify the server.xml of the new tomcat version to include all necessary customization. Here are the commands that I executed to enable the SSL, increase the maxHttpHeaderSize for Kerberos and also apply some security best practices like hiding the versions of your Web Application Server:

alfresco@vmdevalf01:$ sed -i 's/Connector port="8080"/Connector port="8080" URIEncoding="UTF-8"/' tomcat-7.0.68/conf/server.xml
alfresco@vmdevalf01:$ sed -i 's/    redirectPort="8443"/    redirectPort="8443" maxHttpHeaderSize="32768" server="Apache Tomcat" xpoweredby="false"/' tomcat-7.0.68/conf/server.xml
alfresco@vmdevalf01:$ sed -i 's/maxSavePostSize="-1"/maxSavePostSize="-1" server="Apache Tomcat" xpoweredby="false"/' tomcat-7.0.68/conf/server.xml

alfresco@vmdevalf01:$ sed -i '/Connector port="8009"/a 
        <Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol" SSLEnabled="true" 
            maxThreads="150" scheme="https" keystoreFile="/opt/alfresco-4.2.c/alf_data/keystore/ssl.keystore" keystorePass="keypassword" keystoreType="JCEKS" 
            secure="true" connectionTimeout="240000" truststoreFile="/opt/alfresco-4.2.c/alf_data/keystore/ssl.truststore" truststorePass="trustpassword" truststoreType="JCEKS" 
            clientAuth="false" sslProtocol="TLS" allowUnsafeLegacyRenegotiation="true" maxSavePostSize="-1" />' tomcat-7.0.68/conf/server.xml

Of course, you can also open the file directly and put the lines inside it… Just remove the different non-needed ” accross the lines. If you aren’t using the access logs (for DEV/TEST environments for example), I would also recommend you to comment the Valve logging (org.apache.catalina.valves.AccessLogValve). Once done, you can check the differences between the two versions of tomcat using something like:

alfresco@vmdevalf01:$ diff tomcat-7.0.68/conf/server.xml tomcat/conf/server.xml

Next step the tomcat users. Alfresco usually define two default users that you might have and use. These users are put in the file tomcat-user.xml:

alfresco@vmdevalf01:$ cat tomcat/conf/tomcat-users.xml | grep -i Alfresco
  <user username="CN=Alfresco Repository Client, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB" roles="repoclient" password="null"/>
  <user username="CN=Alfresco Repository, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB" roles="repository" password="null"/>

You can simply add these two lines in the new Tomcat version (again, don’t forget the ”):

alfresco@vmdevalf01:$ sed -i '/<tomcat-users>/a 
  <user username="CN=Alfresco Repository Client, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB" roles="repoclient" password="null"/> 
  <user username="CN=Alfresco Repository, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB" roles="repository" password="null"/>' tomcat-7.0.68/conf/tomcat-users.xml

This conclude the configuration part. Now you just have to copy the data from the old version to the new one:

alfresco@vmdevalf01:$ cp -R tomcat/endorsed/ tomcat-7.0.68/
alfresco@vmdevalf01:$ cp tomcat/lib/postgresql-9.0-802.jdbc4.jar tomcat-7.0.68/lib/
alfresco@vmdevalf01:$ cp -R tomcat/scripts/ tomcat-7.0.68/
alfresco@vmdevalf01:$ cp -R tomcat/shared/ tomcat-7.0.68/
alfresco@vmdevalf01:$ rm -rf tomcat-7.0.68/webapps/docs tomcat-7.0.68/webapps/examples/ tomcat-7.0.68/webapps/host-manager tomcat-7.0.68/webapps/manager
alfresco@vmdevalf01:$ cp tomcat/webapps/alfresco.war tomcat-7.0.68/webapps/
alfresco@vmdevalf01:$ cp tomcat/webapps/share.war tomcat-7.0.68/webapps/

Now depending on your Indexing system (Lucene?Solr 1? Solr4?), this next step will change… If you are using Solr4, you probably also have a solr.war file on the webapps folder and therefore you can just put that in the new version too. If you are using Solr1, you might not have a war file in the webapps folder because at the beginning, Solr was deployed in the alf_data folder and therefore there is another way to indicate to Tomcat that the Solr is deployed here:

echo "Solr war file in webapps folder:"
alfresco@vmdevalf01:$ cp tomcat/webapps/solr.war tomcat-7.0.68/webapps/

echo "Solr war file in alf_data:"
alfresco@vmdevalf01:$ cp -R tomcat/conf/Catalina/ tomcat-7.0.68/conf/

echo "Other solution... (depends on how you installed/configured Lucene/Solr for Alfresco)"

Of course, you will also need to update any other customization that you may have done like:

• Updating the logging configuration of Tomcat (conf/logging.properties)
• Change the default configured ports (conf/server.xml)
• Change the default error pages (404, 500)
• aso…

That’s why I would strongly suggest you – before to actually switch from one version to another – to manually compare all configuration files in the “conf” folders. This can be done using a tool such as notepad++ on Windows or simply a “diff <path_to_file1> <path_to_file2>” on Linux based systems.

When you are sure that everything has been copied from your old version of Tomcat to the new one, you can actually do the change:

alfresco@vmdevalf01:$ service alfresco stop
alfresco@vmdevalf01:$ mv tomcat/ tomcat-7.0.30/
alfresco@vmdevalf01:$ mv tomcat-7.0.68/ tomcat/
alfresco@vmdevalf01:$ service alfresco start
alfresco@vmdevalf01:$ mv tomcat-7.0.30/ /home/alfresco/backup_tomcat-7.0.30

And voila, you just have to check the logs of Alfresco and Tomcat, verify that the war files have been deployed successfully and that Alfresco is Up&Running again. To be sure that everything is working properly, you should really check the basic features of Alfresco like CheckIn/CheckOut, Online Preview, Creation of new document, Search, Workflow, aso…

In addition to this upgrade, I would also suggest you – if not already done – to change the default error pages (404, 500) as said above. This can be done pretty easily. Indeed you can simply add the following inside tomcat/webapps/ROOT/WEB-INF/web.xml:

  <error-page>
    <error-code>404</error-code>
    <location>/errors/404.html</location>
  </error-page>
  <error-page>
    <error-code>500</error-code>
    <location>/errors/500.html</location>
  </error-page>

Once done, create the error folder:

alfresco@vmdevalf01:$ mkdir tomcat/webapps/ROOT/errors

And put the errors pages inside it. This is an example for the file 404.html:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html >

<head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <style type="text/css">
   body {
      font: 13px/1.231 arial,helvetica,clean,sans-serif;
      color: #000000;
   }

   body,div,p {
      margin: 0;
      padding: 0;
   }

   div {
      text-align: center;
   }

   div.panel {
      display: inline-block;
   }
   </style>
   <title>Alfresco Share » Page Not Found</title>
</head>

<body>
   <div>
      <br><img src="/share/themes/default/images/app-logo.png"><br><br>
      <p style="font-size:150%">Page Not Found.</p>
      <br><p>The page you were trying to access hasn't been found on the server. Please try again later or contact your administrator.</p><br>
      <a href="/share">Return to Alfresco</a><br><br><br>
      <a href="http://www.alfresco.com">Alfresco Software</a> Inc. © 2005-2012 All rights reserved.
   </div>
</body>
</html>

This conclude this blog about the upgrade of the Apache Tomcat used by Alfresco. As you saw, that’s not complicated at all, it will just take some time to be done properly because we don’t want to left something behind!