How To Change the Local Rendering Container Hostname in XM Cloud

When starting development for Sitecore XM Cloud, the quickest way to set up and start working on a project is to use the starter project template provided when you create a new XM Cloud Project. But this starter template comes with very generic hostnames for the local development containers, and if you are working on several projects it can lead to confusion. You may also want to follow naming conventions established for your project, such as environment-based conventions (e.g. local.project.com, qa.project.com, etc.). In this quick guide we are going to explore how to customize the name of the hostname of the rendering host container for an XM Cloud project created using the starter template.

Customizing the hostnames

Customizing the name of the CM container

Straight to the point, YOU CAN’T. The reason is that in an XM Cloud project, you don’t have a local Identity Server container to handle Sitecore authentication. It is done using the Sitecore-hosted cloud authentication service (https://auth.sitecorecloud.io) and it always expects the CM hostname to be xmcloudcm.localhost.

Customizing the name of the Rendering Host container

When using the default project template for XM Cloud, you will notice that to access the published site in your local environment you have to do it through https://www.xmcloudpreview.localhost. You can customize this hostname by doing the modifications shown below. For this example, we want to use the name www.oshyn.localhost:

• Make sure the Docker containers are not running.

• Open the .env file in the root folder of the project (NOT the one under src/sxastarter, that’s the Next.js environment file) and change the RENDERING_HOST variable:

  Modifications to .env

  … other variables …
  RENDERING_HOST=www.oshyn.localhost
  RENDERING_HOST_INTERNAL_URI=http://rendering:3000
  … other variables …
  

  Notice that we are NOT changing the RENDERING_HOST_INTERNAL_URI value, that one should remain as it comes by default (http://rendering:3000)

• Also in the root of the project, open the init.ps1 file and look for the following sections. Modify only what is commented in the code as shown below:

  Modifications to init.ps1

  ##################################
  # Configure TLS/HTTPS certificates
  ##################################
   
  Push-Location docker\traefik\certs
  try {
      $mkcert = “.\mkcert.exe”
      if ($null -ne (Get-Command mkcert.exe -ErrorAction SilentlyContinue)) {
          # mkcert installed in PATH
          $mkcert = “mkcert”
      } elseif (-not (Test-Path $mkcert)) {
          Write-Host “Downloading and installing mkcert certificate tool…” -ForegroundColor Green
          Invoke-WebRequest “https://github.com/FiloSottile/mkcert/releases/download/v1.4.1/mkcert-v1.4.1-windows-amd64.exe” -UseBasicParsing -OutFile mkcert.exe
          if ((Get-FileHash mkcert.exe).Hash -ne “1BE92F598145F61CA67DD9F5C687DFEC17953548D013715FF54067B34D7C3246”) {
              Remove-Item mkcert.exe -Force
              throw “Invalid mkcert.exe file”
          }
      }
      Write-Host “Generating Traefik TLS certificate…” -ForegroundColor Green
      & $mkcert -install
      & $mkcert “*.oshyn.localhost” ## Modify the local star cert with the desired hostname (after the www)
      & $mkcert “xmcloudcm.localhost”
   
      # stash CAROOT path for messaging at the end of the script
      $caRoot = “$(& $mkcert -CAROOT)\rootCA.pem”
  }
  catch {
      Write-Error “An error occurred while attempting to generate TLS certificate: $_”
  }
  finally {
      Pop-Location
  }

  In the previous code block, the modification is on the line that says & $mkcert “*.oshyn.localhost”.

  Modifications to init.ps1

  ################################
  # Add Windows hosts file entries
  ################################
   
  Write-Host “Adding Windows hosts file entries…” -ForegroundColor Green
   
  Add-HostsEntry “xmcloudcm.localhost”
  Add-HostsEntry “www.oshyn.localhost” ## Modify this line with your desired hostname

  Modifications to init.ps1

  ###############################
  # Populate the environment file
  ###############################
   
  if ($InitEnv) {
   
      Write-Host “Populating required .env file values…” -ForegroundColor Green
   
      # HOST_LICENSE_FOLDER
      Set-EnvFileVariable “HOST_LICENSE_FOLDER” -Value $LicenseXmlPath
   
      # CM_HOST
      Set-EnvFileVariable “CM_HOST” -Value “xmcloudcm.localhost”
   
      # RENDERING_HOST
      Set-EnvFileVariable “RENDERING_HOST” -Value “www.oshyn.localhost” ## Modify this line with your desired hostname
  

• Finally, modify the certs_config.yaml file under docker/traefik/config/dynamic:

  Modifications to certs_config.yaml

  tls:
    certificates:
      - certFile: C:\etc\traefik\certs\_wildcard.oshyn.localhost.pem
        keyFile: C:\etc\traefik\certs\_wildcard.oshyn.localhost-key.pem
      - certFile: C:\etc\traefik\certs\xmcloudcm.localhost.pem
        keyFile: C:\etc\traefik\certs\xmcloudcm.localhost-key.pem

  The modifications are to the first certFile and keyFile values, using the new _wildcard.oshyn.localhost name. The other values should remain as they are with xmcloudcm.localhost.

• Run the init.ps1 script again to re-initialize the environment with the new values:

Modifications to init.ps1

> .\init.ps1 -InitEnv -LicenseXmlPath C:\path\to\license.xml -AdminPassword YourAdminPassword

• Run your containers with the up.ps1 script and access using a browser the rendering host with the new name (in this example, https://www.oshyn.localhost)

Conclusion

Although you will not be able to change the CM container’s hostname because of cloud authentication, you can customize the rendering host’s hostname so you can reduce confusion when working on multiple projects or if you need to follow project-established naming conventions.