Bootstrap Web Files

Overview

This page describes how to import or update web files in the repository using the bootstrap mechanism or manual upload.

When to Use

Use the bootstrap mechanism to import or update web files in the repository, especially during deployment. Use manual upload to update individual web files in production without redeploying the application.

Development Environment

In a local development environment, changes to web files on the file system are automatically imported into the repository. When you (re)start a local repository, any changes made to web files during downtime are imported into the existing repository. This ensures that the repository web files always match the files on the local file system during development.

Production Environment

In production, use the repository bootstrap mechanism to import web files into the content repository. The bootstrap process imports an entire web file bundle using a single YAML source definition. On redeployment, the system reloads the web file bundle if it detects changes compared to the previously deployed version.

You can also update web files manually to avoid redeployment.

Establish clear ownership of each web file bundle. Either project developers manage the bundle content through deployments, or another party manages updates manually. If you update web file content manually and then deploy a new version of the bundle, all manual changes are overwritten by the deployment.

Web File Bundle YAML Source Definition

Implementation projects store web file bundles as files and directories on the file system. These are packaged into .jar files and included in the .war files of the web application. A single YAML source definition bootstraps a packaged web file bundle into the repository.

In a Maven project, store web file bundles in a dedicated module. By default, this module is repository-data/webfiles.

A Maven module can contain multiple web file bundles. Each bundle is located in a separate directory under src/main/resources, named after the bundle. The following directory structure shows a Maven module called repository-data/webfiles with a web file bundle named site containing two web files: css/style.css and js/script.js.

repository-data
  webfiles
    src
      main
        resources            
          site
            css
              style.css
            js
              script.js

Info: The web file bundle name must match the context path of the application where the web files are used. If the application runs without a context path (as ROOT.war), the bundle name should be site.

To import a web file bundle, add a YAML source definition in:

repository-data/webfiles/src/main/resources/hcm-config/main.yaml

The default YAML source definition for the site web file bundle in a project created using the Maven archetype is:

definitions:
  webfilebundle: site
copy

This definition imports all files and directories in the site directory into the repository at the JCR path /webfiles/site. If your module contains multiple web file bundles, for example site and intranet, include both as follows:

definitions:
  webfilebundle: site
  webfilebundle: intranet
copy

Manual Upload

To update a web file in production without redeploying, use the Console. Browse to the web file's jcr:content node (for example, /webfiles/site/css/bootstrap.css/jcr:content) and click Upload binary next to the jcr:data property.

After uploading, update the /webfiles/site/webfiles:anticache property with a new timestamp. This step ensures browsers do not serve cached versions of the old web files.