App server related topics

From OpenCms Wiki
Jump to: navigation, search


Glassfish V1

Just deploy the OpenCms WAR file and everything is fine.

OpenCms before version 7.0.4

Glassfish V2

You need to uncomment the lines in the opencms’s web.xml file relating to the ‘BEA’ workarounds (and you also need to delete the ‘description’ elements for the params for the xml to load properly):

OnErrorExitWithoutException true


OnErrorExitWithoutException true

RequestErrorPageAttribute weblogic.servlet.errorPage

And of course, you need to deploy it from a directory from the exploded WAR.

After deployment, you need to restart your glassfish domain.

OpenCms from 7.0.4 to 7.0.5

As of OpenCms 7.0.4, the above params in the web.xml file have been removed and the servlet now attempts to detect which app servers require the special exception handling based on ServletContext.getServerInfo(). Unfortunately, there is no entry for "Sun Java System Application Server" which is Glassfish. You have to modify the source to add an entry for Glassfish. In addition, there is a problem with the exception handling code and it runs whether the server is detected or not, so the easiest fix is to update OpenCmsServlet.init() to only log the CmsInitExceptions during initialization.

OpenCms 7.5.0

GlassFish is still not detected. But the initialization exception ("Setup Wizard is still enabled") of the OpenCmsServlet which causes GlassFish to shut down the whole web application (-> No setup of OpenCms is possible) may be disabled by setting servlet.exception.enabled=falsein

Later versions

Will detect GlassFish V2 and choose the proper setting for the default setting servlet.exception.enabled=auto. There is already basic support for GlassFish V3 but at release time a stable release of GlassFish V3 was not available.

Sun One Application Server 8.1 & OpenCms 7.0.5

You must follow same steps described in Sun One Application Server 8.2 (next to this section)

In case you want package OpenCMS as an Enterprise Application, follow indications done by SUN ([1]) We use as deployment descriptors:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-application PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 8.0 J2EE Application 1.4//EN" "">


<?xml version="1.0" encoding="ISO-8859-1"?>
<application version="1.4" 

Sun One Application Server 8.2

This is the needed steps to install and configure OpenCMS 6.2.3


  1. Extract opencms.war from the downloaded
  2. Deploy opencms.war on http://localhost:4848
  3. Edit the following archives (Server configuration - Linux CentOS 4.4 and Postgresql 8.2)

- Edit /opt/SUNWappserver/domains/domain1/generated/xml/j2ee-modules/opencms/WEB-INF/sun-web.xml and it adds this line

<class-loader delegate="false"/>

- Edit /opt/SUNWappserver/lib/appclient/client.policy and it adds this line in the end

grant codeBase "file:${com.sun.aas.instanceRoot}${/}applications${/}j2ee-modules${/}opencms${/}-" { permission java.util.PropertyPermission "*", "read,write"; permission; };

- Edit /opt/SUNWappserver/domains/domain1/config/server.policy and it adds this line in the end

grant codeBase "file:${com.sun.aas.instanceRoot}${/}applications${/}j2ee-modules${/}opencms${/}-" { permission java.util.PropertyPermission "*", "read,write"; permission; };

Restart instance in order to apply changes As I complete continues the normal installation of opencms


JBoss treats WAR files differently than other application servers in ways that severely affect the OpenCms installation procedure. To circumvent the problem, OpenCms has to be deployed as an unpacked WAR directory on JBoss.


  • Extract opencms.war from the downloaded archive and copy it to the JBoss deploy directory
  • Rename opencms.war to prevent naming confusion for the next step (example: opencms.2.war)
  • Create a directory named "opencms.war"
  • Unpack opencms.2.war in the opencms.war directory
  • Depending on the OpenCms and JBoss version, upgrade your JSTL libraries (see this thread for details)
  • (Optional) create a file jboss-web.xml in the WEB-INF folder with the following content to define the application's context-root.
<?xml version="1.0" encoding="UTF-8"?>
  • (Optional, for unix/linux servers) grant the permission to read, write and execute for all on the opencms.war/ directory and it's subtree (chmod -R 777 opencms.war)

After these steps, the web config should work fine.

External Links

Tomcat + IIS Config


Sun Java System Application Server 8.x

JBoss 5.0.1.GA & OpenCms 7.0.5

(Following the steps below will get Opencms 7.0.5 to work on JBoss 5.0.1.GA initially, but subsequent runs will still result in errors. See the section "Additional Comments on Running OK Initially And Then Subsequent Errors" at the end of this section for details. (Addition by: Bsgcic 2009/4/22)

Using the default JBoss 5.0.1.GA web app server configuration and OpenCms 7.0.5 will result in application deployment errors. To resolve this problem the following tasks must be performed:

  • Unpack opencms.war into %jboss_home%\server\default\deploy directory so that the files will now be in %jboss_home%\server\default\deploy\opencms.war directory. (Edit by: Bsgcic 2009/4/21)
  • Confirm that the context-parameter "DefaultWebApplication" in opencms.war\WEB-INF\web.xml value is "ROOT". (Edit by: Bsgcic 2009/4/21)
  • Remove conflicting jars from /WEB-INF/lib (you can just change the file extension to ".delete" extension so you retain it but don't load the jar). These jars include: xercesImpl-2.9.0 and xml-apis-2.9.0. XercesImpl conflicts w/ the Xerces version in %jboss_home%/lib/endorsed. Xml-Apis causes ClassCastExceptions with Digester's getParser and getFactory methods. End result is OpenCms will not work properly and won't even install through the wizard.
  • I also followed the steps described under the "JBOSS" heading immediately above this section. (Addition by: Bsgcic 2009/4/21)

Additional Notes

  • After importing all default modules, I was unable to access any of the new Template 2 demo pages due to HTTP 500 errors in which the app server refused to compile the JSPs requested. I did not investigate further on the cause.
  • After importing the default modules some jars will be extract from the modules onto your /WEB-INF/lib directory. Again these have the potential to cause problems with JBoss 5 when you restart the web app. I found it necessary to remove the following jars: xalan, serializer, sax, and jaxp-api to successfully restart the web app.
  • Creation and publication of basic JSP content pages and free text pages appeared to be functional.
  • Please note that the original author had instructed to unpack opencms.war into %jboss_home%\server\default\deploy\ROOT.war directory. and to change context-parameter "DefaultWebApplication" in opencms.war\WEB-INF\web.xml value to "ROOT.war". I am running the same versions of Jboss (5.0.1.GA) and Opencms (7.0.5) and it did not work in the ROOT.war directory for me but did work in the %jboss_home%\server\default\deploy directory with DefaultWebApplication as the default value of "ROOT". The original author mentioned the following when instructing to unpack into the ROOT.war directory. However, should not be relevant if unpack into the deploy/opencms.war directory as mentioned above. Original author's comment if in ROOT.war directory: "If this value does not match the deployment directory, OpenCms will utilize this value as the context path for URLs within the CMS. That is your CMS generated URLs will be something like http://<yourhost>/ROOT/opencms/index.jsp instead of http://<yourhost>/opencms/index.jsp." (Addition by: Bsgcic 2009/4/21)

Alkacon OCEE Cluster Package

You can find an OCEE Cluster Package issue related to JBoss in [2]

Additional Comments on Running OK Initially And Then Subsequent Errors

  • After performing all of the steps with the exception of the step(s) in the link under the "Alkacon OCEE Cluster Package" sub-heading above that someone appeared to add last night, I was able to perform the installation and utilize Opencms. However, when I restarted Jboss, I encountered errors when re-freshing the opencms/opencms/index.jsp page. Still errors after removing the jars that were added by opencms in the lib folder including those mentioned in the "Additional Notes" section above. In addition to the population of additional jars in the lib folder, the following files were added between the version when it worked in jboss and the subsequent version with errors:
















I finally got it working by just setting up an isapi_redirect.dll configuration through IIS such that IIS redirects opencms folder contents to Tomcat and non-opencms jsps to jboss (via folder definitions in This of course is not the desired result of running opencms on Jboss. For those of you who go this route, you should reference the following page to avert Tomcat hogging the the cpu capacity: Both JBoss and Tomcat will default to port 8009 for the connection with isapi and therefore you need to change one of them. I changed Tomcat by editing /conf/server.xml changing the port from 8009 to another port such as 8011.

Also, there was a significant bug in 5.0.1.GA in which the version of deployed apps in the deploy directory are not updated in the tmp directory by VFS and therefore apps fall out-of-sync when updated. Restarting jboss forces VFS to update the tmp directory. The bug is reported to be fixed in the next version of JBoss. This might or might not contribute to the errors here.

If enough people would benefit from an easier jboss integration, I would suggest pleading to the Opencms development community for a feature request to support jboss out-of-the-box.(Addition by Bsgcic 2009/4/22)

JBoss 5.1.0.GA & OpenCms 7.5.2+

confirmed working with version 7.5.3 as well (Addition by DSeligmann 2010/08/24)

  • unzip the downloaded zip
  • unzip the war
unzip opencms.war -d $JBOSS_HOME/server/default/deploy/opencms.war
  • delete the x*.jar libs (should be two files) and you are done
rm $JBOSS_HOME/server/default/deploy/opencms.war/WEB-INF/lib/x*jar
  • run the setup wizard as usual

Anything else is totally optional. You do not need to touch a single config file. (Addition by DSeligmann 2010/08/19)

WebLogic 8.1

This procedure describes only WebLogic 8.1 with the supplied JDK 1.4.2.

OpenCms has to be deployed as an unpacked WAR in WebLogic 8.1.


  • Extract opencms.war to a temporary directory
  • Replace the jar in "opencms/WEB-INF/lib" with the jar supplied in the Java 1.4 patch (
  • Deploy the exploded WAR to WebLogic
  • Go to the Adminitration console and do a static export (Administration -> Database Management -> Start Static Export)
  • Modify the web.xml file to change the 404 error handler :
  • Create the JSP "/system/handler/handle404.jsp" with the following content :
<jsp:forward page="/opencms/handle404"/>
  • Edit the file "WEB-INF/config/opencms-importexport.xml" search for the following line :

and change it to



We have to modify the error handler because WebLogic doesnt allow the same servlet to provide content and error handling. WebLogic is afraid that it might create an infinite loop.

WebLogic 12c

  • Extract opencms.war to a temporary directory
  • Remove persistence.xml file from WEB-INF/lib/opencms-setup.jar to prevent „Duplicate persistence units“ error
  • Add CLASSPATH for JDBC WEB-INF/lib/mysql-connector-java-5.1.26-bin.jar (or download alternative JDBC driver for your database)
  • In WEB-INF/web.xml uncomment this parameter:
  • Create WEB-INF/weblogic.xml and add following content:
<?xml version="1.0" encoding="UTF-8"?>
<weblogic-web-app xmlns="">
  • Deploy exploded WAR to WebLogic
  • When your application starts, remove „trimDirectiveWhitespaces“ parameter from all JSP´s (you can use OpenCms tool in Administration View > Search Management > Source search)


Tested environment: OpenCms 9.5 + Weblogic 12c (Java EE 1.7) + MySQL 5.5


When using tomcat, it's advisable to increase the memory available to the JDK. It can also be important to allocate more memory to the "PermGen" area; this is not reliably garbage collected, so repeated server restarts (particularly when developing Java classes) will rapidly exhaust the permgen space.

In order to allocate more memory to Tomcat under Linux or other *Nix systems, create a file called "" in $TOMCAT_HOME/bin/ . This will be executed by the tomcat startup scripts and can be used to pass environment options to the JVM tunning tomcat. An example script is:

export CATALINA_OPTS=" -Xmx1024m -Xms512m -XX:MaxPermSize=256m"

This will:

  1. Enable remote JMX monitoring of the server (do not do this unless you know what you are doing!)
  2. Allow Java to allocate up to 1GB of ram if needed
  3. Require Java to allocate a minimum of 512Mb of ram at startup
  4. Allow the Permgen area to grow up to 256MB

Increasing the memory available to tomcat will also greatly help the flex cache store JSP fragments, which will speed up overall performance.

An alternative solution is to switch to a different JVM. JRockit appears to be compatible with openCMS and does not have this issue, as it doesn't have a separate "permanent generation" space.

Personal tools