OpenCms documentation
OpenCms documentation

Static export

The static export allows to gain an important performance improvement by mirroring pages and other resources into the real file system of the server.

This can be used to

  • improve the performance of a dynamic site: By exporting all images to the document root of the web server, the performance can be improved, since the web server can serve these images directly, i.e. without calling the JSP container.
  • create a full static copy of a side that can be run completely without OpenCms or that can be stored on an USB stick or CD-Rom.

The static export comes in two flavours:

  • the static export on demand creates a copy of a resource in the RFS (Real File System) the first time this resource is requested while browsing the online project. So the following requests will be resolved faster by just displaying the previously created RFS-copy of the resource, instead of each time creating dynamically every resource - an operation that may involve complex logic and expensive database access.
  • the after-publish static export writes out all pages that should be exported after a content was published, so that the RFS contains a full copy of a site. This after-publish export can also be initiated by starting it in the database management in the administration view of the workplace.

The opencms-importexport.xml covers the configuration of import/export related features. In the DTD for it. all the configuration possibilities are briefly described. Thus, the file is a good, thought very technically, overview for theses features. In particular for the static export configuration.

The default configuration file provides usually the starting point for your adjustments and  reflects the recommanded default configuration for most use cases. Use it as an example configuration.

Some general issues you have to be aware of when using static export are:

  • No page with dynamic interaction, like with forms or search functions should be exported statically.
  • For links to VFS resources (at least the ones that are exported), always using the <cms:link> tag. Provide all parameters that are given to the resource via the link inside the tag.
  • Be sure the Export user has permission to read the resources to export - because every export is performed by this user.

There are various properties which control the export of files. Of course, these have only influence, if static export is enabled at all. But, when using static export you should thoroughly think about which of these properties you have to set at which resource.

export

The property inidcates if a resource should be exported (export=true) or not (export=false). The property is inherited from parent folders. If not set at all, a (configurable) default value is used. Typically false. Note that the property is ignored for files with a suffix, that matches one of the configured default suffixes.

exportname

Via exportname you can change the name of the exported resource when it is written to the RFS. The property applies for folders only and must be attached directly to the folder of interest.

By default, the folder structure of the VFS is resembled on the RFS during export. By setting exportname at a folder, you alter this behavior for the single folder. The value of exportname should be the complete path, the VFS path translates to when exported.

You may use the folder to export (static) resources stored in a VFS folder to a differently named folder on the VFS.

Be careful to prevent the export of two different VFS folders to the same RFS folder. In that case, you may overwrite files with identical names that come from different folders.
exportsuffix

The exportsuffix property specifies the suffix for the exported file. It applies to JSPs only. The default export suffix for JSPs is .html. Via exportsuffix, you can alter that suffix.

E.g., if a CSS file is rendered by a JSP, set exportsuffix=.css.

Besides using the export property, you can mark a resource as internal to prevent export. Go to the workplace's explorer view, right-click the resource, choose "Advanced -> Secure/Export" in the context menu and check "Internal use only" in the appearing dialog. This setting is the strongest and will overwrite all other export settings. The option is not available for folders.

The static export is configured in ${WEBAPP_HOME}/WEB-INF/config/opencms-importexport.xml. It is the configuration file for all import/export related features. For more information on its structure, see a full specification of this configuration file, or a default configuration file.

The static export feature is configured in the <staticexport> node in opencms-importexport.xml. Ensure that the attribute enabled of this node is set to true, if you want to use static export.

A basic setting for the static export feature is the folder, where RFS copies of files should be stored. In the default configuration, they are written to ${WEBAPP_HOME}/WEB-INF/export.This can be configured modifying the <exportpath> node, which should contain an absolute path or a path relative to ${WEBAPP_HOME}.

OpenCms comes 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. You can configure the handler by editing the handler class in the <staticexporthandler> node.

Here's an overview on the static export handlers shipped with OpenCms. Typically an "on demand"-handler is a good choice.

CmsAfterPublishStaticExportHandler

This handler will 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.

CmsAfterPublishMultiLanguageStaticExportHandler

Extended after publish static export handler, supporting multi-language exports.

CmsOnDemandStaticExportHandler (default)

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.

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 useful for most directory based navigations.

Depending on your server configuration, you may also need to adjust render settings (specified in sub-node <rendersettings>). Render settings specify how dynamic resources, i.e., resources rendered by JSPs, are processed. For example, here you can globally set, how links are adjusted. The most important setting is <vfs-prefix>. It specifies the path prefix of links to resources that are not exported, i.e., read from the VFS. You might have to adjust it as described here.

Here's an overview on the render settings. Typically, you can keep the default configuration and skip the overview. If you want even more details, please have a look at the document type definition of the opencms-importexport.xml.

rfs-prefix

The prefix used for links to exported resources. In the default configuration ${CONTEXT_NAME}/export is used.

vfs-prefix

The prefix used for links to resources that are not exported. In the default configuration ${CONTEXT_NAME}${SERVLET_NAME} is used. If you install OpenCms as ROOT app, use ${CONTEXT_NAME} instead.

userelativelinks

If set to true, relative links are produced. Otherwise absolute links are generated. Typically false is the correct setting. Only, if you want to export your whole website and put the static files on a CD or USB-Stick, you should use relative links.

exporturl

The URL given here is internally called to export template resources, i.e., a HTTP request to this machine is done to generate them. Usually this should be a request to the server itself, i.e., localhost. Typically, the default configuration http://127.0.0.1:8080${CONTEXT_NAME}/handle404 is sufficient.

plainoptimization

The option only influences after-publish static export. It speeds up this static export, if files that are not rendered (e.g., images, plain text files, ...) are published. If set to true, publishing those files will only cause their re-export, but avoid re-exporting rendered resources. You may need to turn of the plain optimization if rendered resources depend on those files, e.g., your navigation has entries for those files.

testresource

(no description)

resourcestorender

Here you can specify the resources to render for a full static export or in after-publish mode. The intention is to speed up the export process by excluding folders like /system. Provide them in <regex>-subnodes. See the default configuration for an example.

rfs-rules (optional)

With RFS-rules you can overwrite the global render settings for source sets specified in the rule. Read more about them below.

Besides the static export options already described, there are some more such options. Here's a brief overview on all options you can specify in the <staticexport> node. You can look up the comments in the document type definition of the opencms-importexport.xml.

Usually, most of the settings don't have to be adjusted.
staticexporthandler

The static export handler to use. OpenCms ships with four different export handlers. For most scenarios we recommend the CmsOnDemandStaticExportHandler that is already configured in the default OpenCms configuration. Moreover, you can provide your own static export handler. It has to implement the interface I_CmsStaticExportHandler.

linksubstitutionhandler (optional)

The link substitution handler takes care of adjusting links. By default the CmsDefaultLinkSubstitutionHandler is used. Typically the handler is sufficient. But you can also provide your own handler. It must implement I_CmsLinkSubstitutionHandler.

exportpath

The RFS path where exported files are stored. It can be given relatively to ${WEBAPP_HOME} or as absolute path. The folder structure below the configured path mirrors (if not explicitely specified differently) the folder structure of the VFS.

exportworkpath (optional)

The option has only influence for a full static export. If specifiedand there are not several identical export path specified in export rules, the files are first exported to the work path and moved to the export path in the end. The default export work path is ${WEBAPP_HOME}/WEB-INF/temp.

exportbackups (optional)

The option has only influence for export after publish. It specifies the number of backups (backup folders) in the RFS. Default is 0. If set to a positive integer n, the last n backups are stored under ${EXPORT_PATH}/backup${i}., where i is between 1 (latest backup) and n (oldest backup). If export rules are defined, folders for each rule are written, where these are named backup${export rule name}${i}.

defaultpropertyvalue

If a resource should be exported can be specified via the property export. If set to true (at the resource or a parent folder), the resource is exported. If set to false, it isn't. If the export property is not specified at all, the export property's default value, as configured here, is chosen. In the default configuration the value is false.Note that files with specified default suffixes are always exported - independently of the export property.

defaultsuffixes (optional)

Files that have one of the suffixes listed here are always exported to the RFS. In the default configuration these are files with suffix .jpg, .png, .zip etc.

exportheaders (optional)

A list of HTTP headers which can be used when exporting plain resources (e.g. binary files like pdf).

requestheaders (optional)

A list of HTTP headers are used while sending the internal requests during the static export. If none of those headers are defined, the default settings (language and encoding) of OpenCms are used.

rendersettings

The render settings control how template based resources are written to (i.e. "rendered") the "real" FS. For example, you can specify how links are adjusted.

If you are using a proxy server that should directly serve statically exported resources, you have to configure special rewrite rules to make the export work. Here's the important part to make static export working in the Apache Webserver configuration style:

# 8. Rewrite rule to make OpenCms' static export working
  RewriteCond %{REQUEST_URI} ^/export/.*$
  RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}" !-f
  RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}/index_export.html" !-f
  RewriteRule .* /opencms/handle404?exporturi=%{REQUEST_URI}&%{QUERY_STRING} [PT]

To use the rewrite rules with the Apache webserver you need to have mod_rewrite installed. How to set up the Apache webserver is explained in detail here. That's also where the configuration snippet shown above is taken from. Of course, using HaProxy, nginx, or some other proxy might be a good choice as well.

  • Tomcat's directory listing feature: For ensuring a proper behavior of the static export feature, Tomcat's directory listing feature should be disabled. Since Tomcat 6 it is disabled by default. If you already enabled it, disable it. This can be done in the master ${TOMCAT_HOME}/conf/web.xml configuration file, or for each application in its ${WEBAPP_HOME}/WEB-INF/web.xml configuration file. You just need to set the value of the servlet/init-param/param-value node to false, for both the default servlet and the listings parameter.

Real file system rules (RFS rules) allow to specify export settings that apply only to parts of the VFS resources. Thus you can overwrite the global settings for a part of the resources. This may in particular be necessary if you serve more than one website from one OpenCms installation.

RFS rules are defined in opencms-importexport.xml in the optional subnode opencms/importexport/staticexport/rendersettings/rfs-rules. Each rule is defined in a subnode <rfs-rule>. Here's the structure of such a rule:

name

Name of the rule

description

A precise description of the uses of this rule

source

A regular expression that indicates the set of resources that apply this rule.

rfs-prefix

See the same option for the global render settings.

exportpath

See the same option for the global static export settings.

exportworkpath (optional)

See the same option for the global static export settings.

exportbackups (optional)

See the same option for the global static export settings.

userelativelinks (optional)

See the same option for the global render settings.

related-system-res

A list of regular expressions that should specify all resources in the /system/ folder used by the source resource set. This resources will also be exported to the given export path.

Let's say we have two different sites. Both use the same base template with resources under /system/modules/master.template/: 

  • Site One: This site is accessed at http://www.site-one.com and is configured in OpenCms as /sites/site1/. The site is served by an Apache server, serving from /var/apache/site1/.
  • Site Two: This site is accessed at http://www.site-two.com and is configured in OpenCms as /sites/site2/. The site is served by the same Apache server as Site One, but it's served from /var/apache/site2/. Futhermore, Site Two uses an additional template having resources under /system/modules/site2.template/. These resources have relative links between each other.

The site configuration in ${WEBAPP_HOME}/WEB-INF/config/opencms-system.xml should look like:

<sites>
  <workplace-server>http://www.workplace.com</workplace-server>
  <default-uri>/sites/default/</default-uri>
  <site server="http://www.default.com" uri="/sites/default/"/>
  <site server="http://www.site-one.com" uri="/sites/site1/"/>
  <site server="http://www.site-two.com" uri="/sites/site2/"/>
</sites>

The RFS rule definitions in ${WEBAPP_HOME}/WEB-INF/config/opencms-importexport.xml, under the <rendersettings> node, should look like:

<rfs-rules>
  <rfs-rule>
    <name>site-one</name>
    <description>This is the rfs-rule for site one</description>
    <source>/sites/site1/.*</source>
    <rfs-prefix></rfs-prefix>
    <exportpath>c:/apache/site1</exportpath>
    <related-system-res>
        <regex>/system/modules/master.template/.*</regex>
    </related-system-res>
  </rfs-rule>
  <rfs-rule>
    <name>site-two</name>
    <description>This is the rfs-rule for site two</description>
    <source>/sites/site2/.*</source>
    <rfs-prefix></rfs-prefix>
    <exportpath>c:/apache/site2</exportpath>
    <userelativelinks>true</userelativelinks>            
    <related-system-res>
      <regex>/system/modules/master.template/.*</regex>
      <regex>/system/modules/site2.template/.*</regex>
    </related-system-res>
  </rfs-rule>
</rfs-rules>

The rules only apply to the resources that match the regular expressions in the <source> nodes. If an exported resource does not match any rule, the global settings are used. Also, all system resources are written to the global default export path as well.

Export rules are a feature of the CmsAfterPublishStaticExportHandler. So it will only take effect if you configure this handler. It is not a feature for export on demand (and also does not make sense for that scenario).

So to be able to take advantage of export rules, you have to set your default static export handler to CmsAfterPublishStaticExportHandler (or a subclass of this handler, as CmsAfterPublishMultiLanguageStaticExportHandler). That is, your static export handler definition in the ${WEBAPP_HOME}/WEB-INF/config/opencms-importexport.xml configuration file should look like:

<staticexporthandler>org.opencms.staticexport.CmsAfterPublishStaticExportHandler</staticexporthandler>

Export rules are an instrument to reduce the number of resources that are re-exported by an export after publish. Using static export after publish, OpenCms has to determine the resources that have to be re-exported from the list of published resources. Since dependencies can be very involved, it is in most cases impossible to determine what the re-export candidates are. Thus, OpenCms uses exports more resources than necessary. Typically all dynamic resources are be re-rendered and exported when only a single dynamic resource is published.

Export rules specify dependencies between resources. Thus, they tell OpenCms explicitly which resources have to be re-exported after a special resource is published. Thus, good export rules can reduce publish time substantially.

The export rules, as also all the other configuration settings for the static export, are configured in ${WEBAPP_HOME}/WEB-INF/config/opencms-importexport.xml.

An export rule needs following data.

name

The name of the rule.

description

A precise description of the uses of this rule.

modified-resources

One or more regular expressions that specify a set of resources. If one of this resources becomes published, all resources specified by the <export-resources> node will be exported again.

export-resources

One or more URIs (resources or folders), indicating a set of resources to be exported if any of the resources specified via the <modified-resources> node becomes published.

Here are the two most common applications for export rules:

  • Imagine, you have some template resources under /system/modules/mymodule/template/. All pages that use this template are under /sites/mysite/. So you want an export rule that should trigger only the export of all pages under /sites/mysite/ if any template resource in /system/modules/mymodule/template/ is published. Such an export rule for this situation would look like:
<export-rule>
  <name>mysite-template</name>
  <description>This rule will export all resources under /sites/mysite/,
               if any resource under /system/modules/mymodule/template/ is modified
  </description>
  <modified-resources>
    <regex>/system/modules/mymodule/template/.*</regex>
  </modified-resources>
  <export-resources>
    <uri>/sites/mysite/</uri>
  </export-resources>
</export-rule>
  • The second common situation is to have some XML-content like news under /sites/mysite/.content/news/ and you display this news only in an index.html file, i.e., you want an export rule that should be able to export the index.html file if any resource in /sites/mysite/.content/news/ becomes published. A rule for this situation would look like:
<export-rule>
  <name>mysite-news</name>
  <description>This rule will export the index.html file in folder /sites/mysite/,
               if any resource under /sites/mysite/.content/news/ is modified
  </description>
  <modified-resources>
    <regex>sites/mysite/modules/news/.*</regex>
  </modified-resources>
  <export-resources>
    <uri>/sites/mysite/index.html</uri>
  </export-resources>
</export-rule>

If a published resource does not match any rule, still all VFS resources that match the node's regular expressions from the global render settings will be exported. Keep also in mind that if you specify an URI that does not match the node's regular expressions, it will not be exported. So keep your node's regular expressions synchronized with your  URIs. Please note also, that if a resource is exported having a link to another resource, the last one will only be exported if it is part of the set.