OpenCms documentation
OpenCms documentation

Public resource delivery

This page is for administrators who need to choose how OpenCms delivers public static resources.

OpenCms can combine S3 or FS binary storage with a shared HTTP cache. This model supports efficient byte-range requests and delegates public response caching to a specialized service instead of maintaining physical copies in the local OpenCms /export directory.

Installations that use an S3 or FS storage backend without a shared HTTP cache can serve byte-range requests for large files directly from storage. This model is suitable for installations with low or medium traffic.

Classic static export remains suitable for installations that primarily serve text and images and do not require large-file or byte-range delivery. It can also be preferable when OpenCms should retain control over the removal of server-side cached copies.

The OpenCms side of public resource delivery is configured in WEB-INF/config/opencms-importexport.xml. In addition to the existing <staticexport> settings, two optional elements can replace physical /export copies:

  • <sharedcache> prepares public responses for an external HTTP cache.
  • <storedcontentdelivery> delivers selected externally stored resources directly from S3 or FS.

The following example is abbreviated. Keep the existing contents of <staticexport> and configure the two delivery elements as described below.

<staticexport enabled="true">
    <!-- Existing static export configuration -->
</staticexport>

<storedcontentdelivery enabled="false">
    <!-- Optional suffix configuration for direct delivery from S3 or FS -->
</storedcontentdelivery>

<sharedcache enabled="false">
    <!-- Cache policies for an external shared HTTP cache -->
</sharedcache>

While <staticexport> determines which files are exportable, <sharedcache> and <storedcontentdelivery> control the public static-export path.

<sharedcache> and <storedcontentdelivery> are alternatives and cannot be enabled at the same time.

Efficient byte-range delivery requires the content to be stored in S3 or FS. Configure the storage policy to include the relevant resource types. Existing database content remains database-backed until it is migrated or rewritten.

If your infrastructure provides a reverse proxy cache, web server cache or CDN, you can use it with OpenCms while preventing OpenCms from creating /export copies:

  • enable <staticexport> with an on-demand export handler and route public /export cache misses to OpenCms
  • enable <sharedcache>
  • keep <storedcontentdelivery> disabled
  • remove any Cache-Control entry from <staticexport>/<exportheaders>
  • bypass the shared cache for Workplace, authenticated and ACL-protected requests
  • configure the HTTP cache to support byte-range requests

OpenCms validates these OpenCms-side requirements during startup.

No physical /export copies are created. Content stored in S3 or FS can be read and returned as a byte range.

This delivery model does not change the URL path. Although it does not create physical /export copies, static resource URLs still start with the /export prefix configured in <staticexport>.

Publishing does not automatically send purge or BAN requests to the external cache. Provide an operational invalidation mechanism; otherwise, published changes and deletions may not become visible until sharedmaxage expires.

If an S3 or shared FS storage backend is available but a shared HTTP cache is not:

  • keep <sharedcache> disabled
  • enable <storedcontentdelivery>
  • add the suffixes of potentially large audio, video and PDF files to <enabledsuffixes>

OpenCms then delivers the selected file types from S3 or FS with byte-range support and does not create /export copies for them.

For all other file types, OpenCms creates physical /export copies as it does in the classic model.

This delivery model does not change the URL path. Although it does not create physical /export copies for the selected file types, their URLs still start with the /export prefix configured in <staticexport>.

Shared HTTP cache delivery is configured in WEB-INF/config/opencms-importexport.xml. The following example uses a one-hour default freshness lifetime and a separate policy for images:

<sharedcache enabled="true">
    <cachepolicy>
        <clientmaxage>0</clientmaxage>
        <sharedmaxage>3600</sharedmaxage>
    </cachepolicy>
    <cachepolicy contenttype="image/*">
        <clientmaxage>0</clientmaxage>
        <sharedmaxage>86400</sharedmaxage>
        <staleiferror>604800</staleiferror>
    </cachepolicy>
</sharedcache>

All durations are specified in seconds and must be zero or greater. staleiferror is optional.

clientmaxage

Controls how long a browser can use the response without revalidation. OpenCms writes it as max-age. A value of 0 keeps freshness control at the shared cache and lets an operational cache purge take effect without waiting for a browser freshness period to expire.

sharedmaxage

Controls how long a response is fresh in the shared HTTP cache. OpenCms writes it as s-maxage. Choose this value based on how long a published change may remain invisible when no explicit invalidation is sent.

staleiferror

Allows the shared cache to reuse a stale response for the configured period when the OpenCms origin is unavailable. It is an availability allowance, not a guarantee that the response remains stored.

Configure the HTTP cache to use stale responses only for the intended origin failures. Authorization failures and missing resources, in particular 401 Unauthorized, 403 Forbidden and 404 Not Found, must not trigger stale delivery.

The image policy in the example produces:

Cache-Control: public, max-age=0, s-maxage=86400, stale-if-error=604800

Every configuration requires one default policy. Additional policies can match an exact MIME type such as application/pdf or a top-level wildcard such as image/* or video/*.

OpenCms obtains the MIME type from WEB-INF/config/opencms-vfs.xml. Shared cache policies do not use file suffixes. An exact MIME type policy takes precedence over a matching wildcard policy. A wildcard policy takes precedence over the default policy.

If no shared HTTP cache is available, <storedcontentdelivery> can avoid physical export copies for selected files and stream them directly from S3 or FS:

<storedcontentdelivery enabled="true">
    <enabledsuffixes>
        <suffix key=".pdf" />
        <suffix key=".mp3" />
        <suffix key=".mp4" />
    </enabledsuffixes>
</storedcontentdelivery>

The normal static export rules still decide whether a resource is exportable. Matching is case-insensitive. If enabledsuffixes is omitted or empty, no suffix restriction is applied.

Resources not handled by direct delivery continue to use physical files created by classic static export.

For Workplace resources and ACL-protected resources, OpenCms automatically uses the same underlying direct-delivery mechanism after checking the project and read permissions. This does not require <storedcontentdelivery> to be enabled.