Go to the homepage
Powered bySitecore Search logo
Skip to main contentThe Project Solution Setup page has loaded.

Project Solution Setup

Context

As the technical lead on the project, you need to set up the Project and Environment(s) in the customer portal, as well as a source code repository, so that the project developers can start implementing the client project, commit, and deploy their code.

Execution

There are two paths to setup the solution, depending on whether you are using a source code provider with a supported integration to the XM Cloud Deploy app or not. In the following use case we will focusing on GitHub, but Azure DevOps steps are available in the source control and hosting providers documentation.

Setting up your first Project, Environment, and Site - Supported Integration

In the process of creating a new Project, you connect a GitHub Repository. Make sure you grant following access rights:

  • Read access to metadata
  • Read and write access to administration and code
  • Access to all repositories

If granting those permissions is against your organization’s security policies, follow the “No Integration” steps to setup the project. The Project and Environment creation process requires these to copy a GitHub project to your private or company repository.

In the setup process the project requires a name. Make sure to use proper Naming conventions in case your license allows to have to more than one project or your are planning more projects in the future. Similarly, when creating the first environment you will choose the name of the environment, make sure you are using a standard Naming convention.

Each environment needs to be setup to be a production or non-production environment. So it’s crucial to mark only the production environment accordingly and your QA and UAT environment as non-productions. Give the environments applicable names.

Setting up your first Project, Environment, and Site - No Integration

When creating a project with no integration, you will need to use the Sitecore Cloud CLI.

  • Login to the XM Cloud Deploy App using the CLI

    dotnet sitecore cloud login

  • Create a project providing name of the project and the region where this should be created

    dotnet sitecore cloud project create --name <project-name>

  • Create an environment within that project passing the project ID of the previously created project and the environment name

    dotnet sitecore cloud environment create `
  --name <environment-name> `
  --project-id <project-id-of-previously-created-project>

  • Deploy to your environment using the environment id. This will provision the different XM Cloud resources, build and deploy the foundation head solution and run post actions.

    dotnet sitecore cloud deployment create `
  -id <environment-id-of-previously-created-environment>

  • Fork the Foundation Head repository (for Next.js or for ASP.NET Core) into your source control

  • Deploy your custom solution using the environment ID and the upload parameter. Make sure to run this command from your solution root. Note: the deployment log can be followed live in the deploy app.

    dotnet sitecore cloud deployment create `
  -id <environment-id-of-previously-created-environment> `
  --upload

Create a new Site

Once the process of provisioning the CM resources, and deploying your code and first items to the XM Cloud environment is done, you need to access the dashboard. From here you will create your first site.

For a client project, create an empty site - follow the Creating a Site recipe for further detail.

xmcloud.build.json file includes configuration for rendering host. Next.js is configured by default.

Walk through the Solution

As mentioned earlier, it is required to start using the foundation head solution. This can be either cloned during the project creation process or forked separately.

The solution contains everything to run XM Cloud locally using Docker Containers as well as running the head application locally connecting towards the GraphQL Preview Endpoint.

The Next.js template it contains .env file for managing environment specific connection strings as well as the NextJS application named sxastarter.

Next.JS Foundation Head - Starter Kit


Items Serialization

The items folder contains serialized versions of the items coming from XM Cloud. Those items are stored in yml format and organized based on the item hierarchy and the configuration in the module.json files.

Check out the Setup Sitecore Content Serialization recipe for more details.

Platform

The platform folder can contain customizations you want to add to the XM Cloud content management instance. It is not recommended to do customizations.

The headapps folder represents the head application built with NextJS. it contains its own .env file. The src folder provides already implementation such as a out of the box components but also middleware functionalities such as redirects or personalization.

Middleware functionalities such as redirects or personalization are provided out of the box. Please note that the starter template currently uses the page router instead of the newer app router introduced with version 13.

Next Steps

Using .env.template

  • Rename .env to .env.template in your solution root
  • remove confidential data from .env.template
  • Set .env to be ignored by git in .gitignore file
  • update init.ps1 to copy .env from .env.template before any of the env variables are set

Based on your framework, rename the project accordingly -

Rename the nextjs-starter Project:

  1. Rename nextjs-starter app folder name to your client related application name
  2. Update the appName property in the package.json to your Site name field of your site item
  3. In .env.templateset COMPOSITE_PROJECT_NAME to the new appname and set RENDERING_HOST to match your new appname
  4. In init.ps1
    • change the certificate creation to create certificates according your RENDERING_HOST entry
    • change initialization of environment variables to use the RENDERING_HOST value
    • make host file adjustments use the host name from RENDERING_HOST environment variable
  5. In docker-compose.overwrite.yml change rendering volumes to .\src\[YOUR_APP_FOLDER_NAME]:C:\APP
  6. Update the source code path in the xmcloud.build.json
  7. In cert_config.yml change traefik configuration to match the app_folder_name
  8. In package-lock.json change name field and packages name field to app_folder_name
  9. In render.ts change the comment from sxastarter to your app_folder_name
  10. In Platform.csproj change AssemblyName
  11. In AssemblyInfo.cs change AssemblyTitle and AssemblyProduct accordingly
  12. Rename Solution File XMCloudSXAStarter.sln to what your are using in Assembly configurations.

Insights

Structure in XM Cloud

When starting in XM Cloud the overall structure needs to be understood. When getting access to the Sitecore Composable DXP through the Sitecore Cloud Portal you’ll be part of an Organization that contains the subscription. Depending on the licensing model of your subscription you’ll be able to create and manage 1 to many XM Cloud projects each one containing 1 to many XM Cloud environments.

XM Cloud Structure

When to use Site Collections, Site Collection Folders and Site Folders

XM Cloud is made for multisite implementations. Dependent on the amount of sites you have and the requirements for separation, XM Cloud helps you to organize and manage sites in a hierarchical way.

Every site requires to be within a Site Collection. The Site collection can be seen as a brand folder. But the site collection is not only good for separating and organizing your sites, but also provides certain features. You can share content from one site to another within a site collection. You can create internal links between sites. Sites within a site collection share the same page templates.

If you need content separation you can create a dedicated site collection.

Review the Site Management and Multisite Architecture recipes for further details on how to setup the best multi-site setups.

© Copyright 2025, Sitecore. All Rights Reserved

Legal

Privacy

Get Help

LLM