Bootstrap Web Files

Introduction

Goal

Import or update web files in the repository using the bootstrap mechanism or manual upload.

Summary

Web files can be imported and reloaded into the repository via the bootstrap mechanism.

Development Environment

In a local development environment web files that are modified on the file system are automatically imported into the repository. When locally (re-)starting an existing repository, changes made to the web files during downtime will be imported into the existing repository. This guarantees that during local development the repository web files always match the web files on file system.

Production Environment

When deploying the application in a production environment, the repository bootstrap mechanism is the primary way to import web files into the content repository.

An entire web file bundle is bootstrapped using one special YAML source definition. When redeploying, a web file bundle will be automatically (and entirely!) reloaded if it contains changes compared to the previously deployed version of that web file bundle.

Alternatively web files can be updated manually so that a redeployment is not needed.

Web File Bundle YAML Source Definition

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

In a Maven project, the files and directories that make up a web file bundle are stored in a separate module. The default Maven module for web files as configured when you start a new project is repository-data/webfiles.

A Maven module can contain one or more web file bundles. Each bundle is located in a separate directory below src/main/resources named after the bundle. For example, the following directory structure shows a Maven module called repository-data/webfiles that contains a web file bundle called site with two web files in it: css/style.css and js/script.js.

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

A web file bundle can be imported via a special YAML source definition in the file 

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 looks like this:

definitions:
  webfilebundle: site

The webfilebundle definition will import all files and directories in the site directory into the repository, at the JCR path /webfiles/site. If your module has multiple webfile bundles, for example for site and intranet, you can include them both as follows:

definitions:
  webfilebundle: site
  webfilebundle: intranet

Manual Upload

If a redeployment is undesirable, a web file can be updated manually in a production environment using the Console by browsing to the web file's jcr:content node (e.g. /webfiles/site/css/bootstrap.css/jcr:content) and clicking on the Upload binary link next to the jcr:data property.

When using this method you must make sure a new timestamp value is applied to  the /webfiles/site/webfiles:anticache property. Otherwise browsers may still serve older cached versions of the web files.