Docker Compose Setup - CMCC 10

Last updated 4 minutes ago
This guide has multiple versions

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

LightbulbWhat you'll learn

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

Person reading a bookPrerequisites

  • A built Blueprint workspace

WristwatchTime matters

Reading time: 20 to 30 minutes

Person in front of a laptopShould I read this?

This guide is for Developers.

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

  • Installer

  • Getting Started

  • Make sure that the following paths and files are excluded from being scanned by any real time virus scanner:

    • The location of Hyper-V :

      C:\ProgramData\Microsoft\Windows\Hyper-V
    • The location of your disk image. The defaults are

      C:\Users\Public\Documents\Hyper-V\Virtual hard disks\MobyLinux.vhxd
    • The executables for virtualization

      vmms.exe
      vmwp.exe
    • The file extensions for virtualization files:

      VHD
      VHDX
  • Make sure that no process is already listening on ports 80 and 443. You may run net stop http in an elevated PowerShell to stop these processes. If port 80 is still blocked, you may need to stop the WWW web publisher service as well.

  • Be careful with hibernation, make sure to stop all containers, before hibernate your workstation.

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.

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

  • 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 preceeding 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 an 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 Bluprints 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.

  1. List all services

    cd global/deployment/docker
    docker-compose config --services
  2. From the list of services make a space separated list of services you want to start and put them in an environment variable, that is, for example:

    export DC_DB="mongodb mysql"
    export DC_MANAGEMWENT_BACKEND="${DC_DB} solr content-management-server \
           workflow-server content-feeder caefeeder-preview user-changes \
           elastic-worker studio-server"
    export DC_PUBLICATION_BACKEND="master-live-server caefeeder-live"
    export DC_PREVIEW="cae-preview studio-client traefik"
    export DC_LIVE="cae-live" export DC_CONTENT=management-tools
  3. Now you can use this to start what you most often need:

    docker-compose up -d ${DC_DB} ${DC_MANAGEMENT_BACKEND} ${DC_CONTENT} overview

    overview is not a docker command, but the overview service with all the links.

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 build the workspace and the Docker images. To build the Docker images the Maven profile with-docker must be activated. To check whether you have build 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 -Pwith-docker

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

cd global/deployment/docker

Prestart Check

In order to make sure that there are no conflicts with preexisting setups, you can run the following steps to delete all preexisting 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 https://overview.docker.localhost 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:

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
Copyright © 2024 CoreMedia GmbH, CoreMedia Corporation. All Rights Reserved.