Skip to main content

Walkthrough: Using the Getting Started template

Abstract

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 the run\sitecore-<topology> folder. For example, run\sitecore-xm1\docker-compose.yml. The included docker-compose.yml file is a standard environment from the Sitecore Container Support Package. The docker-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 the src\platform folder for details.

  • An MSBuild project named RenderingHost for an ASP.NET rendering host. See the src\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:

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:

  1. Open PowerShell with administrator privileges.

  2. 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:

  1. Open PowerShell with administrator privileges.

  2. 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

  3. 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>"

  4. 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.

  5. Go to the MyProject/ folder.

  6. 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 are xp0 (default), xm1, and xp1.

    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.

  7. 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:

    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.

  8. Wait for the script to open a browser tab for the Sitecore Identity Server. Then log in and accept the device authorization.

  9. 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:

Tip