Set Environment-Specific Configuration with Docker

Overview

This page explains how to configure a Bloomreach Experience Manager Docker image for a specific environment. It covers default environment variables, methods for overriding configuration, and requirements for running with different databases.

Default Environment-Specific Configuration with Docker

The Bloomreach Experience Manager Docker image sets several system and environment variables by default. These variables are defined in both the dockerFile and the setenv.sh script used by Tomcat.

The following environment variables are set in the dockerFile:

# Default JVM heap size variables
ENV JAVA_MINHEAP "256m"
ENV JAVA_MAXHEAP "512m"

# Default tomcat http max threads variable
ENV TOMCAT_MAXTHREADS "200"

# Default repository settings
ENV REPO_PATH "${docker.brxm.project.path}/target/storage"
ENV REPO_CONFIG ""
ENV REPO_BOOTSTRAP "false"
ENV REPO_AUTOEXPORT_ALLOWED "false"

# Default database profile
ENV profile "h2"

Additional variables are set in the setenv.sh script located in Tomcat’s bin directory:

# Repository configurations
REP_OPTS="-Drepo.path=${REPO_PATH} -Drepo.bootstrap=${REPO_BOOTSTRAP} -Drepo.config=${REPO_CONFIG} -Drepo.autoexport.allowed=${REPO_AUTOEXPORT_ALLOWED}"

# Logging configurations
L4J_OPTS="-Dlog4j.configurationFile=file://${CATALINA_HOME}/conf/log4j2.xml -DLog4jContextSelector=org.apache.logging.log4j.core.selector.BasicContextSelector"

# JVM heap size options
JVM_OPTS="-server -Xms${JAVA_MINHEAP} -Xmx${JAVA_MAXHEAP} -XX:+UseG1GC -Djava.util.Arrays.useLegacyMergeSort=true"

# JVM garbage Collector options
VGC_OPTS="-verbosegc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:${CATALINA_HOME}/logs/gc.log -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=2048k"

# JVM heapdump options
DMP_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=${CATALINA_HOME}/temp"

CATALINA_OPTS="${JVM_OPTS} ${VGC_OPTS} ${REP_OPTS} ${DMP_OPTS} ${L4J_OPTS}"

Note:
If Tomcat startup is slow and you see the following warning in the logs:

WARNING [main] org.apache.catalina.util.SessionIdGeneratorBase.createSecureRandom Creation of SecureRandom instance for session ID generation using [SHA1PRNG] took [214,052] milliseconds.

Add -Djava.security.egd=file:/dev/./urandom to the setenv.sh file to improve startup time.

For more details, see the Tomcat wiki.

Override Environment-Specific Configuration with Docker

You can override default environment variables in several ways when running the Docker image.

Using the `docker.run` Maven Profile

Set environment variables in the docker.run Maven profile:

<profile>
  <id>docker.run</id>
  <properties>
    <docker.brxm.envRun.JAVA_MINHEAP>512</docker.brxm.envRun.JAVA_MINHEAP>  
    <docker.brxm.envRun.JAVA_MAXHEAP>1024</docker.brxm.envRun.JAVA_MAXHEAP>   
    <docker.brxm.envRun.TOMCAT_MAXTHREADS>250</docker.brxm.envRun.TOMCAT_MAXTHREADS>
    <docker.brxm.envRun.REPO_PATH>/usr/local/tomcat/repo</docker.brxm.envRun.REPO_PATH>
    <docker.brxm.envRun.REPO_CONFIG>file:/usr/local/tomcat/conf/repository-mysql.xml</docker.brxm.envRun.REPO_CONFIG>
    <docker.brxm.envRun.REPO_BOOTSTRAP>false</docker.brxm.envRun.REPO_BOOTSTRAP>
    <docker.brxm.envRun.REPO_AUTOEXPORT_ALLOWED>false</docker.brxm.envRun.REPO_AUTOEXPORT_ALLOWED>
    <docker.brxm.envRun.REPO_WORKSPACE_BUNDLE_CACHE>512</docker.brxm.envRun.REPO_WORKSPACE_BUNDLE_CACHE>
    <docker.brxm.envRun.REPO_VERSIONING_BUNDLE_CACHE>128</docker.brxm.envRun.REPO_VERSIONING_BUNDLE_CACHE>
    ... 
  </properties>
  ...
</profile>

Passing System Properties on the Command Line

You can also set variables directly when running Maven:

mvn -Pdocker.run -DREPO_PATH=/usr/local/tomcat/repo -DTOMCAT_MAXTHREADS=250

Setting Variables with `docker run`

Pass environment variables to the container using the docker run command:

docker run -e REPO_PATH='/usr/local/tomcat/repo' -e TOMCAT_MAXTHREADS='250' -e profile='mysql' …

Set Jackrabbit Cluster Node ID with Docker

In a clustered deployment, each Bloomreach Experience Manager node must have a unique Jackrabbit cluster node ID. By default, the Docker configuration sets the cluster node ID to the container hostname. To override this, set the REPO_CLUSTER_NODE_ID environment variable.

Set in the `docker.run` Maven Profile

<profile>
  <id>docker.run</id>
  <properties>
    ...
    <docker.brxm.envRun.REPO_CLUSTER_NODE_ID>custom-node-id</docker.brxm.envRun.REPO_CLUSTER_NODE_ID>
    ...
  </properties>
  ...
</profile>

Set as a System Property

mvn -Pdocker.run -DREPO_CLUSTER_NODE_ID=custom-node-id

Provide a Stored Lucene Index

When starting a new container that connects to an existing Bloomreach Experience Manager cluster, the container must generate a local Lucene index during startup. For large or long-lived repositories, this process can be slow. To reduce startup time, you can provide a Lucene index exported from another cluster node.

Starting with Bloomreach Experience Manager version 14.3.0, the default Dockerfile supports using an existing Lucene index at startup. Place the Lucene index zip file (exported using the Lucene Index Export plugin) on the container’s filesystem, typically by mounting a volume. Set the path to the zip file using the LUCENE_INDEX_FILE_PATH environment variable.

For details on exporting the index, see Lucene Index Export.

Required Environment Variables for Database Connections in Non-Development Environments

To run the Bloomreach Experience Manager Docker image with a MySQL or PostgreSQL database, you must set several environment variables. The profile environment variable determines which database type the container connects to. Valid values are h2, mysql, or postgres.

Example: Docker Compose for MySQL

The following sample docker-compose file runs Bloomreach Experience Manager with a MySQL database:

version: "3"
services:
  web:
    image: org.example/myproject:0.1.0-SNAPSHOT
    ports:
      - "8080:8080"
    networks:
      - webnet
    depends_on:
      - mysql
    environment:
     - profile=mysql
  mysql:
    image: mysql
    ports:
      - "3306:3306"
    networks:
      - webnet
    environment:
      - MYSQL_ROOT_PASSWORD=admin   
      - MYSQL_DATABASE=docklog
      - MYSQL_USER=admin
      - MYSQL_PASSWORD=admin
networks:
  webnet:

Default Database Environment Variables

The Dockerfile sets default values for required database environment variables:

# Default mysql variables
ENV MYSQL_DB_HOST mysql
ENV MYSQL_DB_PORT 3306
ENV MYSQL_DB_USER admin
ENV MYSQL_DB_PASSWORD admin
ENV MYSQL_DB_NAME myproject
ENV MYSQL_DB_DRIVER com.mysql.cj.jdbc.Driver

# Default postgres variables
ENV POSTGRES_DB_HOST postgres
ENV POSTGRES_DB_PORT 5432
ENV POSTGRES_DB_USER admin
ENV POSTGRES_DB_PASSWORD admin
ENV POSTGRES_DB_NAME myproject
ENV POSTGRES_DB_DRIVER org.postgresql.Driver

Adjust these variables as needed for your environment and database configuration.