Skip to main content

Run your first Sitecore instance

Abstract

This topic shows how you get a Sitecore image without customizations up and running.

This topic shows how you quickly get an out-of-the-box Sitecore Experience Platform - Single (XP0) instance up and running with minimal configuration.

Note

Although this topic uses the Sitecore Experience Platform - Single (XP0) configuration for simplicity, you can use the same approach to start any configuration.

Docker Compose files for each Sitecore topology are included in the Sitecore Container Deployment Package that you can download from the Sitecore download page.

This topic assumes that your local environment is set up for developing with Docker on Windows. See Environment setup for details. Make sure you have switched to Windows containers.

You must also have a valid Sitecore license file.

Important

The default Sitecore container configuration uses specific ports. To avoid any conflicts, ensure that the following ports are not being used by another process: 443, 8079, 8081, 8984, and 14330.

Troubleshooting Docker advice is available as well.

Clone the Docker Examples repository

Start by cloning the Docker Examples repository to a location on your machine, for example, C:\sitecore\docker-examples\ (the following steps assume you use this folder). In this topic, you use the getting-started folder within the repository.

Open a PowerShell prompt and navigate to the getting-started folder. It contains these files:

  • docker-compose.yml and .env : Types of Docker Compose files. These are the main files necessary for launching a vanilla Sitecore instance. Included in the Sitecore Container Deployment Package.

  • mssql-data, solr-data, and traefik - Supporting folders utilized by the Docker containers within your Sitecore instance. Included in the Sitecore Container Deployment Package.

  • init.ps1 and clean.ps1 - Example helper scripts. Not part of the Sitecore Container Deployment Package.

Each of these is explained in more detail in the following sections.

The Docker Compose files

  • docker-compose.yml

    This Compose file is the main configuration file used by the docker-compose command. It contains information about the different containers (referred to as services) and their configuration.

    For Sitecore, the services generally represent the individual Sitecore roles that make up the topology (mssql, solr, id, cm, and so on).

  • .env

    This is an environment file. The values here provide default values for any environment variables referenced in the Compose file (for example SITECORE_DOCKER_REGISTRY), or you use it to configure Compose (for example COMPOSE_PROJECT_NAME).

Environment variables are the recommended way to pass configuration settings into containers. You can see how these are used in Sitecore containers in the docker-compose.yml file. The mssql service, for example, sets an environment variable to configure the SQL Server SA password (SA_PASSWORD):

mssql:
  isolation: ${ISOLATION}
  image: ${SITECORE_DOCKER_REGISTRY}sitecore-xp0-mssql:${SITECORE_VERSION}
  environment:
    SA_PASSWORD: ${SQL_SA_PASSWORD}
    SITECORE_ADMIN_PASSWORD: ${SITECORE_ADMIN_PASSWORD}
    ACCEPT_EULA: "Y"
    SQL_SERVER: mssql
  ports:
    - "14330:1433"

The value is sourced from the .env file using variable substitution (${SQL_SA_PASSWORD}).

Preparation

The repository includes a script that performs all preparation steps automatically: the init.ps1 script.

To run this script:

  1. Open a PowerShell administrator prompt.

  2. Run the following command, replacing the -LicenseXmlPath with the location of your Sitecore license file:

    .\init.ps1 -LicenseXmlPath C:\License\license.xml

If you do not use the script, follow the steps in the following sections.

Install SitecoreDockerTools

The SitecoreDockerTools PowerShell module has various helper cmdlets you use in Docker-based Sitecore development. These commands greatly simplify the preparation steps (although they are not essential).

Run the following commands from PowerShell to install, or follow the instructions on the SitecoreDockerTools MyGet page:

Register-PSRepository -Name "SitecoreGallery" -SourceLocation "https://sitecore.myget.org/F/sc-powershell/api/v2"
Install-Module SitecoreDockerTools

Populate the environment file

The .env file has the following unassigned values:

COMPOSE_PROJECT_NAME=sitecore-xp0
SITECORE_DOCKER_REGISTRY=scr.sitecore.com/sxp/
SITECORE_VERSION=10.1.0-ltsc2019
SITECORE_ADMIN_PASSWORD=
SQL_SA_PASSWORD=
TELERIK_ENCRYPTION_KEY=
SITECORE_IDSECRET=
SITECORE_ID_CERTIFICATE=
SITECORE_ID_CERTIFICATE_PASSWORD=
SITECORE_LICENSE=
CM_HOST=xp0cm.localhost
ID_HOST=xp0id.localhost
TRAEFIK_IMAGE=traefik:v2.2.0-windowsservercore-1809
TRAEFIK_ISOLATION=hyperv
ISOLATION=default
SOLR_CORE_PREFIX_NAME=sitecore
# You should change the shared secret to a random string and not use the default value
MEDIA_REQUEST_PROTECTION_SHARED_SECRET=HQ(NjM(u6_5koVla-cTf4ta8x1h6Sb+ZcUQrULUz-0Afpx0cx-NuMtIoQkpDFmX5

The Installation Guide for a Developer Workstation with Containers describes each of these variables, and what values you can specify.

You do not have to update any of the variables that have a value specified at this time, but you must specify values for the variables that are empty.

  1. Set the SITECORE_ADMIN_PASSWORD and SQL_SA_PASSWORD to passwords of your choice.

    Note

    The SQL SA password must meet SQL Server complexity requirements.

    You can also use the SitecoreDockerTools module to set and generate these passwords in the PowerShell: the init.ps1 script sets both to Password12345.

  2. To set the Telerik encryption key, run the following PowerShell script as an administrator in the folder where your environment file is:

    Import-Module SitecoreDockerTools
Set-DockerComposeEnvFileVariable "TELERIK_ENCRYPTION_KEY" -Value (Get-SitecoreRandomString 128)

    This imports the SitecoreDockerTools module into the session, and then sets the TELERIK_ENCRYPTION_KEY variable using these two cmdlets:

    • Set-DockerComposeEnvFileVariable : Sets a variable value in a Docker Compose .env file.

    • Get-SitecoreRandomString: Returns a random string to be used as a password or key.

  3. To set Identity Server variables, run the following PowerShell script:

    Import-Module SitecoreDockerTools
Set-DockerComposeEnvFileVariable "SITECORE_IDSECRET" -Value (Get-SitecoreRandomString 64 -DisallowSpecial)
$idCertPassword = Get-SitecoreRandomString 12 -DisallowSpecial
Set-DockerComposeEnvFileVariable "SITECORE_ID_CERTIFICATE" -Value (Get-SitecoreCertificateAsBase64String -DnsName "localhost" -Password (ConvertTo-SecureString -String $idCertPassword -Force -AsPlainText))
Set-DockerComposeEnvFileVariable "SITECORE_ID_CERTIFICATE_PASSWORD" -Value $idCertPassword

    This sets the SITECORE_IDSECRET, SITECORE_ID_CERTIFICATE, and SITECORE_ID_CERTIFICATE_PASSWORD variables, using the a cmdlet from the SitecoreDockerTools:

    • Get-SitecoreCertificateAsBase64String: Generates a new self-signed certificate and returns the certificate in its password-protected, Base64 encoded form.

  4. To set the Sitecore license variable, run the following PowerShell script, replacing the -Path with the location of your Sitecore license file:

    Import-Module SitecoreDockerTools
Set-DockerComposeEnvFileVariable "SITECORE_LICENSE" -Value (ConvertTo-CompressedBase64String -Path "C:\License\license.xml")

    The Sitecore license file is very large and you must compress and Base64-encode it to fit within the maximum size allowed by Windows for all the environment variables. The ConvertTo-CompressedBase64String cmdlet in SitecoreDockerTools does this.

    Note

    You can reuse variables across multiple Sitecore instances by setting environment variables in Windows instead of the Docker Compose environment file.

    Note

    Alternatively, you can mount a folder with your license.xml file into each service, and set the SITECORE_LICENSE_LOCATION variable. For xConnect services, this must be the folder containing the license file. For all other services, it must be the path to the file itself.

Configure TLS/HTTPS certificates

Sitecore uses Traefik as the default reverse proxy or edge router for Docker Compose. The getting-started\traefik folder contains the following:

  • certs

    An empty folder where you put the certificates you generate.

  • config/dynamic/certs_config.yaml

    A Traefik configuration file used by the Traefik container.

This entire traefik folder is made available for the Traefik container with a Docker volume in the docker-compose.yml file:

traefik:
  [...]
  volumes:
    - source: \\.\pipe\docker_engine
      target: \\.\pipe\docker_engine
      type: npipe
    - ./traefik:C:/etc/traefik
  [...]

The traefik service maps the relative ./traefik folder to the running container at C:/etc/traefik.

This path is then used by the Traefik service configuration, where the --providers.file.directory is specified as C:/etc/traefik/config/dynamic (where the certs_config.yaml file is). See the Traefik documentation for more details.

The certs_config.yaml file also uses the volume to reference certificates in the certs folder:

tls:
  certificates:
    - certFile: C:\etc\traefik\certs\xp0cm.localhost.crt
      keyFile: C:\etc\traefik\certs\xp0cm.localhost.key
    - certFile: C:\etc\traefik\certs\xp0id.localhost.crt
      keyFile: C:\etc\traefik\certs\xp0id.localhost.key

Install mkcert

You use the mkcert utility generate the required certificates.

To install mkcert:

  1. Download the latest Windows executable.

  2. Rename the file to mkcert.exe.

  3. Move the file to a directory that is in one of your PATH environment variables, such as C:\Windows\system32.

  4. Open a command prompt in administrator mode and run mkcert -install

If you use Chocolatey you can install mkcert with the following commands instead:

choco install mkcert
mkcert -install

Generate certificates

Run the following commands in the getting-started folder to generate the required certificates:

mkcert -cert-file traefik\certs\xp0cm.localhost.crt -key-file traefik\certs\xp0cm.localhost.key "xp0cm.localhost"
mkcert -cert-file traefik\certs\xp0id.localhost.crt -key-file traefik\certs\xp0id.localhost.key "xp0id.localhost"

Add Windows hosts file entries

You can add the xp0cm.localhost and xp0id.localhost host names to your Windows hosts file, and point them to the loopback IP address 127.0.0.1:

127.0.0.1   xp0cm.localhost
127.0.0.1   xp0id.localhost

Alternatively, you can use the Add-HostsEntry cmdlet from SitecoreDockerTools:

Add-HostsEntry "xp0cm.localhost"
Add-HostsEntry "xp0id.localhost"

Start Sitecore

To start Sitecore:

  • Run the following command in the same folder as your Compose file:

    docker-compose up -d

This command does the following:

  • Downloads all required images from the Sitecore Container Registry.

  • Creates a default network to use.

  • Creates a container for each configured service.

  • Starts the containers with their configured entrypoints.

Note

The -d (detached mode) tells Docker to start the containers in the background and leave them running. If you omit this, the container logs are streamed to the output instead, and you must type Ctrl+C to return to a prompt. Doing this also stops and removes your containers.

For a quick reference of this and other common commands used in this guide, see the Sitecore Docker cheat sheet.

View the running containers

To see the containers that you created:

  • Run the docker ps command:

    docker ps

This displays a list of all running containers as indicated by a status of Up. You can also see the container ID, image being used, and ports the container is exposed on:

CONTAINER ID  IMAGE                                                                          COMMAND                   CREATED             STATUS                            PORTS                                                 NAMES
75684e9146f2  traefik:v2.2.0-windowsservercore-1809                                          "/traefik --ping --a…"    7 seconds ago       Up 3 seconds (healthy: starting)  80/tcp, 0.0.0.0:443->443/tcp, 0.0.0.0:8079->8080/tcp  sitecore-xp0_traefik_1
67be2b1350e1  scr.sitecore.com/sxp/sitecore-xp0-cm:10.1.0-ltsc2019                      "C:\\LogMonitor\\LogMo…"  21 seconds ago      Up 11 seconds (healthy)           80/tcp                                                sitecore-xp0_cm_1
e553b6ab0fb5  scr.sitecore.com/sxp/sitecore-xp0-cortexprocessingworker:10.1.0-ltsc2019  "C:\\LogMonitor\\LogMo…"  21 seconds ago      Up 11 seconds (healthy)                                                                 sitecore-xp0_cortexprocessingworker_1
8d40d14da8a2  scr.sitecore.com/sxp/sitecore-xp0-xdbautomationworker:10.1.0-ltsc2019     "C:\\LogMonitor\\LogMo…"  21 seconds ago      Up 12 seconds (healthy)                                                                 sitecore-xp0_xdbautomationworker_1
b4279d4f6de7  scr.sitecore.com/sxp/sitecore-id:10.1.0-ltsc2019                          "C:\\LogMonitor\\LogMo…"  27 seconds ago      Up 21 seconds (healthy)           80/tcp                                                sitecore-xp0_id_1
41418243fd0d  scr.sitecore.com/sxp/sitecore-xp0-xdbsearchworker:10.1.0-ltsc2019         "C:\\LogMonitor\\LogMo…"  27 seconds ago      Up 20 seconds (healthy)                                                                 sitecore-xp0_xdbsearchworker_1
6f4e64033031  scr.sitecore.com/sxp/sitecore-xp0-xconnect:10.1.0-ltsc2019                "C:\\LogMonitor\\LogMo…"  27 seconds ago      Up 21 seconds (healthy)           0.0.0.0:8081->80/tcp                                  sitecore-xp0_xconnect_1
33931b923acb  scr.sitecore.com/sxp/sitecore-xp0-mssql:10.1.0-ltsc2019                   "powershell -Command…"    About a minute ago  Up 56 seconds (healthy)           0.0.0.0:14330->1433/tcp                               sitecore-xp0_mssql_1
3b362d8ed9a6  scr.sitecore.com/sxp/sitecore-xp0-solr:10.1.0-ltsc2019                    "powershell -Command…"    About a minute ago  Up 56 seconds                     0.0.0.0:8984->8983/tcp                                sitecore-xp0_solr_1

You might notice some of the statuses have (health: starting), which means they are still warming up to meet the configured health check (see healthcheck in the docker-compose.yml file). If you run the docker ps command again, you can eventually see these all change to (healthy).

Access Sitecore containers

You access the containers serviced by the reverse proxy with the HTTPS protocol, using their configured hostnames (for ex https://xp0cm.localhost).

The rest of the exposed containers are preconfigured to use specific ports (see ports in the docker-compose.yml file). In the default configuration of Docker Desktop for Windows, you access these ports on localhost.

This means you can access your Sitecore Experience Platform - Single (XP0) containers like this:

About connecting to SQL Server

When you connect to SQL Server using a port, the syntax is slightly different. You must use a comma (,) instead of a colon (:), as indicated previously. You can connect with SQL Server Authentication using the sa account and the value you specified for SQL_SA_PASSWORD in the .env file (Password12345 by default in the init.ps1 file):

The Connect to Server dialog.

Populate schema and update indexes

The Sitecore container environment includes a solr-init container that runs on startup, creates the needed cores in your Solr container (if they do not exist already), and then exits. This is the expected behavior.

However, this container does not populate the Solr managed schemas or rebuild indexes. You need to do this manually or with custom scripting. You can see Solr-related errors in your container logs if you do not do this.

To populate the managed schema and update indexes:

  1. Log in to Sitecore as admin.

  2. Open the Control Panel and populate the managed schema for all search indexes.

  3. While still in the Control Panel, rebuild search indexes.

Verify your instance

To verify your instance:

  1. Browse to https://xp0cm.localhost to see the Sitecore default website.

  2. Browse to https://xp0cm.localhost/sitecore and verify you can log in to Sitecore. Use admin for the User Name and the value you specified for SITECORE_ADMIN_PASSWORD in the .env file (Password12345 by default in the init.ps1 file) for the Password.

  3. Look at the logs with the following command to see the logs from all containers:

    docker-compose logs -f --tail 20

    The -f (or --follow) option tells Docker to stream the output, and the --tail option limits the initial log output to the last 20 lines of each container. You can see that the logs are prefixed by the container.

  4. Type Ctrl+C when you are done to return back to a prompt.

Stop Sitecore

To stop the Sitecore instance:

  • Run the following command:

    docker-compose stop

    This stops your containers, but does not remove them. They can then be started again with docker-compose start.

  • To stop and remove the containers:

    docker-compose down

    This stops your containers, but also removes the containers as well as any networks that were created.

  • To stop and remove containers, and also remove images:

    Add --rmi <all/local>.

Your development workflow will involve a combination of these commands. The commands are relatively fast, depending on the topology.

Persistent storage cleanup

There are now files in the mssql-data and solr-data folders. Like the traefik folder, these are folders mounted as volumes in the Compose file. They are configured in the docker-compose.yml file:

mssql:
  [...]
  volumes:
    - type: bind
      source: .\mssql-data
      target: c:\data
solr:
  [...]
  volumes:
    - type: bind
      source: .\solr-data
      target: c:\data

The folders are used as persistent storage for the database files for the mssql service and the index files for the solr service. This means that your database and index data remain even after a docker-compose down command.

However, there are situations where you want to start fresh or you need to clear these due to stale data, for example, if you change the Sitecore administrator password.

You can manually delete the files in these folders, or you can use the clean.ps1 script.

To delete the files:

  1. Open a PowerShell administrator prompt in the getting-started folder.

  2. Run the following command:

    .\clean.ps1

Further reading