Docker Compose Setup - CMCC 11

Last updated 6 months ago

This guide has multiple versions

CMCC 11
CMCC 10

Learn how to setup a Docker environment and run the CoreMedia system with Docker

What you'll learn

Setting up your Docker environment
Configure Docker for the CoreMedia system
Run the CoreMedia system on Docker

Prerequisites

A built Blueprint workspace

Time matters

Reading time: 20 to 30 minutes

Should I read this?

This guide is for Developers.

Table of Contents

Prerequisites
Starting the Docker Setup

This tutorial will guide you through the first steps to start the CoreMedia Content Cloud Services using docker-compose, which is a tool to simplify the deployment of development environments using Docker.

Prerequisites

Docker knowledge is not required, but for first starters with this technology, it is highly recommended starting with simpler projects until the infrastructure is running and basic knowledge about the tooling has been acquired. As a good start, you can play around online in one of the free tutorials on learndocker or katacoda.

Docker Installation

Mac

Windows

Instead of the commercial Docker Desktop, you can also use free alternatives. Have a look at Docker Installation for details.

Docker Configuration

After the installation was successful and Docker has been started, proceed with the following configurations. If you read the getting started documentation of Docker, you should easily find the corresponding settings.

Increase Disk size to at least 30GB
Increase RAM to at least 14 GB
On Windows, you also need to:
- share the Drive C in the "Shared Drives" settings page.
- enable the "Expose the daemon without TLS" toggle in the general settings page.

Docker Compose Configuration

All relative paths shown here are relative to the global/deployment/docker directory.

Make sure compose/development.yml is included in the COMPOSE_FILE variable, it is required to expose the container internal ports to the docker host.
Make sure compose/development-local.yml is included in the COMPOSE_FILE variable, it is required for content import from Blueprint and optionally for loading licenses from local coremedia-licenses directory.
For the docker-compose development setup, make sure that you have the licenses placed at the following locations:
```
coremedia-licenses/cms-license.zip
coremedia-licenses/mls-license.zip
coremedia-licenses/rls-license.zip
```
Zip files added below this directory are by default excluded from Git version control. Alternatively, you may define environment variables with license URLs and the server containers will download them at runtime. You will find the corresponding environment variables in the .env example below.
For the development setup, make sure that you have created or provide themes. Set either THEMES_ARCHIVE_URL or THEMES_ARCHIVE_FILE in the .env file. To re-import the themes set FORCE_REIMPORT_THEMES to true. If you followed the Quickstart instruction, you don’t have to set anything, because the default is sufficient.
For the development setup, make sure that you have created or provide content. Set either CONTENT_ARCHIVE_URL or CONTENT_IMPORT_DIR in the .env file. To re-import the content set FORCE_REIMPORT_CONTENT to true. If you followed the Quickstart instruction, you don’t have to set anything, because the default is sufficient.

Configure your docker-compose environment by creating or editing your .env file. All environment variable references in the compose files can be configured using this file. Be aware, that environment variables in the current process environment have precedence over variables defined in the .env file.

By default, you can start with this file:

# This sets the compose path separator to ":" for all OS.
COMPOSE_PATH_SEPARATOR=:

# Configure a list of compose files you want to apply and
# separate them using the value of the COMPOSE_PATH_SEPARATOR.
# Be advised that ordering is crucial and last definitions
# override preceding ones.
#  compose/default.yml - unconfigured services
#  compose/development.yml - development configuration
#  compose/development-local.yml - local licenses / content
#
# for most cases this should be your default.
COMPOSE_FILE=compose/default.yml:compose/development.yml:compose/development-local.yml

# Optional properties

# With this variable, you can set the prefix of the image repository.
# Set this to use images from a remote registry, that is,
# REPOSITORY_PREFIX=my.registry/cmcc would result in a studio-server
# image my.registry/cmcc/studio-server
# REPOSITORY_PREFIX=my.registry/cmcc

# With this variable, you can set the prefix of the image repository for
# the Commerce Adapter Docker images. Set this to use images from a remote
# registry.
# COMMERCE_REPOSITORY_PREFIX= my.registry/cmcc

# The version tags of the commerce adapter service images to be used.
# COMMERCE_ADAPTER_MOCK_VERSION=1.2.3
# COMMERCE_ADAPTER_SFCC_VERSION=1.2.3
# COMMERCE_ADAPTER_HYBRIS_VERSION=1.2.3
# COMMERCE_ADAPTER_WCS_VERSION=1.2.3

# The environment fully qualified domain name to use for the system.
# If not set, docker.localhost will be used.
# ENVIRONMENT_FQDN=docker.localhost

# enable debug agent for all spring boot apps. If you want to enable
# this only for a single service, you need to set the environment
# variable explicitly at that service.
# JAVA_DEBUG=true

# Service Specific variables

# The license url/path for the content-management-server
# CMS_LICENSE_URL=/coremedia/licenses/cms-license.zip

# The license url/path for the master-live-server
# MLS_LICENSE_URL=/coremedia/licenses/mls-license.zip

# The license url/path for the replication-live-server
# RLS_LICENSE_URL=/coremedia/licenses/rls-license.zip

# The mail server for elastic social registration mails
# ELASTIC_SOCIAL_MAIL_SMTP_SERVER=localhost

# Theme Import

# Themes can be imported from a file location or from an URL
# pointing to a zip archive containing the themes.
# By default, the variable points to the path
# /coremedia/import/frontend.zip within the management-tools
# container. To pass in an archive from your hosts file system
# include the developmemt-local.yaml file in your
# COMPOSE_FILE environment variable and configure only the path
# on your host system using the THEMES_ARCHIVE_FILE env var.
# If you don't configure that variable, the default will point
# to the frontend.zip in your workspace.
# THEMES_ARCHIVE_URL=
# THEMES_ARCHIVE_FILE=

# Force reimport of themes when set to true
# FORCE_REIMPORT_THEMES=false

# Content Import

# The directory from which the content should be imported. By default,
# this points to the target/content directory of the test-data module
# in the CoreMedia Blueprint workspace.
# CONTENT_IMPORT_DIR=

# Forces the reimport of the content when set to true
# FORCE_REIMPORT_CONTENT=false

# The url of a webserver, serving all content blobs during the
# server-import. If you added the content blobs to the workspace,
# you can leave this field empty. This is a CI development
# optimization to keep content image blobs out of the VCS history.
# BLOB_STORAGE_URL=

# The url to a zip archive containing content, users and optionally
# themes for import. The layout in the archive should be the same
# as the test-data module creates. This is a CI development feature
# to import content from a separated build process.
# CONTENT_ARCHIVE_URL=

# Skips the whole content and theme import when set to true
# SKIP_CONTENT=false

Depending on the eCommerce system(s) you want to connect to, you will need to set these additional variables:

HCL WebSphere Commerce

SPRING_PROFILE=dev-wcs
COMPOSE_FILE=compose/default.yml:compose/development-wcs.yml
WCS_HOST=your.wcs.host

SAP Hybris

COMPOSE_FILE=compose/default.yml:compose/development-hybris.yml

Salesforce Commerce Cloud

COMPOSE_FILE=compose/default.yml:compose/development-sfcc.yml

Note that you cannot set arbitrary environment variables in the .env file and expect, that they will be picked up by the CoreMedia Spring Boot applications. Only the variables, being referenced in compose files, can be used here.

For more information about this tooling option, visit the official Docker Compose documentation.

DNS Configuration

To access the applications, you need to configure your hosts DNS resolution. Changing this requires admin rights.

Without Administrator rights

Without administrator rights, you need to set the following environment variables in the .env file to the DNS resolvable host name of your computer:

ENVIRONMENT_FQDN
CMS_ORB_HOST
MLS_ORB_HOST
WFS_ORB_HOST

With Administrator rights

With administrator rights edit the configuration file for the host mappings at the following locations:

On Linux / Mac OS /etc/hosts
On Windows %SystemRoot%\System32\drivers\etc\hosts

Make sure that it contains the following mappings:

# Development names to connect from Maven / IDEA
127.0.0.1 workflow-server
127.0.0.1 content-management-server

# Administrative Hosts
127.0.0.1 docker.localhost
127.0.0.1 overview.docker.localhost
127.0.0.1 monitor.docker.localhost

# Corporate Hosts
127.0.0.1 corporate-de.docker.localhost
127.0.0.1 corporate.docker.localhost

# Management Hosts
127.0.0.1 studio.docker.localhost
127.0.0.1 preview.docker.localhost
127.0.0.1 site-manager.docker.localhost

# Commerce Hosts
127.0.0.1 helios.docker.localhost
127.0.0.1 calista.docker.localhost
127.0.0.1 apparel.docker.localhost
127.0.0.1 sitegenesis.docker.localhost
127.0.0.1 shop-preview-ibm.docker.localhost
127.0.0.1 shop-ibm.docker.localhost
127.0.0.1 shop-preview-production-ibm.docker.localhost
127.0.0.1 shop-preview-hybris.docker.localhost
127.0.0.1 shop-hybris.docker.localhost
127.0.0.1 shop-preview-sfcc.docker.localhost
127.0.0.1 shop-sfcc.docker.localhost
127.0.0.1 shop-tools-sfcc.docker.localhost

Reducing the Setup

If you do not want to start the whole stack, you can start only the required components. All services define their dependencies using the depends_on directive. Running a simple docker-compose up -d content-management-server workflow-server therefore will also start MySQL, MongoDB and Solr.

You can get all available services by running docker-compose config --services

A different approach is to freeze the setup and then cut out everything you need.

docker-compose config > docker-compose.yml

You can then remove everything you don’t want. docker-compose.yml is ignored by Git with the default .gitignore file. You only have to make sure, that in your .env file

COMPOSE_FILE=docker-compose.yml

is set, otherwise the file won’t be loaded.

Of course. there are a lot of toggles for your convenience:

JAVA_DEBUG - default ports XXX06 for JDWP
FORCE_REIMPORT_CONTENT - once imported, the content won’t reimport unless forced
SKIP_CONTENT - same as not running the management-tools container

Having multiple backends in parallel or keep multiple backend data volumes

In order to work on multiple tasks in an interleaved mode, you may want to keep the example content of each setup and switch back and forth. In order to do so, you can use the COMPOSE_PROJECT_NAME. If set docker-compose will prefix all resources with the set value, that is, a volume will be named JIRA-55_db-data if COMPOSE_PROJECT_NAME=JIRA-55. The only thing to keep in mind with this approach is to never use the -v flag when running docker-compose down.

Starting the Docker Setup

Make sure that you have built the workspace and the Docker images. To build the Docker images, the Maven profile default-image must be activated. To check whether you have built the images you can list the available images using the following command:

docker images

The result should look like this but should contain image names like cae-live or content-server:

REPOSITORY                 TAG     IMAGE ID      CREATED       SIZE
coremedia/cae-preview      latest  a8f9d245fbbe  10 hours ago  296MB
coremedia/content-server   latest  8f6045472222  10 hours ago  272MB

If there are no images listed, you probably did not activate the Maven profile. To build with the active Maven profile, run the following command:

mvn clean install -Pdefault-image

After the images have been built, you can change the directory to the Docker setup:

cd global/deployment/docker

Prestart Check

To make sure that there are no conflicts with pre-existing setups, you can run the following steps to delete all pre-existing setups:

docker-compose down -v this command should stop and remove all running containers and volumes that are associated with the project defined by the compose files. The execution of this command needs to be successful to start up a new clean system. The warnings can be ignored, because if the volume does not exist, it cannot be removed.
docker ps --format "table {{.Names}}\t{{.Ports}}" -a this command lists all running containers and their mapped ports. Make sure that these ports do not conflict with the standard port mappings of the CoreMedia applications, when run on a single node.

Start the services

To list the services that will be started, execute the following command:

docker-compose config --services

The result should look similar to this, depending on the value of COMPOSE_FILE:

mysql
mongodb
solr
content-management-server
master-live-server
replication-live-server
workflow-server
content-feeder
cae-feeder-preview
cae-feeder-live
user-changes
elastic-worker
studio-server
studio-client
cae-preview
cae-live
site-manager
headless-server-preview
headless-server-live
traefik

Now you can start the services by running the following command:

docker-compose up -d --build

The flag --build forces docker-compose to build the images, which are not included into the Maven build and which are only required in the development setup, such as mysql, mongodb, overview, traefik and the commerce proxies. You can omit this flag on subsequent builds, if there aren’t any changes to these images.

The result should look like the following output.

Creating elastic-worker            ... done
Creating traefik                   ... done
Creating mongodb                   ... done
Creating management-tools          ... done
Creating master-live-server        ... done
Creating headless-server-preview   ... done
Creating studio-client             ... done
Creating cae-live                  ... done
Creating cae-preview               ... done
Creating replication-live-server   ... done
Creating cae-feeder-live           ... done
Creating solr                      ... done
Creating overview                  ... done
Creating content-management-server ... done
Creating mysql                     ... done
Creating studio-server             ... done
Creating workflow-server           ... done
Creating headless-server-live      ... done
Creating content-feeder            ... done
Creating site-manager              ... done
Creating user-changes              ... done
Creating cae-feeder-preview        ... done

Wait until the services are healthy

To make sure that the system is up and running and all services are healthy, you can use the docker ps command. By default, it will print out the healthy state for each service.

docker ps

The result should look like this excerpt:

cae-preview    coremedia/cae-preview    Up About a minute (healthy)
cae-live       coremedia/cae-preview    Up About a minute (unhealthy)
studio-server  coremedia/studio-server  Up About a minute (health:starting)

Now you have to wait until all services are healthy. You can track this by either running a command loop in your shell, or by visiting the overview page in your browser.

Watch health state using the overview page

Open the overview page and scroll down to the table where the status is shown on the right side. In case the service is healthy or unhealthy, a green or red icon is shown.

Watch health state using the shell

On Linux / Mac OS
```
watch -n 1 "docker ps"
```

On Windows (PowerShell)

while($true) { Clear-Host; docker ps; sleep 5 }

For better visibility of this command, you can configure the formatting by editing/creating the ~/.docker/config.json with the following content:

{
  "psFormat" : "table {{.Names}}\\t{{.Image}}\\t{{.Status}}"
}

Login to CoreMedia Studio

Click on the Open Studio link at the top of the overview page or simply open the link to Studio directly by using the previously configured domain name:

Note that the import of the test data may take some time. So, you may not be able to login immediately as one of the predefined users like Rick C or some content is missing. However, logging in as user admin should work, you can then watch the test data rolling in.

Cleanup Services

To shut down the services, simply run the following command:

docker-compose down

Cleanup Services

To shut down the services, simply run the following command:

docker-compose down

Cleanup Services and Content

To shut down all services and clear all created volumes including the databases, simply run the following command:

docker-compose down -v

This guide has multiple versions

CMCC 11
CMCC 10

Is this page useful?