Installing SFMC Behavioral Data Exchange on containers

Walkthrough: Preparing to install SFMC Behavioral Data Exchange in a container environment

Version:

To prepare for adding the Sitecore Connect for Salesforce Marketing Cloud Behavioral Data Exchange connector (SFMCBDE) to your container installation, regardless of whether you are deploying to Docker or Azure Kubernetes Service, follow the steps in this walkthrough.

Before you install SFMCBDE for containers, you must have the following:

Docker Desktop installed and running. For instructions on how to set up the Docker environment, see the documentation.
If the installation is done on Docker, you must have the Sitecore Docker container files deployed on a local machine. For instructions on how to prepare the Sitecore containers, see the Installation Guide for Developer Workstation with Containers on the Sitecore download page.
If the installation is done on Kubernetes, you must have the Sitecore AKS container files deployed on a local machine. For instructions on how to prepare a Sitecore environment with Kubernetes, see the Installation Guide for Production Environment with Kubernetes on the Sitecore download page.
An SFMC account where you can create an installed package with appropriate access rights.

This walkthrough describes how to:

Add an API integration package to your SFMC installation
Prepare an SFMC connection string
Prepare the installation files
Build the Docker images

Add an API integration package to your installation

To add an API integration package to your Salesforce Marketing Cloud (SFMC) installation:

Follow the steps in the Marketing Cloud Package Development documentation for Salesforce, in the Create and Install Packages section.
Select the Server-to-Server integration type for the API Integration package.
Add the following required rights for your connection:
Category Type Rights
Data Data Extensions
Read
Write
If you use the SFMCBDE Activity for Marketing Automation functionality, you must also add the following rights for your connection:
Category Type Rights
Automation Journey
Read
Write
Execute
Contacts List and Subscribers
Read
Write

Category	Type	Rights
Data	Data Extensions	Read Write

Category	Type	Rights
Automation	Journey	Read Write Execute
Contacts	List and Subscribers	Read Write

Prepare an SFMC connection string to your Sitecore installation

To construct a Salesforce Marketing Cloud (SFMC) connection string to your Sitecore installation:

In Salesforce, in the component you created, in the Components area, make a note of the following values:
- Client ID
- Client secret
- Authentication base URI
- REST Base URI
- SOAP Base URI

Use the values to construct a connection string with this format:


ConnectionString_sfmc=client id=<Client ID>;
                      client secret=<Client secret>;
                      auth endpoint=<Authentication base URI>;
                      rest endpoint=<REST Base URI>;
                      soap endpoint=<SOAP Base URI>" />

Prepare the installation files

To prepare the files you need for the installation:

Download the SFMCBDE container deployment package from the Sitecore download page. Extract it to your local workstation with the folder structure intact.
Go to the folder into which you extracted the SFMCBDE container deployment package. Go to the SFMCBDE folder for the Windows version and topology you are using, for example, SFMCBDE\compose\ltsc2019\xp1.
Open the .env-example file in an editor. Copy all the variables to the clipboard.
Go to the Sitecore container deployment folder on your local machine. Go to the folder for the Windows version and topology you are using, for example, compose\ltsc2019\xp1.
Open the .env file in an editor, and paste in the variables from the SFMCBDE .env-example file. Replace the default value for ConnectionString_sfmc with the connection string you prepared in ???.
From the SFMCBDE compose\<version>\<topology> folder, copy the docker-compose.override.yml file to the Sitecore container deployment compose\<version>\<topology> folder (where the docker.compose.yml file is).

Build the Docker images

When you have prepared the installation files, you must create Docker files for each role, and build the Docker images.

Note

For more information on image assets, see the documentation on how to Add Sitecore Modules.

To build the images:

Go to the Sitecore container deployment folder on your local machine. Go to the folder for the Windows version and topology you are using, for example, compose/ltsc2019/xp1. Create a folder and name it module.
In the module folder, create these subfolders:
- cm
- xconnect
- xdbautomationworker
- xdbsearchworker
In each subfolder, create a new file and name it Dockerfile.

In the cm folder, in the Dockerfile file, enter the following instructions:


# escape=`

ARG BASE_IMAGE
ARG SFMCBDE_IMAGE
ARG DEF_IMAGE
ARG TOOLING_IMAGE

FROM ${DEF_IMAGE} as def
FROM ${SFMCBDE_IMAGE} as sfmcbde
FROM ${TOOLING_IMAGE} as tooling
FROM ${BASE_IMAGE}

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

#Add tools from sitecore-docker-tools-assets
COPY --from=tooling \tools\ C:\tools\

# Add DEF module
COPY --from=def \module\cm\content C:\inetpub\wwwroot

# Add SFMCBDE module
COPY --from=sfmcbde \module\cm\content C:\inetpub\wwwroot

# Copy transformation file to add SFMCBDE connection strings in Sitecore config file
COPY --from=sfmcbde \module\xdttransform\cm\transforms\App_Config\ConnectionStrings.config.xdt  C:\transforms\role\App_Config\ConnectionStrings.config.xdt

# Copy transformation file to update value for Sitecore.Services.SecurityPolicy in Sitecore.Services.Client.config
COPY --from=sfmcbde \module\xdttransform\cm\transforms\App_Config\Sitecore\Services.Client C:\transforms\role\App_Config\Sitecore\Services.Client

RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path C:\inetpub\wwwroot -XdtPath C:\transforms\role

In the xconnect folder, in the Dockerfile file, enter the following instructions:


# escape=`
ARG BASE_IMAGE
ARG SFMCBDE_IMAGE

FROM ${SFMCBDE_IMAGE} as sfmcbde
FROM ${BASE_IMAGE}

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

# Copy models file into xconnect
COPY --from=sfmcbde \module\xconnect\content C:\inetpub\wwwroot

In the xdbsearchworker folder, in the Dockerfile file, enter the following instructions:


# escape=`

ARG BASE_IMAGE
ARG SFMCBDE_IMAGE

FROM ${SFMCBDE_IMAGE} as sfmcbde
FROM ${BASE_IMAGE}

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

# Copy models file into index worker
COPY --from=sfmcbde \module\xdbsearchworker\content C:\service\

In the xdbautomationworker folder, in the Dockerfile file, enter the following instructions:


# escape=`

ARG BASE_IMAGE
ARG SFMCBDE_IMAGE
ARG DEF_IMAGE
ARG TOOLING_IMAGE

FROM ${DEF_IMAGE} as def
FROM ${SFMCBDE_IMAGE} as sfmcbde
FROM ${TOOLING_IMAGE} as tooling
FROM ${BASE_IMAGE}

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

#Add tools from sitecore-docker-tools-assets
COPY --from=tooling \tools\ C:\tools\

# Add DEF module
COPY --from=def \module\xdbautomationworker\content C:\service

# Add SFMCBDE module
COPY --from=sfmcbde \module\xdbautomationworker\content C:\service

#Copy transformation files
COPY --from=sfmcbde \module\xdttransform\xdbautomationworker\transforms\ C:\transforms\role

# Add SFMCBDE connection strings in Sitecore config file
# Add SfmcJourneyInformation node in sc.MarketingAutomation.ContactLoader.xml file
RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path C:\service -XdtPath C:\transforms\role

In the compose\<version>\<topology>\docker-compose.override.yml file, add build instructions for each role. If you are using, for example, the XP1 topology, the file looks like this:


services:
  cm:
    image: sitecore-sfmcbde-xp1-cm:${SITECORE_VERSION}
    build:
      context: ./module
      dockerfile: ./cm/Dockerfile
      args:
        BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-cm:${SITECORE_VERSION}
        DEF_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-def-xp1-assets:${DEF_VERSION}
        SFMCBDE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcbde-xp1-assets:${SFMCBDE_VERSION}
        TOOLING_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION}
    environment:
      Sitecore_ConnectionStrings_sfmc: ${ConnectionString_sfmc}
      Sitecore_ConnectionStrings_TenantService: ${ConnectionString_TS}

  xdbautomationworker:
    image: sitecore-sfmcbde-xp1-xdbautomationworker:${SITECORE_VERSION}
    build:
      context: ./module
      dockerfile: ./xdbautomationworker/Dockerfile
      args:
       BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-xdbautomationworker:${SITECORE_VERSION}
        DEF_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-def-xp1-assets:${DEF_VERSION}
        SFMCBDE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcbde-xp1-assets:${SFMCBDE_VERSION}
        TOOLING_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION}
    environment:
      Sitecore_ConnectionStrings_TenantService: ${ConnectionString_TS}

  xdbsearchworker:
    image: sitecore-sfmcbde-xp1-xdbsearchworker:${SITECORE_VERSION}
    build:
      context: ./module
      dockerfile: ./xdbsearchworker/Dockerfile
      args:
        BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-xdbsearchworker:${SITECORE_VERSION}
        SFMCBDE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcbde-xp1-assets:${SFMCBDE_VERSION}

  xdbsearch:
    image: sitecore-sfmcbde-xp1-xdbsearch:${SITECORE_VERSION}
    build:
      context: ./module
      dockerfile: ./xconnect/Dockerfile
      args:
        BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-xdbsearch:${SITECORE_VERSION}
        SFMCBDE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcbde-xp1-assets:${SFMCBDE_VERSION}

  xdbcollection:
    image: sitecore-sfmcbde-xp1-xdbcollection:${SITECORE_VERSION}
    build:
      context: ./module
      dockerfile: ./xconnect/Dockerfile
      args:
        BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-xdbcollection:${SITECORE_VERSION}
        SFMCBDE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcbde-xp1-assets:${SFMCBDE_VERSION}

If you are not deploying the Tenant Service, remove the id and cd images from the docker-compose.override.yml file.
In the compose\<version>\<topology>\.env file, add the asset image version. For example:
DEF_VERSION=<image version for your topology> SFMCBDE_VERSION=<image version for your topology> SITECORE_TOOLS_REGISTRY=scr.sitecore.com/tools/ TOOLS_VERSION=<image version for your topology>
Note
You can find the image version in the Sitecore Docker Images repository.

If you are deploying in Docker with the Tenant Service, continue with the instructions in Walkthrough: Installing SFMC Behavioral Data Exchange in Docker with the Tenant Service.

If you are deploying in Docker without the Tenant Service, continue with the instructions in Install SFMC Behavioral Data Exchange in Docker without the Tenant Service

If you are deploying in Azure Kubernetes Service with or without the Tenant Service, continue with the instructions in Walkthrough: Adding SFMCBDE to Sitecore in Azure Kubernetes Service

If you have suggestions for improving this article, let us know!