Set Environment-Specific Configuration with Docker

Introduction

Goal

Configure a Bloomreach Experience Manager Docker image for a specific environment.

Background

To facilitate running on different platforms with various configurations, the Bloomreach Experience Manager Docker image contains several configuration variables such as repository variables, several JVM variables, and Tomcat variables.

Default Environment-Specific Configuration with Docker

Default system and environment variables are set both in dockerFile in the docker image and in the setenv.sh bash file that is used to set environment variables in a Tomcat instance.

The following variables are set in dockerFile by default:

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

Other system and environment variables are set in setenv.sh bash file in Tomcat’s bin folder as follows:

# 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}"

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

Setting Environment-Specific Configuration with Docker

If you use the docker.run Maven profile to run the Docker image, you can set the following environment variables to docker.run profile configuration:

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

Or you can pass them on the command-line using as system properties:

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

You can also set the environment variables by passing parameters to the docker run command:

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

Setting Jackrabbit Cluster Node Id with Docker

When the Bloomreach Experience Manager application runs in a clustered environment, the Jackrabbit cluster node ID should be set properly. Each node must have a unique cluster node id in the cluster. In the default docker configuration, the Jackrabbit cluster node ID is set with the hostname of the container. If you need to change the default value, you can define a new value by setting the REPO_CLUSTER_NODE_ID environment variable.

Define REPO_CLUSTER_NODE_ID in the docker.run profile configuration:

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

or pass it on the command-line using as system property:

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

Provide a Stored Lucene Index

When starting a new container to connect to an existing Bloomreach Experience Manager cluster, a new local lucene index must be generated during the startup process. This can be very time-consuming for a large or long-lived repository. To accelerate this part of the startup process, a container can be seeded with an existing lucene index that was exported from an existing cluster node. See the Lucene Index Export docs for more information.

As of Bloomreach Experience Manager version 14.3.0, the default Dockerfile provided by the project archetype supports using an existing lucene index at container startup. To use this, a zip file produced by the Lucene Index Export plugin must be available on the new container's file system, typically by mapping it to a container volume. Set the location of the index zip file in the environment variable LUCENE_INDEX_FILE_PATH.

Required Environment Variables to Run the Image With a Database In Non-Development Environment

Several environment variables are supposed to be set to run the Bloomreach Experience Manager docker image with a MySQL or a Postgres database instance. The environment variable named profile defines which database type the Bloomreach Experience Manager container will connect to. The profile variable can have one of the following values: h2, mysql, postgres.

As an example, to run the Bloomreach Experience Manager image with a mysql database, a sample docker compose file is as follows:

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:

The other environment variables that are required to run the image with a database are set in Dockerfile. The default values of these environment variables are as follows. 

# 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