select *
	from items i
	left join (SELECT ParentID, COUNT(*) AS ChildCount
		FROM items
		WHERE ParentID IS NOT NULL
		GROUP BY ParentID
		HAVING COUNT(*) > 100) p on p.ParentID = i.ID
		where p.ParentID is not null
	order by p.ChildCount desc

ALTER TABLE VisitGeoIpData WITH NOCHECK ADD CONSTRAINT chk_read_only CHECK( 1 = 0 )

Update your Powershell profile by opening this file:

notepad $PROFILE

Add the following script:

function prompt {
    $currentPath = Get-Location
    $gitBranch = ''

    if (Get-Command git -ErrorAction SilentlyContinue) {
        try {
            $branch = git rev-parse --abbrev-ref HEAD 2>$null
            if ($branch -and $branch -ne 'HEAD') {
                $gitBranch = " [$branch]"
            }
        } catch {
            # Not in a Git repo, do nothing
        }
    }

    return "$currentPath$gitBranch> "
}

Windows, on the other hand, does not come with this functionality. Here’s a simple powershell script that works very similar to the tail command and has highlighting enabled for typical log4j logs. It loads the latest log file the given prefix. In this case it will load the latest log file starting with the Sitecore prefix.

The script is called like this: .\tail.ps1 .\App_Data\logs\Sitecore

param (
    [Parameter(Mandatory = $true)]
    [string]$Stem
)

function Get-LatestLogFile {
    $directory = Split-Path $Stem
    $filename = Split-Path $Stem -Leaf
    $pattern = "$filename*.log"

    $files = Get-ChildItem -Path $directory -Filter $pattern -File | Sort-Object LastWriteTime -Descending
    if ($files.Count -eq 0) {
        Write-Host "No log files found with stem '$Stem'" -ForegroundColor Red
        exit 1
    }
    return $files[0].FullName
}

function Write-ColoredEntry {
    param ([string[]]$entry)

    $text = $entry -join "`n"

    switch -Regex ($text) {
        '\bFATAL\b' { Write-Host $text -ForegroundColor Magenta; break }
        '\bERROR\b' { Write-Host $text -ForegroundColor Red; break }
        '\bWARN\b'  { Write-Host $text -ForegroundColor Yellow; break }
        '\bDEBUG\b' { Write-Host $text -ForegroundColor Cyan; break }
        default     { Write-Host $text }
    }
}

function Tail-Follow {
    param (
        [string]$FilePath,
        [int]$Lines = 10,
        [int]$Interval = 1
    )

    $encoding = [System.Text.Encoding]::UTF8
    $fs = [System.IO.File]::Open($FilePath, 'Open', 'Read', 'ReadWrite')
    $reader = New-Object System.IO.StreamReader($fs, $encoding)

    # Read last N lines
    $content = Get-Content -Path $FilePath -Tail $Lines
    $buffer = @()
    foreach ($line in $content) {
        if ($line -match '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}') {
            if ($buffer.Count -gt 0) {
                Write-ColoredEntry -entry $buffer
                $buffer = @()
            }
        }
        $buffer += $line
    }
    if ($buffer.Count -gt 0) {
        Write-ColoredEntry -entry $buffer
    }

    # Move to end of file
    $reader.BaseStream.Seek(0, [System.IO.SeekOrigin]::End) | Out-Null

    $entryBuffer = @()
    while ($true) {
        $line = $reader.ReadLine()
        if ($line -ne $null) {
            if ($line -match '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}') {
                if ($entryBuffer.Count -gt 0) {
                    Write-ColoredEntry -entry $entryBuffer
                    $entryBuffer = @()
                }
            }
            $entryBuffer += $line
        } else {
            if ($entryBuffer.Count -gt 0) {
                Write-ColoredEntry -entry $entryBuffer
                $entryBuffer = @()
            }
            Start-Sleep -Seconds $Interval
        }
    }
}

# Main
$logFile = Get-LatestLogFile
Write-Host "Following log file: $logFile" -ForegroundColor Cyan
Tail-Follow -FilePath $logFile

An error is happening in production. The marketing team has just launched a major email campaign and the new landing page is displaying an error instead of the new call to action component. Everything looked great in the development, integration, and pre-production environments. Even the production environment passed through QA and was signed off on before the marketing campaign went live. What happened?

At this point engineers are going through the production logs to try and identify what's happening and determine a root cause. A stand-alone Sitecore XM environment has, at a minimum, 1x Content Management instance, 2x Content Delivery instances, a SQL cluster, Redis for caching, identity servers for processing logins, SOLR instances for search, etc. Add in a lot more if you're running an XP version of Sitecore. That's a lot of server logs to review for an incident in progress.

Having a log aggregation service like Splunk can help, but you're often still searching for the needle in a haystack. Often that haystack can contain thousands of log entries per second. And try not to think about what Splunk costs to keep all of those logs for any meaningful length of time.

The other challenge is that any issue occurring anywhere in the enterprise that serves content to Sitecore could actually be the culprit behind the production issue. Frequently, it's a microservice issue with another team that is propagating to the website. This is usually something like a user profile service or an order history service experiencing problems. It doesn't even have to be a complete outage of those services—increased latency in requests to them could trigger cascading issues. The fix could be as simple as notifying the relevant team about the urgency of scaling their service (microservices can be multiple tiers deep, and the team may not know where their data is being used or how critical it is to your customer-facing application).

So how do we identify the root cause of a production issue quickly?

Warnings, Errors, and Log Levels

Server logs grow over time (obviously). The rate at which servers create logs also tends to increase over time. Pretty much every service has many different log levels. A log level is essentially how much data is logged for every action that service takes. The most common log levels are Error, Warn, Info, Debug, and Trace. Each level adds significantly more log data than the previous level.

The Error level logs only actual errors that have occurred directly in this service itself. On the other hand, the Trace level logs literally everything that happens on every request. Usually, services start out at either the Warn or the Info log level. It's not unusual for this log level to move toward the Debug or even Trace log levels as challenging issues that are hard to debug occur over time. This typically happens to different services at different times.

These log level changes are similar to technical debt in that everyone knows that a server shouldn't be left at the Debug or Trace log level. It's often out of sight and out of mind though. It can even be helpful for a time as it can help identify issues faster. Over time though, the data keeps growing, and it becomes much more challenging to find the signal in the noise of all the log data.

The Solution

The solution is to implement Distributed Tracing. Distributed tracing is a technique used to monitor and analyze requests as they travel across a distributed system (such as a microservices architecture). It helps in tracking the flow of requests between different services, identifying performance bottlenecks, diagnosing errors, and understanding system behavior. It is the key that ties the logs between all of the different services together.

Each request into the system gets assigned a unique trace ID. As each request moves within a service, span IDs can be added to identify individual operations within that service. As one microservice calls another, it includes the trace ID in the request header. This allows troubleshooters to quickly see that the Warn log on the Content Delivery server is directly tied to a timeout Error log in the User Profile microservice.

This approach does require buy-in throughout the organization, as each application and service needs to be updated to support distributed tracing. The effort level is typically fairly low though, as the libraries that implement distributed tracing quite typically work at a low level and often require minimal configuration out of the box.

Common Distributed Tracing Libraries and Tools

Here are some popular distributed tracing libraries and frameworks that you can implement in your system:

1. OpenTelemetry - An observability framework that merged OpenTracing and OpenCensus; provides language-specific SDKs for various programming environments

2. Jaeger - An open-source, end-to-end distributed tracing system that's compatible with OpenTelemetry and the OpenTracing standard

3. Zipkin - One of the earliest open-source distributed tracing systems, inspired by Google's Dapper paper

4. AWS X-Ray - AWS's distributed tracing service that helps analyze and debug distributed applications

5. Azure Application Insights - Microsoft's APM service that includes distributed tracing capabilities

6. Datadog APM - A commercial APM solution with strong distributed tracing features

7. New Relic Distributed Tracing - Part of New Relic's observability platform

8. Elastic APM - Distributed tracing integrated with the Elastic Stack

9. Dynatrace PurePath - Dynatrace's distributed tracing technology

10. Honeycomb - A commercial observability tool with powerful distributed tracing capabilities

Most of these tools follow the W3C Trace Context standard, which defines a standard format for propagating distributed trace context between services. This makes them relatively interoperable and easier to adopt.

Traditional Sitecore MVC applications start at a much lower level than newer frameworks like Sitecore SXA or XM Cloud that have been built on top of Sitecore MVC. There is no base application to start from and the Sitecore Information Architecture (IA) is for all intents and purposes empty. While this gives the development team incredible freedom to build out the implementation as they wish, it also leaves the team wide open to issues that can be challenging to fix toward the end of an implementation. These development choices can often impact the user experience for content authors as well as limit the out of the box functionality that Sitecore provides.

This article will review common issues that I’ve seen in more than 10 years of building and maintaining Sitecore applications. This isn’t to say that any implementation that has some of these issues is a bad implementation. It’s more of a list of red flags to look for to get a better feel for where the implementation is today.

What a great MVC implementation looks like

A great implementation can be a joy to work on. It’s intuitive, follows consistent patterns, and it’s easy to add features or resolve issues. I’ve found that there are 5 key areas of an implementation that can make or break the development experience: workstation setup, dependency management, the information architecture, the solution architecture, and hotfixes.

Workstation Setup

A new developer on a project should be able to spin up a development environment very quickly. A developer on a great implementation can be up and running within 15 to 20 minutes of getting started. A developer working on a less than optimal solution can take multiple days to get up and running.

Easy Startup

The best implementations have the bootstrap and startup processes scripted. A new developer shouldn’t have to know every detail of the implementation just to get up and running. Older implementations often have a bootstrap script that verifies system dependencies, installs Sitecore, and synchronizes serialized templates and content into the databases. This lets them hit the ground running with an up to date environment very quickly.

More recent versions of Sitecore are built around Docker containers. Docker containers can be thought of like virtual machines that are built via scripts that the development team create. This allows for an even better development experience as whenever the underlying containers are updated, each development machine gets the updates as well. As all of the dependencies for Sitecore are in the containers, it’s as easy as running start.ps1 script to be up and running with the latest version.

If on the other hand developers are asking about database backups, Sitecore installation errors, login credentials, or serialization errors you may have some startup issues to resolve.

Documentation

Great implementations have a Readme.md file in the codebase. This documentation isn’t to go into great depth about the implementation. Rather it’s documentation on getting environments up and running as well as high level information about the solution in general. It’s also a great place for documenting runtime options and environment variable options.

Content Data Updates

Templates in Sitecore are expected to be in source control. The content items defined by the templates are typically not stored in source control as it can be a very large amount of files. Typically there is sample content stored in source control that provides enough content to launch and demo the functionality of the site.

What happens though when a bug is reported in production that isn’t reproducible with development content? Content needs to be synchronized from a higher level environment down to a developer’s workstation. In modern environments this would be handled via the Sitecore command line interface (CLI). It can be helpful to keep the CLI environment and configurations stored in a separate repository to keep the primary repository clean.

This approach replaces the outdated technique of using Sitecore packages to pass templates and/or content items between environments. Creating packages typically takes longer and is more error prone than using the CLI.

Dependency Management

Dependency management is critically important for any software solution but there are some unique considerations for Sitecore implementations. This includes library references, Sitecore references, third party dependencies, and Sitecore content packages (historically provided by Sitecore).

Versioning

Sitecore as a product is unlike many other enterprise applications in that any code modifications are deployed on top of the existing deployment. This leads to the overwriting of the out of the box DLL and/or configuration files with ones from the developer’s solution/deployment artifacts. It’s important DLL versions remain consistent with the Sitecore versions.

This can be problematic when installing nuget packages that have different requirements than the deployed Sitecore versions. It’s typically common libraries like NewtownSoft.Json that are impacted. Care should be taken to confirm that changing the version doesn’t introduce breaking changes within Sitecore. I would also typically expect to see a Packages.props file that defines the specific versions of libraries used throughout the solution.

While it’s not uncommon to see some version changes in an implementation, it would be a red flag to see many DLLs with inconsistent versions. You can find the assembly version in the release notes for a particular Sitecore release.

Sitecore Dependencies

Older implementations would typically have a source controlled version of the Sitecore reference DLLs like Sitecore.Kernel.dll. Modern implementations will use package references that refer directly to Sitecore’s nuget repository. Keeping DLL dependencies within source control can be problematic as it both increases the size of the repository as well as complicates paths to those libraries.

Third Party or Private Dependencies

Third party libraries that don’t have public nuget feeds should be stored in a enterprise hosted nuget repository. This includes any hotfix DLLs provided by Sitecore. Azure DevOps provides nuget repository hosting called Azure Artifacts that can be used for this purpose.

This allows for the third party DLLs to be deployed as part of the solution when included as a package reference.

Information Architecture

Sitecore’s Information Architecture (IA) is extremely limited out of the box. While this on one hand allows for an extremely flexible IA, it often results in unforeseen complications down the road. Often times these complications relate to adding additional sites. Does the IA support regional sites? Or what about separate sites per language? How is content shared between sites? All of these are directly impacted by the IA and it can be challenging to change when the issues actually arise.

Site Structure

A good Information Architecture (IA) in Sitecore clearly organizes your site’s content, structure, and data in a logical, scalable, and maintainable manner. The content is structured around how content authors use and navigate the content rather than how an organization is structured internally. A good Sitecore implementation typically has well thought out approaches for multisite, shared content, data sourcing, external content, and template design.

Shared Content

Shared content is any content that is typically shared between sites. This type of content could be anything from press releases, news articles, or even shared taxonomy.

Data Sourcing

A Sitecore page is comprised of a Layout and Renderings. Each layout has many renderings on it. The header, the footer, call to actions (CTAs), text areas, etc are all typically renderings (often referred to as components). Sitecore’s magic is it’s ability to change the content of renderings based upon all types of personalization rules that can truly provide unique experiences to site visitors. This magic is powered through the use of rendering data sources.

The data source on a rendering points to a content item that could many types of content like text fields or images. They are typically built with the rendering in mind. A CTA content item might contain an image field, a text field, and a target url field. That would allow content authors to dynamically switch out the CTA based upon whatever rules they like.

Multivariate testing (similar to A/B Testing) is also powered by rendering data sources. Typically each option being tested is a different data source on the rendering. A typical red flag on a Sitecore implementation is the lack of use of rendering data sources. A significant amount of out of the box functionality is lost without them.

Too Much Content

Teams building their first Sitecore implementation often fall into a bit of a trap: everything on the website should be in Sitecore. They’ve realized the power of Sitecore and want to leverage every bit of that power throughout the implementation. The reality though is that there can be too much data stored in Sitecore.

Under the hood, all Sitecore items are stored in a single SQL table. That does give you room for many, many items before you run into performance issues but it does put a scalability limit on the content management (CM) environment. A good rule of thumb is to only add items into Sitecore if content authors are expected to edit that content.

An example of this would be a commerce site that sells car parts. There could potentially be millions of SKUs that would correspond to different Sitecore items. It would be better for that data to live in it’s own SQL database rather than in Sitecore directly. Often times a single page in Sitecore renders all of those SKUs as a product page. This same approach applies to any content that is controlled by an external system of record. A red flag here would be seeing Sitecore bucket items containing vast numbers of items that all appear to be content editable.

Templates and Template Inheritance

Templates are the definitions for content items in Sitecore. You might have a CTA template that has fields for Text Message, Image, and Url. This would allow you to make as many CTA items as you like that each have those fields. Template inheritance is where you can make a base template, lets say the one we just defined, and use it to create additional templates.

An example of this would be to create a Product CTA and a Newsletter CTA. Both would inherit the fields from the Base CTA but also have their own distinct fields:

Product CTA:

• Text Message

• Image

• Url

• Product Name

• Short Product Description

Newsletter CTA:

• Text Message

• Image

• Url

• Newsletter Byline

You can keep going down the rabbit hole with this and at first glance it seems like a good thing. A common practice in software development is Don’t Repeat Yourself (DRY) and this seems to fit that perfectly. The downside only comes when you need to reorganize the content.

Finding where a field comes from becomes a more challenging process. If a template is only one level deep it isn’t much of an issue. I have seen inheritance structures going 10 layers deep and that is more of a problem. There is no 100% simple way to track it down.

Changes to base templates can cause unexpected regressions. With many developers on a project it often happens that base templates get used in more places than the original developer of a feature may have expected. An Author base template could be used on nearly any content type. Any change to the base type would impact any rendering that is expecting the old type. This would typically be the type of thing you would expect to catch in a code review but serialized Sitecore content is much more difficult to review than plain code changes in a pull request.

Additionally, template fields can share the same name. Many base templates will have fields named something like Display Name. Now imagine that your child template has 3 base templates all with the same field name. Where is the data coming from? It becomes a bit of a challenge to find out.

Generally speaking I would say that any implementation that uses template inheritance more than 1 level deep to be a red flag and likely technical debt that will come back to bite you someday.

Solution Architecture

Helix

Helix is the recommended architecture for more traditional Sitecore MVC or SXA solutions that would typically be hosted on-prem or platform as a service (PaaS). It provides structural guidelines for the files in the solution, best practices for dependency management, and guidelines for the information architecture. Generally speaking an implementation should follow Helix principles provided that it isn’t headless, XM Cloud, or following a composable DXP strategy.

A solution is typically broken down into three layers: Project, Feature, and Foundation. Typically a Helix solution will break the source tree down into the same structure:

• Src

  • Project

  • Feature

  • Foundation

These three layers also tie directly into dependency management. The project layer only contains configuration, styling, layouts, and the composition of features. That means that a Project layer can only reference Feature and Foundation projects, never other Projects.

Features contain the business logic and reusable functionality that is independent of a Project. This is typically for functionality like navigation, search, banners, or call to actions. Features can reference Foundation projects but never other features or projects.

The Foundation layer generally contains the under the hood functionality shared across features and projects. This covers things like logging, service abstractions, data access, or any other broad set of functionality that can be used by many features or projects.

Generally speaking it’s a red flag to see features referencing other features or projects referencing other projects.

Configuration Transforms

A Sitecore application and all of its underlying functionality are defined via XML configuration files. Every implementation will involve updating the configuration to support new functionality. This is everything from implementing a 404 page (updating the item not found processor) to custom fields in the Solr indexes.

Remember that a Sitecore application is deployed by dropping the newly built code over top of an existing installation. When reviewing a legacy codebase it’s quite often that the updated configuration files get added to source control and replace the originals when deployed. This approach, while common, is technical debt.

A better approach is to use configuration transform files for any change that needs to be applied to the configuration. Typically these files would be added to each Feature or Foundation project that needs it. At application startup, Sitecore picks up these transforms and builds out the final configuration that is used. You can view the merged configuration of a Sitecore installation by navigating to:

https://localhost.cm/sitecore/admin/showconfig.aspx

It is a huge red flag if a solution doesn’t use configuration transforms. That typically means that a much deeper audit of the solution is necessary to uncover all of the technical debt.

Code Generation

By default, Sitecore’s data access library is not strongly typed and has no typed fields for any of the custom fields that you’ve created in the content tree (AKA the information architecture). Older Sitecore solutions would typically use a separately purchased product called Team Development for Sitecore (TDS) to synchronize changes from the Sitecore content tree, typically structural content and templates, into source control.

Virtually every implementation that uses TDS also uses a feature of TDS that generates strongly typed classes for every template that has been synchronized into the solution. While on one hand that’s a great thing as it gives developers strongly typed objects to use and greatly reduces the occurrence of runtime errors for missing template fields. On the other hand it generates a class for every template that has every field in that class. This often leads to very large models being passed throughout the application when really only a few fields are needed for any given instance.

It has become a better practice to manually create the classes as they are needed rather than creating every possibility as part of a code generation process. I wouldn’t necessarily call it a red flag to see code generation in use, but I would say that it’s a good sign to keep an eye open for other deprecated practices that may still be in use.

Glass Mapper

Since the out of the box data access library is rather simplistic, nearly every classic Sitecore implementation uses a 3rd party library called Glass Mapper. It’s essentially a replacement that can map Sitecore items directly to your custom c# classes. It also supports lazy loading for fields that refer to other items and has it’s own caching layer.

While it would be fine for a relatively small site to use the out of the box Sitecore data access library, it would be very rare for a site with any complexity to use it. As Glass Mapper is the only alternative that is actively maintained, it would be a red flag if a complex site wasn’t using it.

Hotfixes

One common theme that I’ve seen in most Sitecore solutions is the failure to apply hotfixes in development environments. It’s critical that the underlying Sitecore code in development matches that of the higher level environments. Too often the hotfixes from Sitecore get passed off to a managed services team that only apply them to production environments. Hotfixes can and have introduced changes to overall site performance when run at scale. They can also potentially overwrite customizations that have been built.

A better approach is to include hotfixes as part of the development process. That can be a pull request into a hotfix branch that also gets merged back into the development branch. It won’t slow down the deployment process and may in fact save time by having more eyes on the changes before they're deployed.

Sitecore and the future

At the time of this writing, the future is looking fairly strong that Sitecore XM Cloud is going to be the new paradigm for Sitecore implementations. To begin future proofing your implementation you will need to consider that XM Cloud is headless, serialization has standardized on Sitecore Serialization, and the lack of official support for backend customization.

XM Cloud sites are headless and built very similar to a Sitecore Jss site. That means all of an implementations razor views will need to be converted into react components. Starting to build react components now can save time during a future migration.

Another challenge is the change to item serialization. The oldest projects typically still use TDS for serialization while newer projects use Unicorn. In either case, the serialized items will need to be replaced with items serialized with Sitecore’s own serialization tools.

Customizations are one of the biggest pain points when moving forward toward XM Cloud. Common pipeline modifications like HttpRequestBegin need to be replaced as the frontend is now decoupled from the backend. Other common issues are with dynamic placeholders and url rerouting.

Changes to the backend of Sitecore like custom field types and replacements for the rich text editor will also be problematic. XM Cloud has introduced a replacement to the Content Editor called Pages that has very limited support compared to the Content Editor. A good rule of thumb is that any customization that could be broken by Sitecore deploying an update to your implementation should be avoided.

Field Types from Sitecore:

• ImageField

• LinkField

• TextField

• DateField

• FileField

• RichTextField

React Components:

• Image

• Link

• Text

• Date

• File

• RichText

• RichTextField

Reference:

https://www.npmjs.com/package/@sitecore-jss/sitecore-jss-nextjs?activeTab=code

Lets take a look at the LinkList.tsx component as an example. Make a copy of the file and name it IconLinkList.tsx. It’s a fairly typical Sitecore component with the following template definitions:

The Link List Folder contains the Link List Root which then contains the Link(s). Lets see if we can update the Link to support an icon as well as the link itself.

Just like in a traditional Sitecore implementation the first step is to add the field to the template. In this case I’ve added the Icon Name field as a text field.

I’ve also updated the content item to fill in the new icon name.

As you look through component’s tsx file you’ll notice that most of the file is just setting up types and interfaces. It’s basically just defining what the data is going to look like for the component.

The entrypoint of the component starts here:

export const Default = (props: LinkListProps): JSX.Element => {
  const datasource = props.fields?.data?.datasource;
  const styles = `component link-list ${props.params.styles}`.trimEnd();
  const id = props.params.RenderingIdentifier;

You can see that the datasource of the component is being passed in as its props and that the props are typed earlier in the code. Now lets say you want to add another field to the data source. It should be easy right? That’s where things get interesting. The types defined in this file need to match the data coming from Sitecore.

So how does that work exactly? It’s not like it’s one item to one datasource. There’s a hierarchy of items in that data source. It starts with the Title text field on the parent item. All of the links are children of that parent item.

The glue that puts that datasource together is in the rendering. The rendering contains a field called Component GraphQL Query. It contains a query that pulls data from the root item with the Title text field and all of the links.

query TitleQuery($datasource: String!, $language: String!) {
  datasource: item(path: $datasource, language: $language) {
    children {
      results {
        field(name: "Link") {
          link: jsonValue
        }
      }
    }
    field(name: "Title") {
      title: jsonValue
    }
  }
}

So this is where the trickiness begins. My first thought was to just add a new duplicate field to the results object above with the new Icon Name field and call it a day as everything just worked. It failed spectacularly.

At first glance everything looks fairly decoupled but in reality these existing components are tightly coupled. The biggest constraints are getting the shape of the output object to match the type defintions in the component. Those definitions then need to be compatible with the Jss components as well. In the end I needed to restructure the query a bit so that it looked like this:

query TitleQuery($datasource: String!, $language: String!) {
  datasource: item(path: $datasource, language: $language) {
    children {
      results {
        field: field(name: "Link") { link: jsonValue}
        iconName: field(name: "Icon Name") { value: value}
      }
    }
    field: field(name: "Title") { title: jsonValue }
  }
}

The type definitions in the component ended up changing to this:

type ResultsFieldLink = {
  field: {
    link: LinkField;
  };
  iconName: TextField;
};

type FooterSocialMediaItemProps = {
  key: string;
  index: number;
  total: number;
  field: LinkField;
  iconName: TextField;
};

With that everything works as expected.

References:

Component GraphQL Query Field in Json Rendering

With Sitecore you can do this easily. Use Sitecore's built in tracker to append page visit history, browser info, etc to your exception messages to give yourself reproduction steps.

Here's some sample code to get started:

public string GetUserHistory()
		{
			var pageHistory = string.Empty;
			try
			{
				var pages = Sitecore.Analytics.Tracker.Current.Session.Interaction.GetPages();
				foreach(var page in pages)
				{
					pageHistory += $"   Url Visit Date: { page.DateTime.ToString("MM/dd/yyyy h:mm tt") } Url: { page.Url + System.Environment.NewLine }";
				}
			}
			catch (Exception e)
			{
                // the tracker may not have been started
				Sitecore.Diagnostics.Log.Warn("Unable to append analytics data to exception", e, this);
			}

			return pageHistory;
		}

The Git command line gives you great power in finding what's changed. In this case we need to:

1. Find out when the last release branch/tag was cut

2. Query the log to find any content item that has changed since that date

Let's start by finding the last commit of the previous release. We tag our releases so we can just type git describe --tags. That will display something like CDPROD-20190702-2200-2.0.204-544-g1b6ee7a90. From there we can run the command git log -1 --format=%ai CDPROD-20190702-2200-2.0.204-544-g1b6ee7a90 which will give us the date: 2019-07-02 15:05:17 -0400.

Now that we have the date we can query git to find any content items that have changed since then. This command makes the assumption that TDS content items have 'Content' in the path.

git log master --since "2019-07-02T15:05:17-04:00" --name-status --oneline -- '*.Content*.item'

This will give output similar to this:

It turns out that Sitecore never expected both Federated Authentication and Virtual Users to be used at the same time. Typically Federated Authentication would handle everything for you but in our case we had a single sign on (SSO) implementation that wasn't quite compatible that drove use to create virtual users as part of the SSO process.

Sitecore Support created a patch for us that in their words:

Fixes excessive ClientData rewrites caused by LoginVirtualUser method when Federated Authentication is enabled.

The site is now running great with the patch in place.

Indexes on the SQL Server

I highly recommend creating some indexes on the SQL databases that will help increase the the speed of the migration process.

Indexes for the Verfication database:

create index VerificationLog_TargetType on VerificationLog (TargetType)
create index VerificationLog_Status on VerificationLog (Status)
create index VerificationLog_OperationType on VerificationLog (OperationType)
create index VerificationLog_Source_Target on VerificationLog(SourceIdentifier, TargetIdentifier)

Indexes for the shards:

create index ContactIdentifiers_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard0].xdb_collection.ContactIdentifiers (ContactId)
create index ContactIdentifiers_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard1].xdb_collection.ContactIdentifiers (ContactId)
create index ContactIdentifiers_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard2].xdb_collection.ContactIdentifiers (ContactId)
create index Contacts_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard0].xdb_collection.Contacts (ContactId)
create index Contacts_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard1].xdb_collection.Contacts (ContactId)
create index Contacts_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard2].xdb_collection.Contacts (ContactId)
create index ContactIdentifiersIndex_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard0].xdb_collection.ContactIdentifiersIndex (ContactId)
create index ContactIdentifiersIndex_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard1].xdb_collection.ContactIdentifiersIndex (ContactId)
create index ContactIdentifiersIndex_ContactId on [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard2].xdb_collection.ContactIdentifiersIndex (ContactId)

Here's a query to see the results of a migration. It's useful to compare these numbers to those in MongoDb.

select b.[Started] as BatchStartDate, 
	format(count(vl.id), 'N0') as RecordCount,
	format(sum(case when vl.TargetType = 'Contact' then 1 else 0 end), 'N0') as ContactCount,
	format(sum(case when vl.TargetType = 'DeviceProfile' then 1 else 0 end), 'N0') as DeviceProfileCount,
	format(sum(case when vl.TargetType = 'Interaction' then 1 else 0 end), 'N0') as InteractionCount
	from [Sitecore.DataExchange.Verification].dbo.VerificationLog vl
	left join [Sitecore.DataExchange.Verification].dbo.[Batches] b on vl.BatchId = b.id
	group by b.[Started]

Here's a query that counts the contacts in the shards themselves. It's a nice sanity check against the verification database:

select format(sum(records), 'N0') as TotalContactsInShards from (
select count(*) as records
	from [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard0].xdb_collection.Contacts s0
union all
select count(*) as records
	from [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard1].xdb_collection.Contacts s1
union all
select count(*) as records
	from [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard2].xdb_collection.Contacts s2
) shards

If you need to clear out SQL Server so that you can re-run the migration process, use this script:

use [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard0]
go
DELETE FROM [xdb_collection].ContactIdentifiers
DELETE FROM [xdb_collection].ContactFacets
DELETE FROM [xdb_collection].InteractionFacets
DELETE FROM [xdb_collection].Interactions
DELETE FROM [xdb_collection].ContactIdentifiersIndex
DELETE FROM [xdb_collection].DeviceProfileFacets
DELETE FROM [xdb_collection].DeviceProfiles
DELETE FROM [xdb_collection].Contacts
go
use [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard1]
go
DELETE FROM [xdb_collection].ContactIdentifiers
DELETE FROM [xdb_collection].ContactFacets
DELETE FROM [xdb_collection].InteractionFacets
DELETE FROM [xdb_collection].Interactions
DELETE FROM [xdb_collection].ContactIdentifiersIndex
DELETE FROM [xdb_collection].DeviceProfileFacets
DELETE FROM [xdb_collection].DeviceProfiles
DELETE FROM [xdb_collection].Contacts
go
use [Sitecore.Xdb.Collection.Database.Sql.ShardMapManagerDb.Shard2]
go
DELETE FROM [xdb_collection].ContactIdentifiers
DELETE FROM [xdb_collection].ContactFacets
DELETE FROM [xdb_collection].InteractionFacets
DELETE FROM [xdb_collection].Interactions
DELETE FROM [xdb_collection].ContactIdentifiersIndex
DELETE FROM [xdb_collection].DeviceProfileFacets
DELETE FROM [xdb_collection].DeviceProfiles
DELETE FROM [xdb_collection].Contacts
go

Configuration

There's a few different types of configuration that need to be done to get up and running. This takes a few web.config changes, a few app_config changes, and your own custom configurations.

Web.config Changes

First up is disabling forms authentication. Do this by changing the authentication mode to none:

<authentication mode="None" />

Next up you need to remove the forms authentication module:

...
<system.webServer>
<modules>
<remove name="FormsAuthentication" />
...

App_Config Changes

The app config changes need some boilerplate Sitecore configuration as well as your custom configuration for your authentication provider. Sitecore's boilderplate config can be found here: \App_Config\Include\Examples\Sitecore.Owin.Authentication.Enabler.config.example. Basically it just turns on federated authentication and enables a few services in Sitecore.

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">
  <sitecore role:require="Standalone or ContentDelivery or ContentManagement">

    <settings>
      <setting name="FederatedAuthentication.Enabled">
        <patch:attribute name="value">true</patch:attribute>
      </setting>
    </settings>

    <services>
      <register serviceType="Sitecore.Abstractions.BaseAuthenticationManager, Sitecore.Kernel"
                implementationType="Sitecore.Owin.Authentication.Security.AuthenticationManager, Sitecore.Owin.Authentication"
                lifetime="Singleton" />
      <register serviceType="Sitecore.Abstractions.BaseTicketManager, Sitecore.Kernel"
                implementationType="Sitecore.Owin.Authentication.Security.TicketManager, Sitecore.Owin.Authentication"
                lifetime="Singleton" />
      <register serviceType="Sitecore.Abstractions.BasePreviewManager, Sitecore.Kernel"
                implementationType="Sitecore.Owin.Authentication.Publishing.PreviewManager, Sitecore.Owin.Authentication"
                lifetime="Singleton" />
    </services>

Next up we need to define our provider:

<identityProviders hint="list:AddIdentityProvider">
        <identityProvider id="Crn" type="Sitecore.Owin.Authentication.Configuration.DefaultIdentityProvider, Sitecore.Owin.Authentication">
          <param desc="name">$(id)</param>
          <param desc="domainManager" type="Sitecore.Abstractions.BaseDomainManager" resolve="true" />
          <caption>Login Button Text</caption>
          <icon>/sitecore/shell/themes/standard/Images/24x24/IconThatsOnTheButton</icon>
          <domain>sitecore</domain> <!-- careful here - you may want to use extranet for public sites -->
          <!--list of identity transfromations which are applied to the provider when a user signin-->
          <transformations hint="list:AddTransformation">
            <transformation name="Idp Claim" ref="federatedAuthentication/sharedTransformations/setIdpClaim" />
            <transformation name="Name Identifier Claim" type="Sitecore.Owin.Authentication.Services.DefaultTransformation, Sitecore.Owin.Authentication">
              <sources hint="raw:AddSource">
                <claim name="sub" />
              </sources>
              <targets hint="raw:AddTarget">
                <claim name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" />
              </targets>
              <keepSource>true</keepSource>
            </transformation>
          </transformations>
        </identityProvider>
      </identityProviders>
      <sharedTransformations>
      </sharedTransformations>

The transformations can be a bit tricky and can really depend on the environment. If the Idp claim isn't returned by your provider you will need to add it here. It's basically just the name of the provider. Sitecore provides a transform to do this:

<transformation name="Idp Claim" ref="federatedAuthentication/sharedTransformations/setIdpClaim" />

The other gotcha is the nameidentifier claim is required by Sitecore. If it doesn't exist you will need to create it. Typically this means filling it with data from another claim:

<transformation name="Name Identifier Claim" type="Sitecore.Owin.Authentication.Services.DefaultTransformation, Sitecore.Owin.Authentication">
              <sources hint="raw:AddSource">
                <claim name="sub" />
              </sources>
              <targets hint="raw:AddTarget">
                <claim name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" />
              </targets>
              <keepSource>true</keepSource>
            </transformation>

Now we need to tell Sitecore what sites it should use the provider for. In this example we're saying use it on every site but that's almost never what you want. You would typically have two entries here, one for the Content Management (Sitecore) login and a separate one for the public facing sites. Think something like Okta Verify for the content editors and Facebook login for the public site.

<federatedAuthentication type="Sitecore.Owin.Authentication.Configuration.FederatedAuthenticationConfiguration, Sitecore.Owin.Authentication">
      <identityProvidersPerSites hint="list:AddIdentityProvidersPerSites">
        <mapEntry name="Crn" type="Sitecore.Owin.Authentication.Collections.IdentityProvidersPerSitesMapEntry, Sitecore.Owin.Authentication">
          <sites hint="list">
            <site>shell</site>
            <site>login</site>
            <site>admin</site>
            <site>service</site>
            <site>modules_shell</site>
            <site>modules_website</site>
            <site>website</site>
            <site>scheduler</site>
            <site>system</site>
            <site>publisher</site>
          </sites>
          <identityProviders hint="list:AddIdentityProvider">
            <identityProvider ref="federatedAuthentication/identityProviders/identityProvider[@id='Crn']" />
          </identityProviders>
          <externalUserBuilder type="Sitecore.Owin.Authentication.Services.DefaultExternalUserBuilder, Sitecore.Owin.Authentication">
            <param desc="isPersistentUser">false</param>
          </externalUserBuilder>
        </mapEntry>
      </identityProvidersPerSites>

The tricky part here is the isPersistentUser setting. Persistent users are basically shadow users that are created and visible in Sitecore's security. You can't actually change their info or reset their passwords though. A big downside here is that you're storing personal data like email addresses in Sitecore itself now. This can cause issues if your organization has requirements around how PII (personally identifiable information) is stored. Often times PII needs to be encrypted in transit and at rest. That would require upgrading to SQL Enterprise rather than just using SQL Standard.

If the setting is false then you don't need to worry about shadow users but you may run into issues with tracking anonymous users across sessions. The documentation isn't 100% clear on this but that's what I've heard. It may take some custom business logic to maintain that tracking.

The last part of the app_config is registering your pipeline:

<pipelines>
      <owin.identityProviders>
        <!-- Processors for coniguring providers. Each provider must have its own processor-->
        <processor type="Site.Foundation.LoginProvider.Pipelines.IdentityProviders.CrnIdentityProvider, Site.Foundation.LoginProvider" resolve="true" />
      </owin.identityProviders>
    </pipelines>

Pipeline Setup

Here's an example pipeline processor:

namespace Site.Foundation.LoginProvider.Pipelines.IdentityProviders
{
    public class CrnIdentityProvider : IdentityProvidersProcessor
    {
        
        public CrnIdentityProvider(
            FederatedAuthenticationConfiguration federatedAuthenticationConfiguration) : base(federatedAuthenticationConfiguration)
        {
            
        }

        protected override string IdentityProviderName
        {
            get { return "Crn"; }
        }

        protected override void ProcessCore(IdentityProvidersArgs args)
        {
            Assert.ArgumentNotNull(args, "args");
            IdentityProvider identityProvider = this.GetIdentityProvider();
            string authenticationType = this.GetAuthenticationType();
            var scope = string.Join(" ", Settings.Default.Scope.Cast<string>()) + " openid";

            args.App.UseOpenIdConnectAuthentication(new OpenIdConnectAuthenticationOptions
            {
                Authority = Settings.Default.EndpointUri.ToString(),
                ClientId = Settings.Default.ClientId, 
                ClientSecret = Properties.Credentials.Default.ClientSecret, 
                Scope = scope, 
                RedirectUri = Properties.Settings.Default.RedirectUri,
                AuthenticationType = authenticationType,
                ResponseType = "code id_token token",
                SignInAsAuthenticationType = authenticationType,
                UseTokenLifetime = false,
                Notifications = new OpenIdConnectAuthenticationNotifications
                {
                    SecurityTokenValidated = notification =>
                    {
                        // the user has been validated but we need to call another 
                        // api to get more fields (name, email address, etc) to inject
                        // as claims before the user is created in Sitecore.
                        var accessToken = notification.ProtocolMessage.AccessToken;
                        // call the api with the access token here

                        // apply any transformations from the app_config
                        // this adds the idp claim that's required by Sitecore
                        notification.AuthenticationTicket.Identity
                          .ApplyClaimsTransformations(new TransformationContext(this.FederatedAuthenticationConfiguration, identityProvider));
                        
                        return Task.CompletedTask;
                    },
                },
            });
            
        }
    }
}

It should be pretty straightforward but the main gotchas here are more around OpenID Connect then Sitecore. The Authority is the url to authenticate against. The ClientID and ClientSecret are similar to a username and password. The ResponseType is a bit tricky though. If you need to make an API call to add aditional claims before Sitecore creates the user then you will need to make sure that it contains the token value. Otherwise the notification.ProtocolMessage.AccessToken field will be null.

Things you can't do in this Pipeline

What you see above is pretty much all you can do here. If you want to change cookie names or providers you will need to override another Sitecore pipeline processor. I'd suggest starting with this and see if it works before adding more. The errors that you get from problems here are very confusing and not descriptive. Oh, and they typically don't show up in any of the logs either.

Signing In vs Signing Out

The main trick here is that you have to request the login url from Sitecore and do a POST to it. If your site is set up to login via links like <a href='/account/login'>Log In</a> then you've got some fixing to do.

Sample code to get the login url:

namespace Site.Foundation.LoginProvider.Services
{
    public class LoginService : ILoginService
    {
        private readonly BaseCorePipelineManager _pipelineManager;

        public LoginService(BaseCorePipelineManager pipelineManager)
        {
            _pipelineManager = pipelineManager;
        }
        
        public string GetLoginUrl(string returnUrl)
        {
            var args = new GetSignInUrlInfoArgs("CFACOM", returnUrl);
            GetSignInUrlInfoPipeline.Run(_pipelineManager, args);

            return args.Result.First().Href;
        }
    }
}

Your login link will now look something more like this:

using (Html.BeginForm(null, null, FormMethod.Post, new { action = Model.SignInUrl }))
            {
                <button type="submit">
                    Login
                </button>
            }

Logging out uses the fairly standard owin method:

owinContext.Authentication.SignOut(new AuthenticationProperties { RedirectUri = redirectUri });

As you investigate further with Sitecore's admin tools you'll realize that it's only controllers that have the problem. It turns out that on release builds with the Optimize Code checkbox checked breaks the assembly naming convention used that's used.

The fix is fairly simple. Replace the original sample code:

serviceCollection.AddMvcControllersInCurrentAssembly();

with this:

serviceCollection.AddMvcControllers(typeof(ServicesConfigurator).Assembly);

* Sitecore StackExchange Answer

This likely won't affect many CD deployment implementations but if it does you aren't crazy. It really IS preventing updates to some configs :)

Example code from Sitecore.Update.dll checking to see if a path is 'safe':

...
if (!this.IsSafeConfigFile(mappedPath))
  {
    collistionBehavior = CollisionBehavior.Skip;
...

and here we see that paths containing connectionstring are not safe:

protected virtual bool IsSafeConfigFile(string mappedPath)
{
  return !mappedPath.ToLowerInvariant().Contains("connectionstring");
}

using (Sitecore.XConnect.Client.XConnectClient client =
                Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                var outcome = new Sitecore.XConnect.Outcome(definitionId.Guid, DateTime.UtcNow.Date, "USD", monetaryValue);
                var contact = _contactRepository.GetXConnectContactFromTracker();
                var interaction = new Interaction(contact, InteractionInitiator.Brand, channel, "Web");
                interaction.Events.Add(outcome);
                client.AddContact(contact);
                client.AddInteraction(interaction);
                client.Submit();
            }

The above code will give this exception:

Concurrency token must not be specified for new entities

To fix the issue just remove the client.AddContact(contact); line. The contact is added via the interaction.

This is great but the installation directions default to installing version 2.0 which isn't compatible with Sitecore 9.0. To install the earlier version do the following:

1. Register the powershell feed
   Register-PSRepository -Name SitecoreGallery -SourceLocation https://sitecore.myget.org/F/sc-powershell/api/v2

2. Install the earlier version of the framework
   Install-Module -Name SitecoreInstallFramework -Repository SitecoreGallery -RequiredVersion 1.2.1

Install Solr

Download Solr version 6.6.1 here. Unzip it and copy the contents to d:\solr-6.6.1

Configure SSL

Next up we need to configure Solr to use SSL. An easy way to do this is to use @kamsar's script from his blog. We will make some minor changes to use a specific DNS name in addition to localhost.

These steps will be different for production environments as you shouldn't be using a self signed key. Get in touch with whomever manages the certificate authority for your organization.

Create the SSL directory in d:\solr-6.6.1.

Next create the solr-ssl.ps1 script. This is slightly modified from @kamsar's version. We're changing the keytool command to use our actual dns in addition to localhost.

param(
	[string]$KeystoreFile = 'solr-ssl.keystore.jks',
	[string]$KeystorePassword = 'secret',
	[string]$SolrDomain = 'localhost',
	[switch]$Clobber
)

$ErrorActionPreference = 'Stop'

### PARAM VALIDATION
if($KeystorePassword -ne 'secret') {
	Write-Error 'The keystore password must be "secret", because Solr apparently ignores the parameter'
}

if((Test-Path $KeystoreFile)) {
	if($Clobber) {
		Write-Host "Removing $KeystoreFile..."
		Remove-Item $KeystoreFile
	} else {
		$KeystorePath = Resolve-Path $KeystoreFile
		Write-Error "Keystore file $KeystorePath already existed. To regenerate it, pass -Clobber."
	}
}

$P12Path = [IO.Path]::ChangeExtension($KeystoreFile, 'p12')
if((Test-Path $P12Path)) {
	if($Clobber) {
		Write-Host "Removing $P12Path..."
		Remove-Item $P12Path
	} else {
		$P12Path = Resolve-Path $P12Path
		Write-Error "Keystore file $P12Path already existed. To regenerate it, pass -Clobber."
	}
}

try {
	$keytool = (Get-Command 'keytool.exe').Source
} catch {
	$keytool = Read-Host "keytool.exe not on path. Enter path to keytool (found in JRE bin folder)"

	if([string]::IsNullOrEmpty($keytool) -or -not (Test-Path $keytool)) {
		Write-Error "Keytool path was invalid."
	}
}

Write-Host ''
Write-Host 'Generating JKS keystore...'
& $keytool -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass $KeystorePassword -storepass $KeystorePassword -validity 9999 -keystore $KeystoreFile -ext SAN=DNS:$SolrDomain,DNS:SOLRNODE1.COMPANY.COM,IP:127.0.0.1 -dname "CN=SOLRNODE1, OU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country"

Write-Host ''
Write-Host 'Generating .p12 to import to Windows...'
& $keytool -importkeystore -srckeystore $KeystoreFile -destkeystore $P12Path -srcstoretype jks -deststoretype pkcs12 -srcstorepass $KeystorePassword -deststorepass $KeystorePassword

Write-Host ''
Write-Host 'Trusting generated SSL certificate...'
$secureStringKeystorePassword = ConvertTo-SecureString -String $KeystorePassword -Force -AsPlainText
$root = Import-PfxCertificate -FilePath $P12Path -Password $secureStringKeystorePassword -CertStoreLocation Cert:\LocalMachine\Root
Write-Host 'SSL certificate is now locally trusted. (added as root CA)'

Write-Host ''
Write-Host '########## NEXT STEPS ##########' -ForegroundColor Green
Write-Host ''
Write-Host '1. Copy your keystore to $SOLR_HOME\server\etc (MUST be here)' -ForegroundColor Green

if(-not $KeystoreFile.EndsWith('solr-ssl.keystore.jks')) {
	Write-Warning 'Your keystore file is not named "solr-ssl.keystore.jks"'
	Write-Warning 'Solr requires this exact name, so make sure to rename it before use.'
}

$KeystorePath = Resolve-Path $KeystoreFile
Write-Host ''
Write-Host '2. Add the following lines to your solr.in.cmd:' -ForegroundColor Green
Write-Host ''
Write-Host "set SOLR_SSL_KEY_STORE=etc/solr-ssl.keystore.jks" -ForegroundColor Yellow
Write-Host "set SOLR_SSL_KEY_STORE_PASSWORD=$KeystorePassword" -ForegroundColor Yellow
Write-Host "set SOLR_SSL_TRUST_STORE=etc/solr-ssl.keystore.jks" -ForegroundColor Yellow
Write-Host "set SOLR_SSL_TRUST_STORE_PASSWORD=$KeystorePassword" -ForegroundColor Yellow
Write-Host ''
Write-Host 'Done!'

Copy the generated keystore solr-ssl.keystore.jks to the d:\solr-6.6.1\server\etc directory.

Next open the d:\solr-6.1.1\bin\solr.in.cmd file an add the following lines to the end:

set SOLR_SSL_KEY_STORE=etc/solr-ssl.keystore.jks
set SOLR_SSL_KEY_STORE_PASSWORD=secret
set SOLR_SSL_TRUST_STORE=etc/solr-ssl.keystore.jks
set SOLR_SSL_TRUST_STORE_PASSWORD=secret

Configure the Firewall

Open TCP port 8983 on the firewall to allow connections to Solr.

Initial Testing

You can now test Solr in a command prompt by running:
bin\solr -c -f -z "SOLRNODE1.COMPANY.COM:2181,SOLRNODE2.COMPANY.COM:2181,SOLRNODE3.COMPANY.COM:2181" -m 18g -p 8983

Navigate to https://SOLRNODE1.COMPANY.COM:8983 to see solr running:

Solr as a Windows Service

We need to set Solr to run automatically. We'll use a process that's very similar to what we did with ZooKeeper.

Create the directory d:\solr-6.6.1\service. Download a copy of prunsrv.exe.

Create a new bat file called InstallSolrService.bat. Add the following content to it:

@echo off

set SERVICE_NAME=solr
set SERVICE_HOME=d:\solr-6.6.1
set PR_INSTALL=%SERVICE_HOME%\service\prunsrv.exe

@REM Service Log Configuration
set PR_LOGPREFIX=%SERVICE_NAME%
set PR_LOGPATH=%SERVICE_HOME%\logs
set PR_STDOUTPUT=auto
set PR_STDERROR=auto
set PR_LOGLEVEL=Debug

set PR_STARTUP=auto
set PR_STARTMODE=exe
set PR_STARTIMAGE=%SERVICE_HOME%\bin\solr.cmd
set PR_STARTPARAMS=-c -z "SOLRNODE1.COMPANY.COM:2181,SOLRNODE2.COMPANY.COM:2181,SOLRNODE3.COMPANY.COM:2181" -m 18g -p 8983

@REM Shutdown Configuration
set PR_STOPMODE=exe
set PR_STOPIMAGE=%SERVICE_HOME%\bin\solr.cmd
set PR_STOPPARAMS=stop -p 8983

%PR_INSTALL% //IS/%SERVICE_NAME% ^
   --Description="Solr-6.6.1" ^
   --DisplayName="%SERVICE_NAME%" ^
   --Install="%PR_INSTALL%" ^
   --Startup="%PR_STARTUP%" ^
   --LogPath="%PR_LOGPATH%" ^
   --LogPrefix="%PR_LOGPREFIX%" ^
   --LogLevel="%PR_LOGLEVEL%" ^
   --StdOutput="%PR_STDOUTPUT%" ^
   --StdError="%PR_STDERROR%" ^
   --StartMode="%PR_STARTMODE%" ^
   --StartImage="%PR_STARTIMAGE%" ^
   --StartParams="%PR_STARTPARAMS%" ^
   --StopMode="%PR_STOPMODE%" ^
   --StopImage="%PR_STOPIMAGE%" ^
   --StopParams="%PR_STOPPARAMS%"

if not errorlevel 1 goto installed
echo Failed to install "%SERVICE_NAME%" service. Refer to log in %PR_LOGPATH%
exit /B 1

:installed
echo The Service "%SERVICE_NAME%" has been installed
exit /B 0

You will need to update the line that contains the DNS addresses and the memory usage.

set PR_STARTPARAMS=-c -z "SOLRNODE1.COMPANY.COM:2181,SOLRNODE2.COMPANY.COM:2181,SOLRNODE3.COMPANY.COM:2181" -m 18g -p 8983

The -m flag is currently setting the memory to 18 GB.

Run the bat file from a command prompt to install the service. Don't forget to set it to run automatically from services.msc.

Rinse and Repeat

Repeat the install process on the other nodes in the cluster.

Using SolrCloud with Sitecore

At this point you should add a load balancer that points to the 3 SolrCloud nodes. Point Sitecore to the load balancer and you're good to go.

There is no method 'Filter' on type 'Sitecore.ContentSearch.Linq.QueryableExtensions' that matches the specified arguments]

It turns out that this error message is caused when Sitecore starts before the Solr service is started. It does not go away after the Solr server starts either. The solution is to either do an iisreset from a command prompt or add a new configuration transform to your project to prevent the issue going forward.

<sitecore>
  <pipelines>
    <initialize>
      <processor type="Sitecore.ContentSearch.SolrProvider.Pipelines.Loader.InitializeSolrProvider, Sitecore.ContentSearch.SolrProvider">
        <patch:delete />
      </processor>
      <processor type="Sitecore.ContentSearch.SolrProvider.Pipelines.Loader.InitializeSolrProvider, Sitecore.ContentSearch.SolrProvider" patch:before="*[@type='Sitecore.Pipelines.Loader.InitializeScheduler, Sitecore.Kernel']"/>
    </initialize>
  </pipelines>
</sitecore>

This solution is from the Sitecore StackExchange site.

ZooKeeper

ZooKeeper is the underlying system that maintains the configuration for the SolrCloud environment. It can be thought of as a distributed filesystem that all Solr nodes have aceess to.

Installation

Let's install ZooKeeper onto our 3 node cluster. It can theoretically be installed on its own cluster but it's more common to put it on the same servers that Solr will use.

For this installation I'm using ZooKeeper v3.4.9.

Install the Java Runtime Environment
Since both ZooKeeper and Solr are Java apps, we will need to install the JRE. I used v1.8 for this installation as the latest version had some compatibility issues with Solr.

After the installer completes you will need to set the JAVA_HOME system environment variable. Its value should be: C:\Program Files\Java\jre1.8.0_172.

Next we need to update the Path environment variable to include the JAVA_HOME variable: %JAVA_HOME%\bin;.

Install ZooKeeper
Extract the ZooKeeper package to the data drive of your server. In our case it will be located in D:\zookeeper-3.4.9.

Create a system environment variable for ZooKeeper. It should be called ZOOKEEPER_HOME and have a value of D:\zookeeper-3.4.9.

Update the system path to include the new variable:

Note that like the JAVA_HOME we've appended the bin directory to the path.

Next we need to copy the %ZOOKEEPER_HOME%\conf\zoo_sample.cfg to zoo.cfg. Open the file and change the dataDir variable to point to this path: dataDir=d:\\zookeeper-3.4.9\\data. Make sure this directory exists.

Create a file called "myid" in the data folder. It must contain the integer id of the server.

Add the DNS entries for the servers in the cluster to the bottom of the zoo.cfg file:

server.1=SERVER1.COMPANY.COM:2888:3888
server.2=SERVER2.COMPANY.COM:2888:3888
server.3=SERVER3.COMPANY.COM:2888:3888

Confirm that this zookeeper node starts correctly by running "zkserver" from the command line.

Run ZooKeeper as a Service
Create the directory %ZOOKEEPER_HOME%\service. Download a copy of prunsrv.exe to this folder. Create a new file called ZooKeeperInstallService.bat with the following contents:

@echo off

SET HOME=d:\zookeeper-3.4.9
SET SERVICE_DIR=d:\zookeeper-3.4.9\service
SET SERVICE_LOGPATH=d:\zookeeper-3.4.9\logs

REM Service configuration
SET SERVICE_NAME=ZooKeeperService
SET PR_INSTALL=%SERVICE_DIR%\prunsrv.exe
SET PR_PIDFILE=servicepid

REM Service log configuration
SET PR_LOGPREFIX=%SERVICE_NAME%
SET PR_LOGPATH=%SERVICE_LOGPATH%
SET PR_STDOUTPUT=%SERVICE_LOGPATH%\stdout.txt
SET PR_STDERROR=%SERVICE_LOGPATH%\stderr.txt
SET PR_LOGLEVEL=All

REM Zookeeper - Classpath Configuration
SET ZOOCFGDIR=%HOME%\conf
SET ZOO_LOG_DIR=%HOME%
SET ZOO_LOG4J_PROP=INFO,CONSOLE
SET ZOOCFG=%ZOOCFGDIR%\zoo.cfg
SET ZOOMAIN=org.apache.zookeeper.server.quorum.QuorumPeerMain

SET CLASSPATH=%ZOOCFGDIR%
SET CLASSPATH=%HOME%\zookeeper-3.4.9.jar;%CLASSPATH%
SET CLASSPATH=%HOME%\lib\jline-0.9.94.jar;%CLASSPATH%
SET CLASSPATH=%HOME%\lib\log4j-1.2.16.jar;%CLASSPATH%
SET CLASSPATH=%HOME%\lib\netty-3.10.5.Final.jar;%CLASSPATH%
SET CLASSPATH=%HOME%\lib\slf4j-api-1.6.1.jar;%CLASSPATH%
SET CLASSPATH=%HOME%\lib\slf4j-log4j12-1.6.1.jar;%CLASSPATH%
SET PR_CLASSPATH=%CLASSPATH%

SET PR_JVMOPTIONS="-Dzookeeper.log.dir=%ZOO_LOG_DIR%";"-Dzookeeper.root.logger=%ZOO_LOG4J_PROP%"

REM Startup configuration
SET PR_STARTUP=manual
SET PR_STARTMODE=java
SET PR_STARTCLASS=%ZOOMAIN%
SET PR_STARTPARAMS=%ZOOCFG%
 
REM JVM configuration
SET PR_JVM=auto
SET PR_JVMMS=256
SET PR_JVMMX=1024

REM Service Shutdown configuration
SET PR_STOPMODE=exe
SET PR_STOPIMAGE=%SERVICE_DIR%\ServiceKiller.exe
SET PR_STOPPARAMS=%SERVICE_LOGPATH%\servicepid
 
REM Install service
prunsrv.exe //IS//%SERVICE_NAME%

Create the %ZOOKEEPER_HOME%\logs folder if it doesn't already exist.

Run the bat file and confirm that it created a service entry in services.msc. You will also need to change the startup mode to be automatic.

Open the Firewall
Next up is adding the required ZooKeeper ports to the firewall. These TCP ports need to allow incoming connections: 2181, 2888, 3888.

Rinse and Repeat
Repeat these steps on the other two servers in the cluster. Remember to change the server id in the myid file.

Install Solr
Installing Solr will be covered in part 2.