Walkthrough: Using the Getting Started template
How to use the Getting Started template to quickly set up Sitecore containers and a rendering host for your first Sitecore Headless Development experience.
Sitecore provides a Getting Started template for Sitecore developers that want to try out Sitecore Headless Development with ASP.NET and Sitecore containers. You can use it to get started quickly or to kick-start new customer projects.
The template does not implement Sitecore Helix conventions for solution architecture. As you begin building your Sitecore solution, we recommend reviewing Sitecore Helix and the Sitecore Helix Examples for guidance on implementing a modular solution architecture.
The template includes:
A Docker environment with a Sitecore topology (by default XP0). The template also includes configuration for the XM1 and XP1 topologies.
Note
The template includes
docker-compose
files for every supported topology. You can find them in therun\sitecore-<topology>
folder. For example,run\sitecore-xm1\docker-compose.yml
. The includeddocker-compose.yml
file is a standard environment from the Sitecore Container Support Package. Thedocker-compose.override.yml
file for each topology contains customizations made for this solution.An ASP.NET rendering host.
Serialized items for a one-page sample site. See the
src\Items.module.config
file for details.An MSBuild project named
Platform
for deploying configuration and code into the Sitecore Content Management role. See thesrc\platform
folder for details.An MSBuild project named
RenderingHost
for an ASP.NET rendering host. See thesrc\rendering
folder for details.
Before you can create a solution from the Getting Started template, you must install some software components and install the template.
This walkthrough describes how to:
Install the prerequisites
Install the template
Create the MyProject solution
Test the MyProject solution
Install the prerequisites
Before you can install the template and create a solution, you must install the following software components on your workstation:
.NET Core 6.0 SDK (check your installed version with the
dotnet --version
command).NET Framework 4.8 SDK (see the Microsoft procedure for checking .NET Framework versions)
Docker for Windows (with Windows Containers enabled)
PowerShell 5.1 (PowerShell 7 is not supported)
See the Sitecore Containers documentation for more information on system requirements.
Install the template
You download and install the template in your file system. Afterward, you can create solutions based on the template.
To install the template:
Open PowerShell with administrator privileges.
Run the following command:
dotnet new -i Sitecore.DevEx.Templates --nuget-source https://sitecore.myget.org/F/sc-packages/api/v3/index.json
The dotnet
tool does not provide obvious feedback that the installation was successful. However, the install command ends by listing all of the installed templates. If the install is successful, the list includes sitecore.aspnet.gettingstarted
.
Create the MyProject solution
You can name your solution anything you like but, in this example, we name the solution MyProject
.
To create the MyProject
solution:
Open PowerShell with administrator privileges.
Check if you have Internet Information Server running on port 443:
Get-Process -Id (Get-NetTCPConnection -LocalPort 443).OwningProcess
If you do, you must to stop it:
iisreset /stop
Check if you have Apache Solr or any other service running on port 8984:
Get-Process -Id (Get-NetTCPConnection -LocalPort 8984).OwningProcess
If you do, you must stop it:
Stop-Service -Name "<the name of your service>
Or, if you have started it with Non-Sucking Service Manager, stop it with this command:
nssm stop "<the name of your service>"
Go to your solutions folder and create the
MyProject
solution and project:dotnet new sitecore.aspnet.gettingstarted -n MyProject
Important
You must use Latin characters in the project/folder name. Using non-Latin characters can give unexpected results because of character limitations in Docker registry names and URLs.
Go to the
MyProject/
folder.Run the following script to prepare the Sitecore container environment:
.\init.ps1 -InitEnv -LicenseXmlPath "<C:\path\to\license.xml><path to your license.xml file>" -AdminPassword "<your Sitecore administrator password>" -Topology <topology>
You must provide an absolute path for the license file.
The
-Topology
parameter is optional. Supported values for the-Topology
parameter arexp0
(default),xm1
, andxp1
.The script prepares the following items:
A valid/trusted wildcard certificate for
*.myproject.localhost
.The hosts file entries for
myproject.localhost
.The required environment variable values in the
.env
file for the Sitecore instance.
Download the Sitecore Docker images and install the containers:
.\up.ps1
The template creates the following entries in the Windows
hosts
file. Each of them points to a Sitecore container:https://id.myproject.localhost/
points to themyproject_id_1
container with a Sitecore instance hosting Sitecore Identity Server.https://cm.myproject.localhost/
points to themyproject_cm_1
container with a Sitecore instance hosting Content Management, Content Delivery, and Sitecore Layout Service.https://www.myproject.localhost/
points to themyproject_rendering_1
container with the rendering host.
Note
If the
up.ps1
command fails and shows you the message not implemented, go to your Docker for Windows setup and disable the experimental Docker Compose V2 feature.Wait for the script to open a browser tab for the Sitecore Identity Server. Then log in and accept the device authorization.
Wait for the script to open browser tabs for Content Management and the rendering host.
The application does not include a reference to the .env
file in the .gitignore
file so that developers can share initialized environment variables. If you check your .env
file into source control, other developers can prepare a certificate and hosts
file entries by simply running the init.ps1
script.
If your Sitecore solution or its data are sensitive, we recommend excluding the .env
file from source control and providing other means of centrally configuring the variables.
Test the MyProject solution
After creating your solution, you can modify and publish it using the Content Editor and use Visual Studio to modify and publish your code.
To test the solution:
Follow the instructions to publish, run, and test the Getting Started template.