OpenCms Static-Export Feature

The Static-Export is an advanced OpenCMS feature, that allows to gain an important performance improvement while browsing the Online-Project, creating a copy of the resources in the RFS (Real File System) the first time a resource is requested, so that following requests will be resolved faster by just displaying the previous created RFS-copy of the resource, instead of creating each time dynamically every resource, operation that may involve complex logic and expensive database access. The Static-Export feature is a complex operation that recognizes static and dynamic resources and handles carefully cached and included resources as also resources with a given timeout.

OpenCms Configuration

The default configuration file for the Static-Export feature is the ${CONTEXT_NAME}/WEB-INF/config/opencms-importexport.xml configuration file. This file configures also another import/export related features, like the Content Import/Export and the Module Import/Export features, and in this document, we will address just the basic configuration. But for more information, you can see a full specification of this configuration file, or a default configuration file.

The Static-Export feature is configured in the staticexport node. The first thing to do is to set the staticexport@enabled  attribute of this node to true, if you want to try it out. In the default configuration the RFS copies of the resources are stored in the ${CONTEXT_NAME}/WEB-INF/export directory. This can be configured modifying the text of the staticexport/exportpath node, which should be a relative path to the${CONTEXT_NAME}/WEB-INF  directory.

OpenCms comes also with several different Static-Export Handler classes, that determines how the Static-Export feature takes care of publish operations, like adding a new file or modifying a existing one. The most used are:

• org.opencms.staticexport.CmsAfterPublishStaticExportHandler:
  This handler will static-export the whole site after every publish operation, it will regenerate every resource in the current project. This handler is also implicitly called when creating a full static site-mirror, via the Administration -> Static-Export menu.
• org.opencms.staticexport.CmsOnDemandStaticExportHandler:
  This handler will just delete the RFS-copies of fresh published resources, so that they can be regenerated by the next incoming request, for reflecting the changes.
• org.opencms.staticexport.CmsOnDemandHtmlSubtreeHandler:
  This handler is an extension to the previous one, that also deletes every RFS-copy of dynamic resources in the subtree of every fresh published resource. This is usefull for most directory based navigations.

The default Static-Export Handler class is theorg.opencms.staticexport.CmsOnDemandStaticExportHandler. You can configure it by editing the handler class in the staticexport/documentation_staticexporthandler node.

Tomcat5 Configuration

For ensuring a proper behaviour of the Static-Export feature, it is advisable to disable the Tomcat default directory listing feature, this can be done in the master ${TOMCAT5_HOME}/conf/web.xml configuration file, or for each application in the ${CONTEXT_NAME}/WEB-INF/web.xml configuration file. You need just to set the text of the servlet/init-param/param-value node, to false, for the default servlet and the listings parameter.

See a sample master Tomcat5 Web configuration file.

Apache Configuration

If you are using an Apache2 interface for accessing your site, you will have to redirect the unresolved requests to the OpenCms 404 Error Handler. For this, you will need to ensure you are including following Apache modules in your ${APACHE2_HOME}/httpd.conf configuration file:

 LoadModule alias_module modules/mod_alias.so
 LoadModule proxy_module modules/mod_proxy.so
 LoadModule proxy_http_module modules/mod_proxy_http.so
 LoadModule rewrite_module modules/mod_rewrite.so

Then your VirtualHost definition should include a new rewrite rule like:

 # Redirect all request to non-existing file in the export directory to OpenCms which will generate the files "on the fly"
 RewriteEngine     on
 RewriteCond       %{REQUEST_URI}                                            ^/export/(.*)  [NC]
 RewriteCond       "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}"                     !-f
 RewriteCond       "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}/index_export.html"   !-f
 RewriteRule       .*  http://127.0.0.1:8081/handle404?exporturi=%{REQUEST_URI}&%{QUERY_STRING} [P]

Where ${CONTEXT_NAME} should be replaced by your application name. Also, notice that an extra Tomcat Connector on port 8081 is being used, this can be configured in the ${TOMCAT5_HOME}/conf/server.xml configuration file by adding a new server/service/connector node.

See a sample Tomcat5 Server configuration file, and a sample Apache2 configuration file.

See also the com.alkacon.documentation.howto_apache-httpd documentation module.

Another unofficial approach is described in a short How-To written by Sebastian Himberger and posted at the OpenCms Forum.de.