Using Docker EntryPoints to configure for development and production

The Sitecore Docker images repository is an open source GitHub repository which you can access here today. It has been created with a large amount of contributions from the community and is constantly evolving. It provides examples of how to build images and combine them into fully functioning Sitecore systems, and includes example EntryPoints showing how you can customize your container's execution.

Watch the video accompanying this article below, which includes demos of these concepts. Or watch it on Discover Sitecore on YouTube.

Before we take a look at what is provided as part of the Sitecore Docker Images repository, we should talk about what an EntryPoint is and when you would want to make use of them. If you look over the Docker documentation, it describes an EntryPoint as:

But what does that mean? Well, in essence, an EntryPoint provides a method for you to execute a command within a container, either at build time, or when the container is first run. In this post and the related video, we're going to focus on the second use case: executing a command within a container when it is first run.

The Sitecore Docker Image repository comes with two example EntryPoints provided out of the box:

• Production EntryPoint - provides functionality around logging and monitoring
• Development EntryPoint - provides the functionality from the Production EntryPoint and also introduces debugging and deployment functionality.

This EntryPoint is designed to help with Production workloads and introduces two features: IIS Service Monitor and File Beat.

IIS Service Monitor

The IIS.ServiceMonitor feature is a Windows executable designed to be used as the EntryPoint process when running IIS inside a Windows Server container. It ties the status of the container to the status of the IIS process running inside of it. Tying these two together means that if the IIS process errors and exits, then the Container itself will exit as well. This means that it becomes much simpler to look externally and see whether a container is in a healthy state or not.

FileBeat

The second feature added is related to logging. When you run Sitecore directly on your host machine, the logs are written straight to disk and are very easy to access. This is the case for the Sitecore logs, as well as other system logs like the IIS logs.

While you can access the file system when you run applications inside of containers, that isn't generally the best approach for logging. There are a few steps involved to access the containers files that make this more difficult. Also, due to the ephemeral nature of containers, if there is an error and a container is recreated, then all of the logs stored inside it would be lost. A better approach is to move the logging to be stored outside of the container.

The Production endpoint provided with the Sitecore Docker Images repository makes use of FileBeat to send these logs to STDOUT as you can see above. File beat is a lightweight log forwarder that is designed to form part of the ELK Stack created by the folks at Elastic. It's pretty straightforward to wire up the Sitecore containers to an existing ELK setup, but you can also use the STDOUT integration that you get out of the box. You can, for example, view the logs for a specific container by using Docker Logs. It's also possible to view the aggregated logs for all of the Sitecore containers running your system with a single command by using Docker Compose Logs.

If you prefer to use a GUI to interact with your containers and would rather access your logs that way, then you can use a program like Portainer instead:

Portainer is a complete docker management interface that you can create and configure in just two commands. You can find details on how to get started with Portainer here.

The Development EntryPoint takes all of the functionality in the Production EntryPoint detailed above and builds on top of it. It adds features covering remote debugging and deployments. The debugging functionality allows you to connect an IDE running on your host to the process executing in the container to debug the code execution.

The deployment functionality works through a PowerShell script called WatchDirectory.ps1. This script makes use of Docker Volumes to give you a method to push file changes into a running container. You create a volume to map a folder on your host machine to be mapped into the 'c:\src'  folder inside the container. The WatchDirectory PowerShell script automatically copies any files that are placed in that location to the 'C:\inetpub\wwwroot'  folder where the Sitecore instances are running from.

This gives you the ability to publish from your IDE or CLI of choice to the folder on your host and the assets will all be copied into the Sitecore root ready to be accessed by the site.

How do you change the EntryPoint?

The EntryPoint you choose to use is specified in the Docker-Compose file when you establish your container definition. If you take a look at this definition for a Sitecore CD container, you'll see the EntryPoint line setting this container up to run with the Production EntryPoint:

 cd: 
   image: $REGISTRYsitecore-xm-cd:$SITECORE_VERSION-windowsservercore-$WINDOWSSERVERCORE_VERSION 
   entrypoint: powershell.exe -Command "& C:\\tools\\entrypoints\\iis\\Production.ps1" 
   ports: 
     - "44002:80" 
   environment: 
     SITECORE_LICENSE: $SITECORE_LICENSE 
     SITECORE_APPSETTINGS_ROLE:DEFINE: ContentDelivery 
     SITECORE_CONNECTIONSTRINGS_SECURITY: Data Source=sql;Initial Catalog=Sitecore.Core;User ID=sa;Password=$SQL_SA_PASSWORD 
     SITECORE_CONNECTIONSTRINGS_WEB: Data Source=sql;Initial Catalog=Sitecore.Web;User ID=sa;Password=$SQL_SA_PASSWORD 
     SITECORE_CONNECTIONSTRINGS_EXPERIENCEFORMS: Data Source=sql;Initial Catalog=Sitecore.ExperienceForms;User ID=sa;Password=$SQL_SA_PASSWORD 
     SITECORE_CONNECTIONSTRINGS_SOLR.SEARCH: http://solr:8983/solr 
     ENTRYPOINT_STDOUT_IIS_ACCESS_LOG_ENABLED: 'true' 
     ENTRYPOINT_STDOUT_IIS_ERROR_LOG_ENABLED: 'true' 
     ENTRYPOINT_STDOUT_SITECORE_LOG_ENABLED: 'true' 
   depends_on: 
     sql: 
       condition: service_healthy 
     solr: 
       condition: service_started

To change this over to use the Development EntryPoint all you would need to do is to change the EntryPoint line to instead reference the Development.ps1 script, then map in your volume for the deployment directory.

I just want to finish off with a few tips and tricks to help get you started with working with these EntryPoint scripts:

• The WatchDirectory.ps1 script will not only copy in any files and folders, it will also delete any files and folders you delete as well. So you'll need to be careful that you don't end up accidentally deleting something you don't want removed.
• If you want to connect the FileBeat instances to the ELK stack, this is fairly simple to set up. However, the ELK stack only runs on Linux containers, so you will need to enable Docker's Experimental Features to be able to run Linux and Windows containers side-by-side. You can find more details on this here.
• If you like running Portainer to use a GUI to view your container information, you can integrate it into your Docker-Compose file to have it automatically created with your Sitecore containers. Whether you want to do this depends on whether you want this Portainer instance to live alongside your Sitecore containers, or whether you want it to live separately to monitor other containers or other Sitecore instances you might have running.

Thanks for reading and make sure to follow #LearnSitecore for future content!

Rob Earlam, Technical Evangelist, Sitecore
https://robearlam.com/