Reading time: 5 min read
How to Create a Custom Sitecore Index When Using Docker
Integrating custom indexes with Docker to optimize Sitecore development
Due to the normalization of docker for development, tasks such as adding a custom index to your local environment will require additional configuration along with the custom index config we’ve been using from ages. In this blog we’ll go through in detail what you’ll need to do in order to get a custom index set up.
Why Create a Custom Index?
Before we dive into the configuration part, lets first understand why a custom index is needed and how to take advantage of it. Sitecore’s OOTB indexes are decent enough but they take a hit as soon as the complexity of the website increases like you’ve multi site solution, massive amount of content/media items, etc. OOTB indexes will have a hard time with the former and you might start to have performance issues. This is where custom indexes come in handy because it’ll do the following:
- faster searches - will only search for items that are in your index
- index specific items and fields - will only index the items that you’ve specified in your custom index config
- customized re-indexing
How to Create a Custom Index
Disclaimer: We’re using the docker deployment package found under the download options when visiting Sitecore’s download page so the folder structure might differ from what you’re working for your project and so we’re adding the custom index straight to what Sitecore offers OOTB.
Docker Compose Override
First step is to look if you’ve a docker-compose.override.yml file in your project. If you don’t, then create one otherwise modify the existing one. We need a custom docker image which is based on the default solr-init image which has a build context.
image - name of the custom image based on the default solr-init image.
context - path to the Dockerfile that we’ll use for our custom image
PARENT_IMAGE - name of the image in docker-compose.yml file for your solr-init
services:
solr-init:
image: ${COMPOSE_PROJECT_NAME}-solr-init:${SITECORE_VERSION}
build:
context: ./docker/build/solr-init
args:
PARENT_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xm1-solr-init:${SITECORE_VERSION}
solr-init Dockerfile
We’ll now create a Dockerfile at the path of the context and add the following code. The last tells Sitecore to add a custom core when you initialize Solr.
# escape=`
ARG PARENT_IMAGE
FROM ${PARENT_IMAGE}
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
# Copy cores-fishtank.json for core creation
COPY .\cores-fishtank.json C:\data\cores-fishtank.json
core.json
Next, we’ll add a cores-fishtank.json at the same location where our Dockerfile is and add the following code.
{
"sitecore": ["_fishtank_custom_index"]
}
Delete Indexes
If you’re developing on a project, then chances are you already have the OOTB indexes created. In order for above code to create a custom index you’ll need to delete the existing indexes first. A quick way to check if your custom index is being created or not after you do a docker compose up -d is to check within your solr-data folder OR check your image container for the following message.
If you’ve receive the above message, then the solr initialization is getting skipped and which is why you won’t be able to see your custom index. So take a backup of your solr-data folder and empty the whole folder. After clearing and running up, you should see the following in your image container.
Also, the solr-data folder will now contain your custom index.
Final Thoughts & Troubleshooting Tips
That’s it folks! Before the docker adaptation we only need to copy an existing index and rename the .core properties plus the index folder but with docker the story changes and requires a bit of configuration to have your custom index up. DO NOT forget to add a Sitecore config with the same index name otherwise even though your index is added to Solr, Sitecore won’t recognize it (this remains changed before docker adaptation so it is not included). Below are some troubleshooting tips if you’re facing any problems. Also, checkout our blog to secure Solr with BasicAuth when hosted on Azure when you go upstream. Below are some troubleshooting tips to help you get setup with the custom index:
- Visit Solr Admin (
https://localhost:8984/solr/#) and check if your custom index is added. - If you have an existing
docker-compose.override.ymlwhich containssolr-initdefinition, then its best to do adocker-compose build --no-cacheto rebuild yoursolr-initbefore you do yourdocker compose up -d - If it still doesn’t work then you can go your docker desktop and delete your custom
solr-initimage(s) and then do the above step.