Run and Develop with Docker

Introduction

Goal

Use Docker to run your Bloomreach Experience Manager implementation project in your development environment.

What is Docker

Docker is a tool that allows you to create, deploy, and run applications by using containers. In development environments, we recommend to run the CMS and HST site applications inside one and the same container from Maven. In the standard Maven POM that is provided with the archetype, the Maven Docker plugin is pre-configured to build and run a Docker image from your project. This page explains how to work with the default Docker setup: how to run, how to debug, and how to customize the configuration.

Install and Start Docker

If you haven't yet, download and install Docker. Once installed, start it up. Docker must be running when you build the image in the next step.

Build a Docker Image

For the purpose of building an image containing a Bloomreach Experience Manager project, a dedicated Maven profile is provided by the Bloomreach Experience Manager Release POM. To view the Bloomreach Experience Manager Release POM and the Docker configuration defined there, see the relevant release in the Bloomreach Experience Manager Maven repository. To learn about Maven profiles refer to the introduction to build profiles on the Maven documentation website.

<docker.maven.plugin.version>0.44.0</docker.maven.plugin.version>

To build a Docker image containing your Bloomreach Experience Manager project, run the following commands. These compile and package the project, then build a docker image from the packaged artifacts. They can only be run from the root directory of the project.

mvn clean install
mvn -P docker.build 

Base Image & Default Dockerfile

The base image used to build the project image is specified by the Maven property docker.brxm.base.image and used by the file src/main/docker/Dockerfile, which is provided by the project archetype.

By default, the base image is either tomcat:9-jdk8-openjdk-slim for brXM 14 or tomcat:9-jdk11-openjdk-slim for brXM 15. These are official Tomcat images provided by Docker Hub and always contain the latest Tomcat 9 image for their respective OpenJDK versions. As a latest image, it evolves over time with each Tomcat 9 release.

If a more stable approach is desired, it's possible to specify a different base image by overriding the Maven property mentioned above, for example by setting a specific version of Tomcat, such us 9.0.29-jdk8-openjdk-slim.

Note that using official images from Docker Hub is not mandatory, however, the more different the image is, the more likely the Dockerfile will require modifications.

Included JDBC Driver Versions

Docker images created using the provided docker support files are prepared to run with multiple database types and already contain built-in MySQL, PostgreSQL and H2 JDBC drivers. Depending on environment variables specified during container creation (i.e. via the docker run command) the appropriate configuration and DB driver will be used. Currently, there are two properties in the Release POM which control the JDBC driver versions: mysql.connector.version and postgres.connector.version. If required, these versions can be overridden in the local project POM file.

Run with Docker for Development

To run the Docker container built above for local development testing purposes, use the command:

mvn -P docker.run

Note that you can only run this command from the root directory of your project. By default, if no extra profile is specified, an H2 database is used. By default, the raw data is stored in the /target/storage subdirectory of the project, which is bind-mounted into the running docker container.

During the execution of docker.run command, an intermediate image is created and used for development. It contains extra development related artifacts such as:

• essentials.war
• hippo-services-autoreload.jar
• repository-data-development.jar
• repository-data-site-development.jar

Docker DB Profiles

Several secondary profiles can be used together with docker.run profile to select alternative database types.

mvn -P docker.run,docker.mysql

or

mvn -P docker.run,docker.postgres

If one of the two profiles above is specified in addition to docker.run, a corresponding DB container will be created, bootstrapped, and linked via a private network to the main brXM container. By default, the raw data is stored in either the /target/mysql-data or /target/postgres-data project subdirectory, respectively. The default credentials used for database connections will be admin:admin. These values are configurable by overriding the docker.db.username and docker.db.password properties in the project POM file. The database port will be randomly allocated by default. If required, it is possible to explicitly specify the desired port by defining the Maven property docker.db.port.

SQL Bootstrapping

It is also possible to bootstrap SQL data into the DB container when it is created. To do that, .sql or .sql.gz files should be placed into a /db-bootstrap subdirectory of the root of the project. Files will be executed in alphabetical order. For example, SQL instructions can create additional DBs or bootstrap data from a backup of another environment.

DB Image Versions

The Docker base images used for the DB containers are specified in the docker.mysql.image and docker.postgres.image Maven properties. If required, these versions can be overridden in the local project POM file.

Connect to an External DB

Alternatively, it is possible to connect the local Bloomreach Experience Manager container to an external MySQL or PostgreSQL DB. Use the Maven properties docker.db.host, docker.db.port, docker.db.schema, docker.db.username, and docker.db.password, to configure the connection. (The default values will attempt to connect to the default port for the DB type on localhost.) Then run with the alternate profiles below. Note the missing 'docker.' prefix.

mvn -P docker.run,mysql

or

mvn -P docker.run,postgres

Debug with Docker

The Bloomreach Experience Manager Docker profile provides several useful options to debug your Bloomreach Experience Manager project. Java debuggers may connect to the running container via port 8000 by default. Merely attach your favorite debugger to this port. Refer to Develop with Eclipse to learn how to use the Eclipse built-in debugger for this.

By default, Docker starts up Tomcat without waiting for a debugger to be attached. In order to modify this behavior, you can specify the property docker.brxm.debug.suspend=y when running with the docker.run profile:

mvn -P docker.run -Ddocker.brxm.debug.suspend=y

This is particularly useful if you want to debug something during the startup and initialization phases of the CMS or website. The JVM will now suspend execution until you have attached a debugger.

You can also specify an alternative port number for the remote debugging facility. This can be useful if the default port is already in use by another application. To specify an alternative port number for the remote debugging facility, change the property docker.brxm.debug.port.

mvn -P docker.run -Ddocker.brxm.debug.port=9000

Run with Docker without Development Repository Data

A standard Bloomreach Experience Manager project based on the Maven archetype contains a repository data JAR modules called repository-data-development and repository-data-site-development. By default, these modules are deployed into Tomcat's shared/lib directory. The latter can optionally be omitted using the Maven profile without-development-data combined with the docker.run profile:

mvn -P docker.run,without-development-data

This will cause the repository-data-development and repository-data-site-development JARs not to be deployed. For example, this is useful when testing an upgraded project locally, using a copy of an existing production repository.

Run with Docker using Different Port Numbers

By default, the Bloomreach Experience Manager container's HTTP port will be mapped to the host machine on port 8080. If you want to change this default port number, add the following property in the docker.run profile configuration like the following example, which maps the container to the host's port 9080:

<profile>
  <id>docker.run</id>
  <properties>
    ...
    <docker.brxm.http.port>9080</docker.brxm.http.port>
    ...
  </properties>
</profile>

You can also specify this at the command line, like so:

mvn -P docker.run -Ddocker.brxm.http.port=9000

Finally, to make sure the HST site implementation works properly, use the Console to update the delivery tier configuration to reflect the different HTTP port:

/hst:hst/hst:hosts/dev-localhost
  - hst:defaultport = 9080

Pass Additional System Properties

Either add them to the docker.run plugin configuration using docker.brxm.jvm.args property in the primary POM:

    <profile>
      <id>docker.run</id>
      <properties>
        <docker.brxm.jvm.args>-Xmx4g -Drepo.path=./storage</docker.brxm.jvm.args>
      </properties>

Or pass them on the command-line using the system property -Ddocker.brxm.jvm.args:

mvn -Pdocker.run -Ddocker.brxm.jvm.args="-Drepo.path=./storage -Xmx4g"

Run with Docker on Local Linux OS

UID (User Identifier), GID (Group Identifier), and name of the user in the Docker container are customizable using docker.brxm.container.dev.uid, docker.brxm.container.dev.gid, and docker.brxm.container.dev.username properties for the development image. The default values of these properties that defined in the Release POM are as follows:

<docker.brxm.container.dev.username>brxmdevuser</docker.brxm.container.dev.username>
<docker.brxm.container.dev.gid>1000</docker.brxm.container.dev.gid>
<docker.brxm.container.dev.uid>1000</docker.brxm.container.dev.uid>

In local development, since the Docker container uses a shared directory which is defined by the volume in the docker.run profile in the Release POM, the container user needs permissions to the directory which is mounted. On local Linux OS, if you get permission errors while running the Docker container, then you may need to tweak the UID and GID values to match values that are valid for the Linux user running the Maven commands.

To be able to change these values, add the following properties in the docker.run profile configuration:

<profile>
  <id>docker.run</id>
  <properties>
    ...
    <docker.brxm.container.dev.gid>new_gid_value</docker.brxm.container.dev.gid>
    <docker.brxm.container.dev.uid>new_uid_value</docker.brxm.container.dev.uid>
    ...
  </properties>
</profile>

Or specify this at the command line, which uses the standard Linux id command to list the effective GID and UID for the current user

mvn -P docker.run -Ddocker.brxm.container.dev.gid=`id -g` -Ddocker.brxm.container.dev.uid=`id -u`

In addition to that, when the docker.build profile is run, the Docker image of the Bloomreach Experience Manager project is generated, which is intended for use in production environments. You can change the user properties for this image with the following configuration:

<profile>
  <id>docker.build</id>
  <properties>
    ...
    <docker.brxm.container.gid>new_gid_value</docker.brxm.container.gid>
    <docker.brxm.container.uid>new_uid_value</docker.brxm.container.uid>
    ...
  </properties>
</profile>

How to Execute The Image with Docker Run Command

The docker image of the Bloomreach Experience Manager project can be executed with docker run command as follows.

docker run -p 8080:8080 org.example/myproject:0.1.0-SNAPSHOT

The docker image contains other configuration variables such as repository variables, other JVM variables and tomcat variables. You can configure these variables as well. To learn how to set these variables, please refer to Set Environment-Specific Configuration with Docker.

Log4j Configuration

The Bloomreach Experience Manager project already has Log4j configured out-of-the-box. The conf/log4j2-docker.xml and conf/log4j2-dev.xml are the configuration files for the production image and the development image respectively. Another configuration option is conf/log4j2-dist.xml file that allows to save logs to the files with production level parameters. This configuration file for the production image can be set by changing the definition in src/main/docker/assembly/conf-component-docker.xml file as follows.

 <files>
    <file>
      <source>conf/log4j2-dist.xml</source>
      <outputDirectory>conf</outputDirectory>
      <destName>log4j2.xml</destName>
    </file>
 …
 <files>