Sitecore XP 10 on Docker

There are a few exciting developments in Sitecore XP 10. One of them is support for running Sitecore on Docker. Though significant work has been done by community on this before, with Sitecore official support for this, adoption would definitely increase by a large extent.

Sitecore Containers support rapid deployment and more efficient solution and team onboarding with modern Docker and Kubernetes technology. It brings the benefits of containerization technology to Sitecore projects. Key benefits in Sitecore projects:

  • Very easy setup – No more installation using SIF (Sitecore Install Framework), SIM (Sitecore Instance Manager), etc. Sitecore provides container images ready to use.
  • Run multiple versions – Run multiple Sitecore instances simultaneously without worrying about things like conflicting versions of SQL and Solr. Start and stop entire instances quickly when jumping between projects, making better use of your machine’s resources.
  • Simplified onboarding – The developer onboarding process can now be as simple as: install prerequisites, clone your code repository, run docker-compose up
  • Environment consistency – Eliminate issues due to environment inconsistencies. No more “works on my machine”. Containerize your build to have complete control of the build environment through DevOps / continuous integration (CI).
  • Environment stability -If your local Sitecore instance is corrupted, simply do docker-compose down and docker-compose up.

This is my experience of running Sitecore-xp0 in Docker:

  • Set up:
  • Install Docker Desktop for Windows. Pre-requisites for installing:
    • Hyper V enabled on laptop
    • 16 GB RAM
    • Admin privilege
  • Run Docker Desktop for Windows. You might have to start Docker service first from services.exe
  • Switch to Windows Containers. Right click docker in task tray & switch to windows containers
  • Test in Powershell. Run command docker version or docker run hello-world.

Once docker is set up, we can start with steps for Sitecore. There are just 4 steps to execute:

  1. Clone repository from github https://github.com/Sitecore/docker-examples
  2. Open a PowerShell prompt as admin and navigate to the getting-started folder in the repository. This folder has
    • .env file with required variables that will be populated by init.ps1 script.
    • init.ps1 script that executes all the pre-requisites
    • docker-compose.yml file: this has the containers configuration for Sitecore XP0 topology. As seen in screenshot it has 9 containers configuration that will be created on running step 4.
  3. Run this command .\init.ps1 -LicenseXmlPath C:\License\license.xml . This will do the following:
    • Install SitecoreDockerTools
    • Populate the environment file (.env)
    • Configure TLS/HTTPS certificates
    • Add Windows hosts file entries
  4. Start Sitecore – Run command docker-compose up –d
    • Download all required images from the Sitecore Container Registry
    • Create a default network to use
    • Create a container for each configured service, and
    • Start the containers with their configured entrypoints

Once done successfully, you will see Sitecore running successfully in Docker Dashboard.

Issues encountered by me in running these steps:

  • In step 3, you have to provide full path to license.xml file even if it is placed in “getting-started” folder. Else it will give error as:
  • In step 3, error in installing mkcert tool.
    • Cause: it was not able to access github url to download the exe
    • Resolution: downloaded manually & copied it to E:\Projects\docker-examples-develop_11Sep2020_Containers\getting-started\traefik\certs with name mkcert.exe. Then commented the line for downloading it in init.ps1 file.
    • After this step 3 completed successfully.
  • Step 4: command “docker-compose up -d” The download of images took 2-3 hours & after all downloads completed, threw this error:
    • Cause: The default Sitecore container configuration uses specific ports. To avoid any conflicts, we have to ensure that the following ports are not being used by another process: 443, 8079, 8081, 8984, and 14330.
    • Resolution: To determine which port is in use I ran following command: netstat -aon | findstr 8984
      • To know service name: tasklist | findstr ‘5480’
      • Stopped the service mentioned in above image from services.exe
      • Repeated this for other ports & closed few more services running on my laptop
  • Step 4: command “docker-compose up -d” : container is unhealthy error:
    • Cause: Unknown
    • Resolution: Taking cue for stack exchange, ran these commands:
      • Run docker-compose stop on Powershell.
      • Run docker-compose down on Powershell.
      • Now run iisreset /stop on Powershell to make sure that the required ports are free.
      • Now run docker-compose up on Powershell.
      • This time it completed successfully
  • Tried to run the site in browser https://xp0cm.localhost/, however it threw 404 error.
    • Cause: In Docker desktop, I could see CM container is not running. Clicked on the container to see the logs. Logs said “Failed to update IIS configuration”.
    • Resolution: Ran iisrest /start & ran docker-compose down & docker-compose up again. I also changed docker-compose.yml file to remove xdbAutomation & cortex workers by adding scale: 0 & removing depends on for these services to reduce memory consumption in case that is causing the issue. It worked after few retries of docker-compose down & docker-compose up
  • The URL https://xp0cm.localhost/ now showed SItecore welcome page & I was able to log into Sitecore launch pad as well https://xp0cm.localhost/sitecore.

References: https://doc.sitecore.com/developers/100/developer-tools/en/containers-in-sitecore-development.html

Installing Sitecore 9.1

Prerequisites

                  Install-SitecoreConfiguration -Path .\Prerequisites.json

  • Changed solr parameters in XP0-SingleDeveloper.ps1 accordingly.
  • xp0-singledeveloper_solrparams
  • Also changed “$SitecoreAdminPassword” in XP0-SingleDeveloper.ps1 from SIF-Default to my password and SQL server parameters.
  • Placed the license file along with configuration files.

Installing in Custom Path

  • I wanted to install in D drive. So added install paths in following config files (taking hint from https://www.brimit.com/blog/installing-sitecore-9-different-location).
    • IdentityServer.json
    • sitecore-XP0.json
    • xconnect-xp0.json
  • I used 3 different paths in the respective files: SitecoreInstallationPath, XConnectInstallationPath, IdentityServerInstallationPath and replaced “Site.PhysicalPath” accordingly in the 3 configs.
  • In XP0-SingleDeveloper.ps1, made these changes:
  • xp0-singledeveloper_paths
  • Paths need to be added in “XP0-SingleDeveloper.json” as well.
  • xp0-singledeveloper

Else you will get this error on running install script.

parameternotfounderror

Running Installation script and the issues I faced

  • Ran the install script

         .\XP0-SingleDeveloper.ps1

  • It prompted for the parameters I had created:

paramspromptThe parameters in  XP0-SingleDeveloper.ps1 should have been named as its being prompted here.

Please note the parameters values cannot include quotes here. It treated quote as part of path itself and failed with this error. “Install-sitecoreconfiguration : Cannot find drive. A drive with the name ‘”D’ does not exist.”

ddriveerror

  • After giving all 3 params, installation started and failed with this error:

solradditionalslasherror

failedtostartserviceerror

  • It was not able to start marketing automation service while installing xConnect. I tried again but this time it failed at msdeploy step itself due to existing DBs. Deleted all DBs already created and started again. The DB issue resolved by deleting existing DBs and it recreated the DBs but kept failing with “failed to start service ‘Sitecore Marketing…….” error.
  • Restarted the system and Ran these commands in powershell after restarting:

Get-Childitem cert:\LocalMachine\root -Recurse | Where-Object {$_.Issuer -ne $_.Subject} | Move-Item -Destination Cert:\LocalMachine\CA

Get-Childitem cert:\CurrentUser\root -Recurse | Where-Object {$_.Issuer -ne $_.Subject} | Move-Item -Destination Cert:\CurrentUser\CA

  • Started the Sitecore installation script. The script ran without error this time.
  • Also had tried following things. Not sure if this also helped finally resolve the issue.
    • Gave permissions to the certificate “sc910.xconnect” for user LocalService in mmc.exe
    • Imported the certificate “sc910.xconnect” in Intermediate Certification authorities for Local Machine in mmc.exe.

INSTALLATION COMPLETED !!! My site was up and running.

It was quite smooth except for “failed to start service ‘Sitecore Marketing…….” error which took some time to resolve.

It now has a “Prerequisites.json” that download and install prerequisites which is a good change from Sitecore 9.0.x. But it does not install Solr.
You need to specify SitecoreAdminPassword in the script else it will generate a random password which will be displayed on screen after installation completes and will also be present in the output file created. Everything else is more or less the same as Sitecore 9.0.x from installation perspective.

Had also received this error: “Invoke-ManageWebsiteTask : The property ‘Value’ cannot be found on this object. Verify that the property exists .” This happened as the “World Wide Web Publishing Service” was not running on my PC. It resolved once I ran the service.

Enhancing Author Experience Using EditFrame in Sitecore 9

Enabling Experience Editor for authors for all their tasks makes for great author experience in Sitecore. Though this is straightforward for simple fields like Rich Text, Date and Time, it is not straightforward for complex fields like Treelist, Multilist etc. “EditFrame” is the way to achieve this. It is very easy to configure as I discovered with a simple example described below.

Enable Editing of a treelist field from Experience Editor in Sitecore 9:

  • Created a template Product with fields as shown in the image.

ProductTemplate

  • Created StandardValues of template and inserted $name in Name field. 
  • Created a MVC layout in Sitecore at “/sitecore/layout/Layouts/Foundation/Products” and physical file at “<webroot>\Views\Products\MVC Layout.cshtml” (Creating in “<webroot>\layout” folder was giving error as namespaces were missing which are present in web.config in Views folder). No edit was required on the file.
  • Created a View Rendering “ProductRendering” in Sitecore at “/sitecore/layout/Renderings/Foundation/Products” and the Product.cshtml file at “<webroot>\Views\Products\ “.
  • Copy this code in Product.cshtml

@using Sitecore.Mvc

@using Sitecore.Mvc.Presentation

@using Sitecore.Mvc.Extensions

@model RenderingModel

@Html.Sitecore().Field(“Name”)

@Html.Sitecore().Field(“Description”)

@Html.Sitecore().Field(“Image”)

<h3>Related Products</h3>

@{

Sitecore.Data.Fields.MultilistField relProdField = Model.Item.Fields[“Related Products”];

}

@using (Html.EditFrame(Model.Item.Paths.FullPath, “ProductTests”, “Related Products”, “Edit Related Products”, null, null))

{

<ul>

@{

foreach (Sitecore.Data.Items.Item relProd in relProdField.GetItems())

{

<li>@relProd.Name</li>

}

}

</ul>

}

  • Enclose the code you want the edit toolbar to appear for in using block for Html.EditFrame as in code above.
  • Created EditFrame button in Core DB.

EditFrameButtonDefinitionInCoreDB

 

  • In StandardValues of Product Template, entered presentation details as follows:

 

  • PresentationDetails

 

  • Created a Products folder at sitecore/content/Home item and created 3 product items prod1, prod2, and prod 3. 

 

  • Opened Prod1 item in Experience Editor , when hovered over Related Products in Experience Editor now, it showed toolbar with the button. This tool bar appears only when Experience Editor is in Editing mode. It does not appear in Designing mode.
  • EditFrameInAction
  • On clicking button, this popup appeared. You can now edit RelatedProducts from Experience Editor itself.
  • EditFrameInAction1

Issues Encountered and their resolutions:

  • Error: ‘System.Web.Mvc.HtmlHelper’ has no applicable method named ‘EditFrame’ but appears to have an extension method by that name. Extension methods cannot be dynamically dispatched. Consider casting the dynamic arguments or calling the extension method without the extension method syntax.
    • Solution: Defining model on top of view is imp. I had not added @model RenderingModel on the view. It got resolved when this was added.
  • The second argument of Html.EditFrame needs to be the folder name under EditFrameButtons in Core DB and not the EditFrameButton item. It did not give any error but the edit button did not appear on the toolbar in Experience Editor.
    • Html.EditFrame(Model.Item.Paths.FullPath, “ProductTests“, “Related Products”, “Edit Related Products”, null, null)
  • Error: Inner Exception: Field editor menu item /sitecore/content/Applications/WebEdit/Edit Frame Buttons/ProductTests/EditComplexFields has empty ‘Fields’ field.
    • Solution: Entered fields name Related Products in Fields.

 

Sitecore 9 – XMSingle topology deployment on Azure PaaS with ARM templates

Prerequisites:

Deployment:

Followed the steps given here for deploying: https://doc.sitecore.net/sitecore_experience_platform/setting_up_and_maintaining/sitecore_on_azure/deploying/walkthrough_deploy_a_new_sitecore_environment_to_the_microsoft_azure_app_service

  • Copy the raw URL of azuredeploy.json for XMSingle for Sitecore 9 from github.

https://raw.githubusercontent.com/Sitecore/Sitecore-Azure-Quickstart-Templates/master/Sitecore%209.0.0/XMSingle/azuredeploy.json

This was obtained from git after clicking on “raw” when the file is selected.

git raw

Its very important to get the “Raw” URL else you will keep getting template validation failed error on running PowerShell (PS) command.

  • Run PS as administrator.
  • Import Sitecore cloud cmdlets from Azure toolkit. This is required to run the cmd “Start-SitecoreAzureDeployment” that does the actual deployment. You will get “Start-SitecoreAzureDeployment” not recognized as a cmd error if this is not imported. Ran this cmd in Powershell to import:

Import-Module “D:\Sitecore Software\Sitecore9\Sitecore Azure Toolkit 2.0.0 rev.171010\tools\Sitecore.Cloud.Cmdlets.psm1”

  • Login to your Azure subscription. Ran cmd Add-AzureRMAccount. Failed with this error

AdAzureRM

This error will come if Azure Powershell is not installed and imported.

PS c:\> Get-Module PowerShellGet -list | Select-Object Name,Version,Path

GetModule

  • install the Azure PowerShell from the PowerShell Gallery by running following command:

PS C:\> Install-Module AzureRM

Command took 5-6 min to complete.

  • Then import the AzureRM module:

Import-Module AzureRMimportAzureRM

Azure Powershell is installed and imported.

  • Ran cmd Add-AzureRMAccount again.

Enter subscription details in the popup window.

  • Copy subscriptionId shown in PS and Run cmd

Set-AzureRMContext -SubscriptionId 62c6c7c3-cbda-4838-a3df-bfbf07ad72c4

AdAzureRM1

  • Now we need to prepare parameters required by cmd “Start-SitecoreAzureDeployment”
  • Edit the file “azuredeploy.parameters.json” downloaded from ARM templates from git for XMSingle topology of Sitecore 9.

https://github.com/Sitecore/Sitecore-Azure-Quickstart-Templates/blob/master/Sitecore%209.0.0/XMSingle/azuredeploy.parameters.json

I edited it to look like this

{

“$schema”: “https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#“,

“contentVersion”: “1.0.0.0”,

“parameters”: {

“deploymentId”: {

“value”: “ECMEntSolGrp”

},

“location”: {

“value”: “East US”

},

“sqlServerLogin”: {

“value”: “saCharu”

},

“sqlServerPassword”: {

“value”: “Password1!”

},

“singleMsDeployPackageUrl”: {

“value”: “https://ecmdatastore.blob.core.windows.net/sitecore/Sitecore%209.0.0%20rev.%20171002%20(Cloud)_single.scwdp.zip

},

“sitecoreAdminPassword”: {

“value”: “Password1!”

},

“licenseXml”: {

“value”: “”

}

}

}

  • For  “singleMsDeployPackageUrl”, I uploaded the Sitecore package “Sitecore 9.0.0 rev. 171002 (Cloud)_single.scwdp.zip” ( Packages for XM Single downloaded  from “Download options for Azure AppService” for Sitecore 9 here https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/90/Sitecore_Experience_Platform_90_Initial_Release.aspx.) to Azure storage. Upload steps:
    • Login to portal.azure.com
    • Go to Storage Accounts.
    • Click on an existing account or create one.
    • Click on Blobs in the selected storage account.
    • Blob
    • Create a container or use an existing one.
    • Select the container and click Upload to upload the package.
    • Upload
    • Select the uploaded package
    • Uploaded
    • Copy the URL shown in Blob properties on the right side.
    • CopyBlobURL
  • Try the copied URL in browser. If it says Requested resource does not exist, you need to set the access policy of the container to allow anonymous read.
  • BlobAccess
  • alternative solution for live project is required based on Shared Access Signatures.
  • Start the deployment. Run cmds
    • $Parameters = @{ “deploymentId”=”ECMEntSolGrp”}

It succeeded. Took around 30 min to complete.

success

  • Logged in to portal.azure.com. Navigated to “App Services”. I can see a new WebApp “ecmentsolgrp-single” there.
  • AppService

Click this and click the URL of the site displayed on right.

SiteURL

The Sitecore site came up.

 Site  SiteLaunchPad

Few errors I had got before it finally worked:

  • “Start-SitecoreAzureDeployment is not recognized as a command”.  Had started the new PS session in between. So have to import module from Sitecore azure tool kit again.
  • Start-SitecoreAzureDeployment
  • error “Positional parameter could not be found.” There was a space between “-” and “SetKeyValue” in the command. Removed the space to resolve it.
  • Positional parameter
  • Error “Forbidden”. The -Name parameter of the command and “deploymentId” mentioned in $parameters and in azuredeploy.json should be the name of Resource Group (new or existing). I first used “XMSingle” for this but was getting “Forbidden” error. This was due to the fact that I did not have privilege to create a new Resource group (RG) in my Azure Subscription. So had to change it to existing RG name “ECMEntsolGrp”.
  • ResourceGroupName
  • “Errorcode Invalid template….Unexpected character encountered while parsing”. This was due to incorrect ArmTemplateUrl parameter. The URL needs to be the Raw URL of file azuredeploy.json from github as mentioned in concerned step above.
  • ArmTemplateUrl

Incorrect:  https://github.com/Sitecore/Sitecore-Azure-Quickstart-Templates/blob/master/Sitecore%209.0.0/XMSingle/azuredeploy.json

Correct: https://raw.githubusercontent.com/Sitecore/Sitecore-Azure-Quickstart-Templates/master/Sitecore%209.0.0/XMSingle/azuredeploy.json

  • “Lacation ‘East US 2’ is not available for Resource Type ‘Microsoft.Search/SearchServices'”. I had first specified location parameter as “East US 2” which is not available for Azure Search. Changed it to “East US” to resolve this error.
  • SearchServices
  •  “‘sa’ is not a valid login name in this version of SQL Server.” I had specified “sa” as value of “sqlServerLogin” in azuredeploy.parameters.json file. Changed it to “saCharu” to resolve.
  • Failed to download package.\r\nAppGallery Deploy Failed: ‘System.Net.WebException: The remote server returned an error: (404) Not Found.

As mentioned here  “singleMsDeployPackageUrl” the Sitecore package was not accessible due to Access Policy on the container in Azure Storage. Changed Access Policy on the container to allow anonymous read.

  • A self-signed certificate will be required for other topologies. I had created it for this as well as authCertificateBlob is mentioned in params here for XMSingle as well

https://doc.sitecore.net/sitecore_experience_platform/setting_up_and_maintaining/sitecore_on_azure/deploying/walkthrough_deploy_a_new_sitecore_environment_to_the_microsoft_azure_app_service but it was giving me error that “authCertificateBlob” is not present in original template and can not be supplied at deployment. So removed it. However, mentioning the steps here:

  • Created a self signed certificate: Open IIS, Click Server Certificates in IIS section, Click Create self signed certificate in right pane, Enter name and click Ok. Certificate will be visible in IIS. Right click created certificate and click Export. Specify file name and a password and click ok. “XMSingleCert.pfx” file got generated.
  • Entered this in azuredeploy.parameters.json in the end

“allowInvalidClientCertificates”: {

“value”: true

}

Remember to put ‘,’ after the end brace of last parameter else you will get the error while deploying.

The file looked like this at the end:


allowInvalidClientCertificates

  • To deploy, add this in $parameters

$Parameters = @{

“deploymentId”=”XMSingle”;

“authCertificateBlob” = [System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes(“D:\Sitecore Software\Sitecore9\AzureDeplXMSingle\XMSingleCert.pfx”))