1. Sitecore Headless Development

Walkthrough: Using the Getting Started template

Version:

Sitecore provides a Getting Started template for Sitecore developers that want to try out Sitecore Headless Development with ASP.NET and Sitecore containers. It can be used to get you started quickly or to kickstart new customer projects.

The template does not implement Sitecore Helix conventions for solution architecture. As you begin building your Sitecore solution, we recommend that you review Sitecore Helix and the Sitecore Helix Examples for guidance on implementing a modular solution architecture.

The template includes:

  • A Docker environment for a Sitecore XP0 topology with an ASP.NET rendering host.

    Note

    The included docker-compose.ymlfile is a stock XP0 environment from the Sitecore Container Support Package. All changes for this solution are included in the docker-compose.override.yml file.

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

To create a solution from the Getting Started template, complete the following procedures:

Install the prerequisites

Before you can install the template and create a solution, make sure that you have these software components installed 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 install Sitecore.DevEx.Templates --nuget-source https://nuget.sitecore.com/resources/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

  5. Go to the MyProject/ folder.

  6. You use the provided init.ps1 script to prepare the following items for the Sitecore container environment:

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

    Important

    • Using non-Latin characters in the project/folder name can give unexpected results because of character limitations in Docker registry names and URLs.

    • See the Sitecore Containers documentation for more information on these preparation steps.

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

    Provide an absolute path for the license file.

    Out of the box, this example doesn't include a reference to the .env file in the .gitignore file. This is 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 and/or its data are sensitive, we recommend that you keep the .env file excluded from source control and provide another means of centrally configuring the information within.

  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:

  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.

Test the MyProject solution

Tip
If you have suggestions for improving this article, let us know!