Sync items with a running container

Current version: 10.1

This topic explains how you push and pull serialized items when you have a local Sitecore environment running in containers. You must already know how to serialize Sitecore items and use serialization when you develop and deploy Sitecore solutions.

Sitecore CLI / Sitecore Content Serialization

The Sitecore CLI that is available in Sitecore 10, and later, is optimized for interaction with a remote Sitecore instance. You can use commands such as sitecore ser pull, sitecore ser push, and sitecore ser watch with a Sitecore environment running in containers just as you can any other Sitecore instance.

Sitecore TDS

Because Sitecore TDS communicates via an HTTP-based service, it functions exactly the same when your Sitecore environment is in containers as it does with any other Sitecore instance. You must be aware of how to set up your container environment and TDS project in Visual Studio, so that TDS can successfully install its connector into your CM container.

The Helix.Examples repository on GitHub includes a complete example.

Configuring your TDS project for containers

The Sitecore TDS documentation has details, but the basic steps are:

Set up your CM container Dockerfile and entrypoint for runtime file deployment, as you would for your Visual Studio builds.
Configure the Sitecore Web Url in your TDS project to the host name you use for the CM service in your Sitecore container environment.
- In the Docker Examples repository, this would be https://cm.dockerexamples.localhost.
- Do not forget the https.
Configure the Sitecore Deploy Folder in your TDS project to the path that has been mounted for Sitecore CM file deployment, for example the docker\deploy\website folder. The path must be relative to the location of the TDS project.
Check the Enable container deploymentoption in your TDS project. This optimizes some behaviors of the TDS service install for container based environments.
Check the Install Sitecore Connector option on your TDS project(s).

When you configure TDS like this, it also enables code builds to deploy to the right location for runtime file deployment.

Configuring in TdsGlobal.config

If you are using a TdsGlobal.config configuration file, you can configure the required values like this:

RequestResponsexml

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="3.5" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
    <SitecoreWebUrl>https://cm.dockerexamples.localhost</SitecoreWebUrl>
    <SitecoreDeployFolder>..\..\docker\deploy</SitecoreDeployFolder>
    <InstallSitecoreConnector>True</InstallSitecoreConnector>
    <EnableContainerDeployment>True</EnableContainerDeployment>
    <!-- Your access GUID here: -->
    <SitecoreAccessGuid>00000000-0000-0000-0000-000000000000</SitecoreAccessGuid>
  </PropertyGroup>
</Project>

Configure Unicorn

Important

Unicorn is a third-party open source tool that is not supported by Sitecore Support. These instructions are provided as guidance only, for the convenience of Unicorn users.

Unicorn runs in-process with the Sitecore platform and it directly pushes and pulls items from the file system. During development, you can use a bind mount to allow Unicorn (running within your CM container) to update serialized items within your solution source code.

The Helix.Examples repository on GitHub includes a complete example.

Mount serialized items

You typically set the base file system path used for Unicorn sync in the Sitecore configuration with an sc.variable called sourceFolder. You can populate this value from an environment variable:

RequestResponseshell

<sc.variable name="sourceFolder" value="$(env:ITEM_SYNC_LOCATION)" />

If you already copy serialized items into your CM container at build time, this must be the same environment variable that you use to configure that path. At development time, you can set that environment variable in the docker-compose.override.yml to a path you have mounted from your solution:

RequestResponseshell

  cm:
    [...]
    environment:
      ITEM_SYNC_LOCATION: c:\items-mounted
    volumes:
      - ${LOCAL_ITEM_PATH}:c:\items-mounted

You can then configure the LOCAL_ITEM_PATH variable configured in the .env file to the relative path of the Unicorn item root in your solution:

RequestResponseshell

LOCAL_ITEM_PATH=.\src

When it is configured, the Unicorn notifications within the Content Editor display the path of the item within the CM container, but changes to those items also reflect on the file system of the container host (your development environment):

Configuring transparent sync

Unicorn's transparent sync enables working with serialized items without the need to explicitly push them, for example when you switch feature branches or pull latest from source control. However, you might want to disable this functionality in other environments, such as production.

In this case, you can once again utilize environment variables to configure Unicorn:

RequestResponseshell

<unicorn role:require="Standalone or ContentManagement">
    <defaults>
        <dataProviderConfiguration set:enableTransparentSync="$(env:UNICORN_ENABLE_TRANSPARENT_SYNC)" />
    </defaults>
</unicorn>

This value can then be set in your docker-compose.override.yml and .env:

RequestResponseshell

  cm:
    [...]
    environment:
      UNICORN_ENABLE_TRANSPARENT_SYNC: ${UNICORN_ENABLE_TRANSPARENT_SYNC}

RequestResponseshell

UNICORN_ENABLE_TRANSPARENT_SYNC=true

Do you have some feedback for us?

If you have suggestions for improving this article,