Run and Develop with Docker

Introduction

Goal

Use Docker to run your Bloomreach Content project in a local development environment.

What is Docker

Docker is a platform for building, deploying, and running applications in containers. For development, run both the CMS and HST site applications inside a single container using Maven. The standard Maven POM provided by the project archetype includes a pre-configured Maven Docker plugin. This page describes how to use the default Docker setup: running, debugging, and customizing the configuration.

Install and Start Docker

Download and install Docker if it is not already installed. Start Docker before building the image in the next step.

Info: Refer to System Requirements for supported Docker versions.

Build a Docker Image

The Bloomreach Content Release POM provides a dedicated Maven profile for building a Docker image of your project. Review the Release POM and its Docker configuration in the Bloomreach Content Maven repository. For details about Maven profiles, see the Maven build profiles introduction.

Info: At the time of writing, the Release POM sets the Maven Docker plugin version to 0.33.0. You can override this in your project's root POM under <properties>:
<docker.maven.plugin.version>0.46.0</docker.maven.plugin.version>
For the latest version, see https://github.com/fabric8io/docker-maven-plugin/releases.

To build a Docker image for your Bloomreach Content project, run the following commands from the project root. These commands compile, package, and then build a Docker image from the packaged artifacts.

mvn clean install
mvn -P docker.build

Info: Always use mvn install instead of mvn verify when building the Docker image. The Docker plugin requires the artifacts to be installed in the local Maven repository.

Base Image & Default Dockerfile

The base image for your project is set by the Maven property docker.brxm.base.image and referenced in src/main/docker/Dockerfile, which is included by the archetype.

By default:

brXM 14 uses tomcat:9-jdk8-openjdk-slim
brXM 15 uses tomcat:9-jdk11-openjdk-slim
brXM 16 uses tomcat:10.1-jdk17-temurin

These are official Tomcat images from Docker Hub and use the latest tag for their respective OpenJDK versions. The latest tag updates as new Tomcat versions are released.

To use a specific Tomcat version, override the Maven property with a value such as 9.0.29-jdk8-openjdk-slim.

You are not required to use official Docker Hub images, but using a different base image may require changes to the Dockerfile.

Included JDBC Driver Versions

Docker images built with the provided support files include JDBC drivers for MySQL, PostgreSQL, and H2. The container selects the appropriate driver and configuration based on environment variables at startup. The Release POM properties mysql.connector.version and postgres.connector.version control the JDBC driver versions. You can override these in your project POM if needed.

Run with Docker for Development

To start the Docker container for local development, run:

mvn -P docker.run

Run this command from the project root. By default, the container uses an H2 database and stores data in the /target/storage directory, which is bind-mounted into the container.

Hint: The local project is bind-mounted into the container, and auto-export is enabled. This setup enables full developer experience features while running in Docker.

When you run the docker.run profile, Maven creates an intermediate image for development. This image includes additional development artifacts:

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

Info: Windows users:
On Unix systems, Docker uses the socket /var/run/docker.sock by default.
On Windows, this socket is not available. Starting with brXM 14.3, you must expose the Docker daemon on tcp://localhost:2375 when using Windows.
For Docker Engine on Windows, follow these instructions to enable it.
For Docker Desktop, enable the option as described here (a restart is required).

Docker DB Profiles

You can run the container with alternative database types by combining secondary profiles with docker.run.

mvn -P docker.run,docker.mysql

mvn -P docker.run,docker.postgres

When you specify one of these profiles, Maven creates and links a database container (MySQL or PostgreSQL) to the main Bloomreach Content container using a private network. Data is stored in /target/mysql-data or /target/postgres-data by default. The default database credentials are admin:admin. You can override these by setting docker.db.username and docker.db.password in your project POM. The database port is randomly assigned by default, but you can set it explicitly with the docker.db.port property.

SQL Bootstrapping

To initialize the database with SQL scripts, place .sql or .sql.gz files in a /db-bootstrap directory at the project root. The container executes these files in alphabetical order. Use this to create databases or import data from backups.

DB Image Versions

The base images for the database containers are set by the docker.mysql.image and docker.postgres.image Maven properties. Override these in your project POM if you need different versions.

Connect to an External DB

You can connect the Bloomreach Content container to an external MySQL or PostgreSQL database. Configure the connection using the Maven properties docker.db.host, docker.db.port, docker.db.schema, docker.db.username, and docker.db.password. The defaults connect to the standard port on localhost. Then run with the following profiles (note the missing docker. prefix):

mvn -P docker.run,mysql

mvn -P docker.run,postgres

Debug with Docker

The Docker profile for Bloomreach Content supports remote debugging. By default, Java debuggers can attach to port 8000. Connect your debugger to this port. For Eclipse, see Develop with Eclipse.

By default, Tomcat starts immediately without waiting for a debugger. To suspend startup until a debugger attaches, set the property docker.brxm.debug.suspend=y when running the docker.run profile:

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

This is useful for debugging startup and initialization. The JVM will pause until a debugger is attached.

To use a different port for remote debugging, set the docker.brxm.debug.port property:

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

Run with Docker without Development Repository Data

By default, projects based on the Maven archetype include repository-data-development and repository-data-site-development JAR modules, which are deployed to Tomcat's shared/lib directory. To omit these modules, use the without-development-data profile together with docker.run:

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

This prevents deployment of the development data JARs. Use this approach when testing an upgraded project with a copy of a production repository.

Run with Docker using Different Port Numbers

By default, the container's HTTP port maps to port 8080 on the host. To change this, set the docker.brxm.http.port property in the docker.run profile:

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

Alternatively, set the port on the command line:

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

Update the delivery tier configuration in the Console to match the new HTTP port:

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

Pass Additional System Properties

Add JVM arguments to the docker.run plugin configuration using the docker.brxm.jvm.args property in your main POM:

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

Or set them on the command line:

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

Run with Docker on Local Linux OS

You can customize the UID (user identifier), GID (group identifier), and username for the container user using the properties docker.brxm.container.dev.uid, docker.brxm.container.dev.gid, and docker.brxm.container.dev.username. The Release POM sets the following defaults:

<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>

The Docker container uses a shared directory defined by the volume in the docker.run profile. On local Linux, if you encounter permission errors, adjust the UID and GID values to match your local user.

To set these values, add them to the docker.run profile:

<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 set them on the command line using the standard Linux id command:

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

When you run the docker.build profile to create a production image, you can also set the user properties for that image:

<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>

Execute the Image with Docker Run Command

You can run the Bloomreach Content Docker image directly with the following command:

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

The Docker image supports configuration via environment variables for repository, JVM, and Tomcat settings. For details, see Set Environment-Specific Configuration with Docker.

Hint: By default, the container uses an embedded H2 database. You can configure the database type and connection properties with environment variables passed to the docker run command. See Set Environment-Specific Configuration with Docker. for details.

Log4j Configuration

Bloomreach Content projects include Log4j configuration by default. Use conf/log4j2-docker.xml for production images and conf/log4j2-dev.xml for development images. The conf/log4j2-dist.xml file provides production-level logging to files. To use this configuration in the production image, update src/main/docker/assembly/conf-component-docker.xml as follows:

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