C:\ProgramData\Microsoft\Windows\Hyper-V
Docker Compose Setup - CMCC 10
- 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
Should I read this?
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
-
Make sure that the following paths and files are excluded from being scanned by any real time virus scanner:
-
The location of 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 theWWW 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 theCOMPOSE_FILE
variable, it is required to expose the container internal ports to the docker host. -
Make sure
compose/development-local.yml
is included in theCOMPOSE_FILE
variable, it is required for content import from Blueprint and optionally for loading licenses from localcoremedia-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
orTHEMES_ARCHIVE_FILE
in the.env
file. To re-import the themes setFORCE_REIMPORT_THEMES
totrue
. -
For the development setup, make sure that you have created or provide content. Set either
CONTENT_ARCHIVE_URL
orCONTENT_IMPORT_DIR
in the.env
file. To re-import the content setFORCE_REIMPORT_CONTENT
totrue
. -
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.
-
List all services
cd global/deployment/docker docker-compose config --services
-
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
-
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 portsXXX06
for JDWP -
FORCE_REIMPORT_CONTENT
- once imported, the content won’t reimport unless forced -
SKIP_CONTENT
- same as not running themanagement-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
- CMCC 11
- CMCC 10