Experience Sitecore !

Here's the awkward part of this failure: SitecoreAI Page Builder opens the page in its editor iframe and the website content is right there. You can see it, but you never get the editing UI. The ng-spd-loading-indicator stays on top indefinitely and blocks interaction with the page.

Nothing points immediately to a dead rendering host. The page isn't blank, the app hasn't crashed completely, and there's no obvious "rendering host is unavailable" message. You may get only one browser console error, and it may look unrelated - duplicate initialization of a third-party script, for example.

For me, Page Builder got as far as displaying the page. The Sitecore loading overlay then stayed there. Getting the fix into DEV, UAT and PROD involved slightly different deployments, but it was the same fix, applied and verified in each environment.

Here is how I got from those first suspicions to the fix.

Something to start with.

First, a reminder of what Page Builder does when rendering in XM Cloud / SitecoreAI.

These are the main references:

• Environment, editing hosts and rendering hosts
• Configure an external editing host
• Editor integration using metadata

The public website isn't all that Page Builder needs. It sends a request to a rendering endpoint, usually:

https://<editing-host-or-rendering-host>/api/editing/render

The endpoint checks the editing secret and takes the Sitecore editing parameters from the request. It fetches editing layout data, renders the page with metadata and returns markup for Page Builder.

That's why rendering with metadata matters: a visible website isn't necessarily editable in Page Builder.

What I First Suspected

There are several reasonable places to start with a Page Builder spinner. Some of them do explain other cases.

1. Broken Rendering Host Configuration

The rendering host item was the first thing I suspected:

/sitecore/system/Settings/Services/Rendering Hosts

When using metadata-based editing, pay attention to these fields:

Server side rendering engine endpoint URL:
https://<host>/api/editing/render

Server side rendering engine application URL:
https://<host>/

Server side rendering engine configuration URL:
https://<host>/api/editing/config

I couldn't put the main failure down to these values, although wrong values here can stop Page Builder early. They are still worth checking.

2. Missing Environment Variables

After that I looked at the environment configuration. The following variables are needed for Preview context and editing on the editing host and external rendering hosts:

SITECORE_EDGE_CONTEXT_ID
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID
NEXT_PUBLIC_DEFAULT_SITE_NAME
SITECORE_EDITING_SECRET

I did have differences between environments, and corrected the variables, but the spinner still didn't go away. A missing value can give you 401, 404 or 500 from the render endpoint, depending on where it causes the application to fail.

3. Content, Presentation Details, or Personalization

Since I could see content in the iframe, a content-level problem seemed possible too:

• final/shared presentation that is broken
• a component that throws only in edit mode
• a datasource item that is missing in Preview
• a personalization rule that breaks the layout service output
• a page using a rendering without metadata support

I wouldn't rule these out as causes of a Page Builder failure. But I had the same application-level behavior across multiple pages and environments; it seemed less likely that one content item was behind it.

4. Experience Edge, Publishing, Indexing, or Links Database

I also considered whether the backend state could explain it:

• an item that hasn't been published to Edge
• an Edge cache that is stale
• an index that hasn't been rebuilt
• a links database that hasn't been rebuilt
• page route resolution that is wrong

I'd investigate those for missing content on a public site. But for editing, Page Builder gets Preview context and editing layout data. A problem rendering the public page can look much like an editing render problem in the browser, without being the same problem.

5. Browser Console Errors

The console also reported duplicate initialization of a third-party SDK. Suspicious, yes, but it wasn't blocking editing. The console was useful in the investigation; that prominent warning just wasn't the cause.

The Actual Symptom to Focus On

I wasn't dealing with a simple "the page does not load" failure.

More precisely, this was the failure:

The page content renders, but Page Builder never receives the successful editing-render completion it expects, so the ng-spd-loading-indicator never goes away.

I needed to look at the flow described above.

With a fully broken page, I'd usually look for a rendering exception. When the page renders but Page Builder can't edit it, I'd inspect the editing render flow.

The critical request is:

/api/editing/render

Editable markup with metadata is what Page Builder expects from that request.

How the Render Flow Is Supposed to Work

For Content SDK and Next.js, a Page Builder call to the render API route has parameters along these lines:

/api/editing/render
  ?secret=<editing-secret>
  &sc_site=<site-name>
  &sc_itemid=<item-id>
  &sc_lang=en
  &route=/
  &mode=edit
  &sc_version=latest
  &sc_layoutKind=shared

The SDK render middleware then:

1. Checks that the editing secret is valid.
2. Takes the editing parameters from the request.
3. Turns on preview/editing mode.
4. Calls the application back to render the requested page.
5. Sends back HTML containing the metadata needed by Page Builder.

Following the callback back into the application showed me the problem.

This was an App Router application with a multisite route:

/{site}/{locale}/[[...path]]

Public traffic could use that route without trouble. The default render handler still did not know enough about where to render for Page Builder. Its internal editing render request was therefore subject to the usual routing and middleware, instead of being sent to a dedicated editing route.

Which left me in this rather odd situation:

• the page was visibly rendered
• the editing request was still affected by middleware and routing
• the response reaching Page Builder wasn't exactly what it needed
• the spinner stayed in place

The Fix: Create a Dedicated Editing Render Page

I needed the SDK render handler to send Page Builder editing requests somewhere private. I changed it to use a dedicated route and avoid coming back through the normal public one.

The render API route was creating its handlers with no options:

import { createEditingRenderRouteHandlers } from '@sitecore-content-sdk/nextjs/route-handler';

export const { GET, POST, OPTIONS } = createEditingRenderRouteHandlers({});

I added the options shown here:

import { createEditingRenderRouteHandlers } from '@sitecore-content-sdk/nextjs/route-handler';

export const { GET, POST, OPTIONS } = createEditingRenderRouteHandlers({
  allowedQueryParams: ['secret'],
  resolvePageUrl: () => '/sitecore-editing',
});

These options give the SDK the following instructions:

• preserve the secret query parameter
• render editing requests through /sitecore-editing
• do not guess the public page URL for the internal request

For that private route I added this App Router page:

src/app/sitecore-editing/page.tsx

By the time this page renders the Sitecore page in editing mode, the SDK has already transformed the original sc_* query parameters into the editing request. Public traffic doesn't belong on this route.

The page has three jobs.

First comes request validation:

const CONTENT_SDK_PREVIEW_HEADER = "__content_sdk_preview";

if (
  !editingPreviewData ||
  requestHeaders.get(CONTENT_SDK_PREVIEW_HEADER) !== "1" ||
  secret !== scConfig.editingSecret
) {
  notFound();
}

Then it builds the editing preview data:

return {
  site,
  itemId,
  language,
  mode: mode === "edit"
    ? LayoutServicePageState.Edit
    : LayoutServicePageState.Preview,
  variantIds: getSearchParam(searchParams, "variantIds") || DEFAULT_VARIANT,
  version: getSearchParam(searchParams, "version"),
  layoutKind: getSearchParam(searchParams, "layoutKind") as LayoutKind | undefined,
};

It must then fetch Sitecore preview data, not public page data:

const page = await client.getPreview(editingPreviewData);

I could reuse the layout and providers from the normal public page. The data for this route comes from editing preview data, however, and the route stays out of the public routing behavior.

Do Not Forget Middleware

The middleware also needed a bypass.

If middleware handles multisite routing, localization, redirects, personalization, authentication, language cookies or similar behavior, it may also intercept /sitecore-editing.

That is expected for public traffic, but can interfere with an internal editing render request.

I added a bypass for this route in the proxy/middleware:

export async function proxy(req: NextRequest, _ev: NextFetchEvent) {
  const langCookie = req.cookies.get(LANG_COOKIE_NAME)?.value;
  const pathname = req.nextUrl.pathname;

  if (pathname === '/sitecore-editing') {
    return NextResponse.next();
  }

  // normal middleware logic follows
}

The editing render pipeline needed this bypass in order to use the route.

How I Verified the Fix

You don't need to open Page Builder yet to make the following checks.

1. Check the Render API Route

The render endpoint should respond to OPTIONS:

curl.exe -sS -o NUL -D - -X OPTIONS https://<host>/api/editing/render

A good response is:

HTTP/1.1 204 No Content
X-Matched-Path: /api/editing/render

That response tells you the route is there on the deployed host.

2. Check the Private Editing Route

Direct browser access to /sitecore-editing should be blocked by the page's protection:

curl.exe -sS -o NUL -D - https://<host>/sitecore-editing

Expected result:

HTTP/1.1 404 Not Found
X-Matched-Path: /sitecore-editing

The request has matched the route, so the route exists. But a direct request has neither the internal preview header nor the secret. The security checks should therefore refuse access, which is what this response shows.

3. Check the Actual Page Builder Network Flow

Now open Page Builder with the Network tab in view.

The request to /api/editing/render should complete. A normal error needs its own troubleshooting. When the HTML looks like a public route, there are two checks: resolvePageUrl must point to /sitecore-editing and middleware must not rewrite it.

Deployment Gotchas Across DEV, UAT, and PROD

The environments had different deployment setups.

In DEV the shared render helper was already in the application branch. I could therefore put the fix straight through the development branch.

For UAT I needed to update both the Sitecore editing host and the external Vercel rendering host. Either can be used by Page Builder; the rendering host item configuration determines which.

In PROD the production editing host was tied to main, rather than the development branch. I couldn't push the whole development branch to it. Instead I backported just the fix to main, including only:

src/app/api/editing/render/route.ts
src/app/sitecore-editing/page.tsx
src/proxy.ts

Then the production editing host was deployed from main, and the production Vercel projects were deployed manually because Git deployments were disabled for those projects.

That's why I would check both hosts' deployments when fixing Page Builder. The public rendering host may not be deployed in the same way as the Sitecore editing host.

The Minimal Checklist

For another occurrence, I'd work through these checks:

1. Establish whether Page Builder is failing during editing render, rather than just public page rendering.
2. Check /api/editing/render on the rendering host configured in Sitecore.
3. Use the metadata endpoint in the rendering host item, not an old /jss-render endpoint.
4. Check the host has SITECORE_EDITING_SECRET and the Edge preview variables.
5. Check whether App Router, middleware, redirects, localization or multisite proxy logic intercept editing requests.
6. Give App Router editing render its own /sitecore-editing route.
7. Have createEditingRenderRouteHandlers use that route via resolvePageUrl.
8. Make middleware bypass /sitecore-editing.
9. Get the change deployed to the Sitecore editing host and all external rendering hosts that Page Builder might use.
10. Check OPTIONS /api/editing/render, and check the protection against direct access on /sitecore-editing.

Final Thoughts

I had a rendered site and visible content, which hardly looked like a crash. I also had console errors that could lead me away from the actual problem. None of that changed the fact that Page Builder couldn't proceed.

The response from the rendering host has to be editing-aware and metadata-enabled for SitecoreAI Page Builder. When using Next.js App Router with custom middleware, I'd take the safest option: give the SDK render handler a dedicated private route and keep it outside the normal public routing pipeline.

After that change the spinner went away. Editing worked normally across the environments again.

So even if it looks like a broken component or an item you can't edit, check what happens between Page Builder and the rendering host as well.

For local SitecoreAI containers, you might want to avoid Docker Desktop. Docker Desktop requires a paid subscription for organizations with more than 250 employees or an annual revenue of more than $10 million. So, can you run the XM Cloud local container stack without Docker Desktop at all?

The answer is yes. I went through Sitecore's official documentation, the starter kit repositories and every community walkthrough I could find. I was checking what's supported, what's community-derived and what's missing. 

You can use this for a local Sitecore development environment if Docker Desktop isn't available, you don't want it, licensing restricts its use, or it's unstable. Install the standalone Docker Engine and run it directly as a Windows service. For Docker Compose, use the CLI plugin path that modern Docker tooling expects.

1. Already got Docker Desktop? Remove it first

Already have Docker Desktop installed? Stop it first. To replace it entirely, uninstall Docker Desktop before you install the standalone Docker Engine.

It's worth considering a cleanup of old Docker resources before you carry on, particularly if Windows container layers have taken up a lot of space.

For Docker daemon cleanup, Vikrant Punwatkar’s Docker cleanup guidance uses this longer shutdown timeout:

dockerd -D --shutdown-timeout 900

Docker may need that extra time to clean up large Windows container layers.

2. Enable required Windows features

These features are probably already available if you've used Docker Desktop. If they aren't, open PowerShell as Administrator and run:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
Enable-WindowsOptionalFeature -Online -FeatureName containers -All

Restart Windows if prompted.

You'll commonly need both Hyper-V and Containers for Windows container development.

3. Download standalone Docker Engine for Windows

Run PowerShell as Administrator:

curl.exe -o docker.zip -LO https://download.docker.com/win/static/stable/x86_64/docker-20.10.13.zip

Then extract the archive:

Expand-Archive docker.zip -DestinationPath C:\

You should now find the Docker binaries here:

C:\docker

4. Add Docker to PATH

In Administrator PowerShell, keep this command on a single line:

[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path', 'Machine'));C:\docker", [System.EnvironmentVariableTarget]::Machine)

The current shell still needs its path refreshed:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine")

Close and reopen PowerShell if docker still isn't recognized.

5. Register Docker daemon as a Windows service

To register Docker Engine as a Windows service, run:

dockerd --register-service

Now start the Docker service:

Start-Service docker

Check that Docker is running:

docker version
docker info

Try a basic container run:

docker run hello-world

6. Install Docker Compose v2 CLI plugin

First, create the Docker CLI plugin directory:

New-Item -ItemType Directory -Force -Path "C:\Program Files\Docker\cli-plugins"

Next, download Docker Compose v2:

curl.exe -L "https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-windows-x86_64.exe" -o "C:\Program Files\Docker\cli-plugins\docker-compose.exe"

It also needs to be on PATH. Run the following PowerShell in admin mode:

$d='C:\Program Files\Docker\cli-plugins'; $m=((([Environment]::GetEnvironmentVariable('Path','Machine') -split ';') | ? { $_ -and $_  -ne "$d\docker-compose.exe" -and $_ -ne $d } | select -Unique) + $d) -join ';';  [Environment]::SetEnvironmentVariable('Path',$m,'Machine'); $env:Path=$m

Verify Compose:

docker compose version
docker-compose version

Use this plugin path:

C:\Program Files\Docker\cli-plugins\docker-compose.exe

With that path, docker compose works as a Docker CLI plugin.

7. Configure Docker daemon if needed

The file to create, or edit if it's already there, is:

C:\ProgramData\docker\config\daemon.json

Here's a safe starting point for many Sitecore Windows container setups:

{
  "experimental": true,
  "features": {
    "buildkit": false
  }
}

Once you've changed the daemon configuration, restart Docker:

Restart-Service docker

For Sitecore projects, experimental: true may be needed for a solution that mixes Windows and Linux containers. Some older Sitecore container setups do this.

8. Stop local IIS and Solr before starting Sitecore containers

Watch out for local IIS or Solr services: they can clash with the ports used by Sitecore containers.

Stop IIS:

iisreset /stop

For an installed local Solr Windows service, stop it through services.msc, or use its service name if you know it:

Stop-Service -Name "solr-*"

If the wildcard doesn't match your service, list the services first:

Get-Service *solr*

9. Run your Sitecore project

Which command you run from the project root depends on the project's structure.

The following may be what you need for many SitecoreAI local container setups.

If this is the first run, you must initialize it first:

cd .\local-containers\scripts
.\init.ps1 -InitEnv -LicenseXmlPath C:\Projects\license.xml -AdminPassword b -baseOs ltsc2022

After that, run the main script:

.\local-containers\scripts\up.ps1

Now sit comfortable, grab your coffee and wait until it pulls all the required images and runs:

There can be quite a bit going on in a Sitecore local container startup script. It may:

• Pull or update images
• Build custom images
• Configure hosts file entries
• Start Docker Compose services
• Start the CM container
• Install Sitecore CLI plugins
• Populate Solr schemas
• Rebuild indexes
• Push serialized items

Troubleshooting checklist

I'd check admin mode before chasing any of the issues below. Make sure that's how you're running the scripts, especially on restricted corporate and enterprise machines.

Docker service does not start

First, check the service and start it:

Get-Service docker
Start-Service docker

Then check what Docker reports:

docker info

If Docker fails with references to panic.log, try removing this file and starting Docker again:

Remove-Item "C:\ProgramData\docker\panic.log" -Force
Start-Service docker

Docker command is not recognized

Is Docker in the machine PATH? Check it here:

[Environment]::GetEnvironmentVariable("Path", "Machine")

Also check that the binary is actually there:

dir C:\docker\docker.exe

Refresh the PATH in the current PowerShell session:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine")

Docker Compose is not recognized

Check that the plugin file is there:

dir "C:\Program Files\Docker\cli-plugins\docker-compose.exe"

Verify Compose:

docker compose version

Ports are already in use

Check common Sitecore container ports:

netstat -ano | findstr ":443"
netstat -ano | findstr ":8079"
netstat -ano | findstr ":8984"
netstat -ano | findstr ":14330"

If IIS is using port 443:

iisreset /stop

Windows container layers consume too much disk space

Rebuilding Sitecore containers over and over can leave Windows container layers piling up in Docker’s storage folders.

Here are the usual cleanup commands:

docker system df
docker system prune -a

When Windows layers are stubborn about cleanup, the Docker daemon may need a longer shutdown timeout:

dockerd -D --shutdown-timeout 900

Try Docker’s own cleanup commands first. Be careful if you do delete Docker layer folders by hand.

If you've ever worked on multiple SitecoreAI (XM Cloud) projects at the same time, you know the pain. Often you have to terminate working on Project A, run docker compose down, wait, switch .env files, run docker compose up, wait some more... and then realize you need to quickly check something back in Project A. Rinse, repeat, lose your sanity. What a time waste!

What if I told you there's a way to run three completely independent XM Cloud Docker environments side by side, all on the same Windows machine, all accessible on standard HTTPS port 443, with full network isolation between for each of them?

Let's dig into how I made it work.

The Problem - Why Can't We Just Run Three Docker Compose Stacks?

At first glance, running three copies of the XM Cloud starter kit seems straightforward. Clone the repo three times, change some ports, and done. Right?

Not quite. There are two showstoppers:

1. The Hostname Lock-In

Sitecore's XM Cloud identity server (Auth0) expects callbacks to xmcloudcm.localhost or *.xmcloudcm.localhost. This is hardcoded on their end. Every single CM instance in the standard setup uses xmcloudcm.localhost as its hostname. If three CM containers all claim the same hostname, only one wins.

2. The Traefik Port War

The Traefik reverse proxy in each codebase is set up for port 443 and port 8079. The first one starts; Docker rejects the rest because the ports are already in use.

There are further collisions for MSSQL at port 14330 and Solr at port 8984.

The Solution - A Shared Traefik Gateway with Subdomain Routing

These are the three parts of the setup I used:

One Traefik to rule them all. Instead of three competing Traefik instances, we run a single shared Traefik at the root level that acts as the gateway for all environments.

Third-level subdomains for CM. Auth0 already allows *.xmcloudcm.localhost. That allows us to use one.xmcloudcm.localhost, two.xmcloudcm.localhost, and three.xmcloudcm.localhost. All three hostnames use one wildcard TLS certificate. This is the configuration for each codebase:

  ┌────────────┬─────────────────────────────────────────────┬────────────┬───────────┐
  │  Codebase  │                 CM Hostname                 │ MSSQL Port │ Solr Port │
  ├────────────┼─────────────────────────────────────────────┼────────────┼───────────┤
  │ codebase-1 │ https://one.xmcloudcm.localhost/sitecore/   │ 14331      │ 8984      │
  ├────────────┼─────────────────────────────────────────────┼────────────┼───────────┤
  │ codebase-2 │ https://two.xmcloudcm.localhost/sitecore/   │ 14332      │ 8985      │
  ├────────────┼─────────────────────────────────────────────┼────────────┼───────────┤
  │ codebase-3 │ https://three.xmcloudcm.localhost/sitecore/ │ 14333      │ 8986      │
  └────────────┴─────────────────────────────────────────────┴────────────┴───────────┘

A shared bridge network for Traefik routing. CM and rendering containers from each codebase join the same nat network. Traefik uses that network to reach them; the internal infrastructure (MSSQL, Solr) remains isolated on each project's default network.

The connections between the gateway and the codebases look like this:

                     +----------------------+
                     |   Shared Traefik     |
                     |   Port 443 / 8079    |
                     +--+-------+-------+---+
                        |       |       |
                   traefik-shared (nat network)
                        |       |       |
   +----------+--+  +---+------+---+  +--+----------+
   | codebase-1  |  | codebase-2   |  | codebase-3  |
   |  xmc-one    |  |  xmc-two     |  |  xmc-three  |
   | MSSQL:14331 |  | MSSQL:14332  |  | MSSQL:14333 |
   | Solr:8984   |  | Solr:8985    |  | Solr:8986   |
   +-------------+  +--------------+  +-------------+

And the hostname mapping should loke as:

  ┌─────────────┬─────────────────────────────────────────────┐
  │   Service   │                  Hostname                   │
  ├─────────────┼─────────────────────────────────────────────┤
  │ CM 1        │ https://one.xmcloudcm.localhost/sitecore/   │
  ├─────────────┼─────────────────────────────────────────────┤
  │ CM 2        │ https://two.xmcloudcm.localhost/sitecore/   │
  ├─────────────┼─────────────────────────────────────────────┤
  │ CM 3        │ https://three.xmcloudcm.localhost/sitecore/ │
  ├─────────────┼─────────────────────────────────────────────┤
  │ Rendering 1 │ https://nextjs.xmc-one.localhost/           │
  ├─────────────┼─────────────────────────────────────────────┤
  │ Rendering 2 │ https://nextjs.xmc-two.localhost/           │
  ├─────────────┼─────────────────────────────────────────────┤
  │ Rendering 3 │ https://nextjs.xmc-three.localhost/         │
  └─────────────┴─────────────────────────────────────────────┘

What We Need to Change

I needed only a few changes to get this in place. Here is what I changed.

Step 1: The Shared Traefik

I put a shared-traefik folder at the root of the multi-docker directory and gave it its own docker-compose.yml:

services:
  traefik:
    isolation: hyperv
    image: traefik:v3.6.4-windowsservercore-ltsc2022
    command:
      - "--ping"
      - "--api.insecure=true"
      - "--providers.docker.endpoint=npipe:////./pipe/docker_engine"
      - "--providers.docker.exposedByDefault=false"
      - "--providers.file.directory=C:/etc/traefik/config/dynamic"
      - "--entryPoints.websecure.address=:443"
      - "--entryPoints.websecure.forwardedHeaders.insecure"
    ports:
      - "443:443"
      - "8079:8080"
    healthcheck:
      test: ["CMD", "traefik", "healthcheck", "--ping"]
    volumes:
      - source: \\.\pipe\docker_engine\
        target: \\.\pipe\docker_engine\
        type: npipe
      - ./traefik:C:/etc/traefik
    networks:
      - traefik-shared

networks:
  traefik-shared:
    name: traefik-shared
    external: true

A single Traefik connects to the Docker engine through a Windows named pipe; this connection lets it discover all containers across all Compose projects; it uses the traefik-shared network to reach the CM and rendering containers.

Before starting Traefik, create the shared network with the Windows nat driver:

docker network create -d nat traefik-shared

Why nat and not bridge? Windows containers do not support the bridge driver. Running docker network create traefik-shared without -d nat produces this error: "could not find plugin bridge in v1 plugin registry". I ran into this early on.

For TLS, I referenced wildcard certificates in shared-traefik/traefik/config/dynamic/certs_config.yaml:

tls:
  certificates:
    - certFile: C:\etc\traefik\certs\_wildcard.xmcloudcm.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmcloudcm.localhost-key.pem
    - certFile: C:\etc\traefik\certs\_wildcard.xmc-one.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmc-one.localhost-key.pem
    - certFile: C:\etc\traefik\certs\_wildcard.xmc-two.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmc-two.localhost-key.pem
    - certFile: C:\etc\traefik\certs\_wildcard.xmc-three.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmc-three.localhost-key.pem

Step 2: Parameterize the Traefik Labels

The most important and most subtle change to the existing codebase was prefixing the router, middleware and service names:

With the Docker provider, Traefik takes container labels to build its routing table. The stock docker-compose.yml contains these CM labels:

- "traefik.http.routers.cm-secure.rule=Host(`${CM_HOST}`)"

The router name cm-secure is hardcoded. If three CM containers all define cm-secure, Traefik merges them into a single router with unpredictable results.

The fix is elegant: prefix every router, middleware, and service name with ${COMPOSE_PROJECT_NAME}:

- "traefik.http.routers.${COMPOSE_PROJECT_NAME}-cm-secure.rule=Host(`${CM_HOST}`)"

Since each codebase has a unique COMPOSE_PROJECT_NAME in its .env (e.g., xmc-one, xmc-two, xmc-three), the router names become xmc-one-cm-secure, xmc-two-cm-secure, etc. Globally unique. Zero conflicts.

Make this change throughout the Traefik label lines in both docker-compose.yml (CM labels) and docker-compose.override.yml (rendering host labels).

I parameterized the host ports for MSSQL and Solr as well:

# Was: "14330:1433"
ports:
  - "${MSSQL_PORT:-14330}:1433"

The :-14330 default means if you don't set MSSQL_PORT, nothing changes. Backward compatible.

Step 3: The Multi-Instance Override

Each codebase gets a docker-compose.multi.yml that does three things:

1. Disables the per-codebase Traefik (since the shared one handles everything)
2. Connects CM and rendering to the shared Traefik network
3. Passes the site name to the rendering container

services:
  traefik:
    deploy:
      replicas: 0

  cm:
    labels:
      - "traefik.docker.network=traefik-shared"
    networks:
      - default
      - traefik-shared

  rendering-nextjs:
    environment:
      NEXT_PUBLIC_DEFAULT_SITE_NAME: ${SITE_NAME:-xmc-one}
    labels:
      - "traefik.docker.network=traefik-shared"
    networks:
      - default
      - traefik-shared

networks:
  traefik-shared:
    name: traefik-shared
    external: true

The traefik.docker.network label tells the shared Traefik which network to use for the route to this container. Otherwise Traefik may choose the wrong network and fail silently.

This file is loaded automatically via the COMPOSE_FILE variable in .env:

COMPOSE_FILE=docker-compose.yml;docker-compose.override.yml;docker-compose.multi.yml

Windows gotcha: The COMPOSE_FILE variable uses this separator on Windows: ; (semicolon), not : (colon). Colons produce the CreateFile ... The filename, directory name, or volume label syntax is incorrect error. I took longer to find that separator problem than I wanted to.

Step 4: Per-Codebase .env Configuration

Each codebase's .env gets a handful of unique values:

Do not forget SITECORE_FedAuth_dot_Auth0_dot_RedirectBaseUrl - it must match the CM hostname, for example:

SITECORE_FedAuth_dot_Auth0_dot_RedirectBaseUrl=https://one.xmcloudcm.localhost/

Step 5: The Hosts File

This is pretty simple - just add these entries to C:\Windows\System32\drivers\etc\hosts:

127.0.0.1	one.xmcloudcm.localhost
127.0.0.1	two.xmcloudcm.localhost
127.0.0.1	three.xmcloudcm.localhost
127.0.0.1	nextjs.xmc-one.localhost
127.0.0.1	nextjs.xmc-two.localhost
127.0.0.1	nextjs.xmc-three.localhost

Step 6: Fix up.ps1

The up.ps1 script has a Traefik health check that uses the hardcoded router name cm-secure@docker. Since we parameterized it, we need to read COMPOSE_PROJECT_NAME and use it:

$composeProjectName = ($envContent | Where-Object {
    $_ -imatch "^COMPOSE_PROJECT_NAME=.+"
}).Split("=")[1]

# Updated health check
$status = Invoke-RestMethod "http://localhost:8079/api/http/routers/$composeProjectName-cm-secure@docker"

And the hardcoded Start-Process https://xmcloudcm.localhost/sitecore/ becomes:

Start-Process "https://$xmCloudHost/sitecore/"

Making the Next.js Rendering Hosts Work

Getting the CM to respond on a subdomain was easier than making the Next.js rendering hosts work.

The "Configuration error" Wall

Once the CM instances were responding on their subdomains, I moved on to the rendering hosts. In each codebase, the rendering-nextjs container mounts the Next.js app from examples/basic-nextjs and runs npm install && npm run dev as its entrypoint. All three containers crashed immediately with this error:

Error: Configuration error: provide either Edge contextId or
local credentials (api.local.apiHost + api.local.apiKey).

The stock sitecore.config.ts contains only defineConfig({{}}), with no API configuration. Although that is enough for an XM Cloud Edge connection in production, local Docker mode requires the Content SDK's build tools to know where the CM is.

Add the api.local block:

import { defineConfig } from '@sitecore-content-sdk/nextjs/config';

export default defineConfig({
  api: {
    local: {
      apiKey: process.env.SITECORE_API_KEY || '',
      apiHost: process.env.SITECORE_API_HOST || '',
    },
  },
  defaultSite: process.env.NEXT_PUBLIC_DEFAULT_SITE_NAME || 'xmc-one',
  defaultLanguage: 'en',
});

The SITECORE_API_HOST is set to http://cm by the compose override (the internal Docker DNS name for the CM container), and SITECORE_API_KEY comes from the .env file. So far so good.

The "Invalid API Key" Surprise

With the config in place, I restarted the rendering containers. They got further this time - the SDK successfully connected to the CM - but then:

ClientError: Provided SSC API keyData is not valid.

Here's the thing about Sitecore API keys: having a GUID in your .env file is not enough; that GUID must be registered as an item inside Sitecore's content tree at /sitecore/system/Settings/Services/API Keys/. Without it, Sitecore rejects the key outright.

The standard up.ps1 flow registers the key through the Sitecore CLI's serialization push. Run it separately for each of the three parallel instances:

cd codebase-1
dotnet sitecore cloud login                    # Browser auth required
dotnet sitecore connect --ref xmcloud `
  --cm https://one.xmcloudcm.localhost `
  --allow-write true -n default

& ./local-containers/docker/build/cm/templates/import-templates.ps1 `
  -RenderingSiteName 'xmc-one' `
  -SitecoreApiKey 'c46d10a5-9d62-4aa9-a83d-3e20a34bc981'

This creates the API key item under /sitecore/system/Settings/Services/API Keys/xmc-one with CORS and controller access set to *. Browser login uses the interactive Auth0 device flow. It is needed only once per codebase.

The "//en" Path Mismatch Mystery

Once the API keys were registered and the containers restarted, the rendering hosts started. Next.js reported Ready in 6.2s; I opened https://nextjs.xmc-one.localhost/ in the browser and got "Page not found."

The container logs showed this:

[Error: Requested and resolved page mismatch: //en /en]
GET / 404 in 53ms

The double slash in //en pointed to a path-resolution problem between the Content SDK's multisite and locale middleware; the locale middleware added /en to the path /, but no defaultSite was configured; the multisite resolver therefore could not determine which site to use, and produced the double-slash path.

Two changes fixed it:

1. Set defaultSite in sitecore.config.ts (as above), so the SDK knows which Sitecore site to resolve by default
2. Pass NEXT_PUBLIC_DEFAULT_SITE_NAME to the rendering container as an environment variable in docker-compose.multi.yml

The Hostname Binding

The path mismatch was fixed, but I still had a 404 from the rendering host. I used this request to verify that the CM's layout service was responding correctly:

curl -sk "https://one.xmcloudcm.localhost/sitecore/api/layout/render/jss?item=/&sc_apikey=&sc_site=xmc-one&sc_lang=en"

That returned valid JSON with the Home page route data. So the CM was fine. The problem was in Sitecore's site resolution.

In the Sitecore Content Editor, each site has a Site Grouping item with a Hostname field. This field tells Sitecore which incoming hostname maps to which site. Without it, when the rendering host queries the CM for layout data, Sitecore does not know which site the request is for.

The fix: go to each CM's Content Editor and set the Hostname to the rendering host's domain:

• xmc-one site -> Hostname: nextjs.xmc-one.localhost
• xmc-two site -> Hostname: nextjs.xmc-two.localhost
• xmc-three site -> Hostname: nextjs.xmc-three.localhost

After that, all three rendering hosts returned HTTP 200, each serving content from their respective Sitecore instance. Three independent XM Cloud stacks, all running in parallel, all on standard HTTPS.

Running It All

First-Time Setup

# Run as Administrator
cd C:\Projects\SHIFT-AI\Multiple-Docker
.\setup-multi.ps1

This creates the Docker network, generates wildcard TLS certificates with mkcert, and updates the hosts file.

Then initialize each codebase (if not already done):

cd codebase-1\local-containers\scripts
.\init.ps1 -InitEnv -LicenseXmlPath C:\License\license.xml -AdminPassword "YourPassword"
# Repeat for codebase-2 and codebase-3

Daily Usage

# Start everything
.\start-all.ps1

# Start just one codebase
.\start-all.ps1 -Codebases @("codebase-2")

# Stop everything
.\stop-all.ps1

# Stop codebases but keep Traefik running (faster restarts)
.\stop-all.ps1 -KeepTraefik

Post-Startup: Register API Keys and Create Sites

After the CMs are healthy, you need to register the API keys and create sites with hostname bindings (see the sections above). This is a one-time step per codebase.

Verifying It Works

Check the Traefik Dashboard

Open http://localhost:8079/dashboard/ before the public hosts. It is my quick sanity check for the shared gateway. Expect six routers: a CM router and a rendering router per codebase, each with its unique prefix. Seeing both routes for every project tells me that discovery worked; it does not yet prove that the page content is correct. The dashboard helps separate a routing problem from a page problem. If a router is missing, I check its labels and network attachment before testing the URLs below. Once the six entries are present, I use the browser checks below to see whether the redirects and home pages respond.

Hit Each CM Instance

• https://one.xmcloudcm.localhost/sitecore/ -> Auth0 login redirect
• https://two.xmcloudcm.localhost/sitecore/ -> Auth0 login redirect
• https://three.xmcloudcm.localhost/sitecore/ -> Auth0 login redirect

Hit Each Rendering Host

• https://nextjs.xmc-one.localhost/ should return the site home page (HTTP 200).
• https://nextjs.xmc-two.localhost/ -> Site home page (HTTP 200)
• https://nextjs.xmc-three.localhost/ -> Site home page (HTTP 200)

Each should serve its Sitecore content from an independent CM, MSSQL, and Solr instance; all three should respond.

Lessons Learned

Windows Docker networking has its own rules. The driver is nat; several nat networks on one container are unreliable. I dropped my three Traefik networks and used one shared nat network. CM and rendering containers use it; MSSQL and Solr stay on project-default networks.

COMPOSE_FILE uses semicolons on Windows. Linux: COMPOSE_FILE=a.yml:b.yml:c.yml. Windows: a.yml;b.yml;c.yml. Colons produce a cryptic CreateFile ... volume label syntax error.

Traefik label names are global. The Docker provider sees every router name. Two containers using one name can make Traefik resolve the collision incorrectly. Prefix each with ${COMPOSE_PROJECT_NAME}; I will use that pattern in future multi-project Docker and Traefik setups.

Docker Compose labels are merged, not replaced. An override keeps base labels; it can add labels but cannot remove them. Changing the base file is cleaner.

sitecore.config.ts needs explicit local API config. The stock defineConfig({{}}) assumes Edge. Local Docker needs api.local.apiKey and api.local.apiHost; without them, the Content SDK build tools (sitecore-tools project build) stop.

The defaultSite setting prevents the //en mismatch. Without it, multisite and locale middleware produce //en rather than /en; valid CM content still returns 404. Setting defaultSite with NEXT_PUBLIC_DEFAULT_SITE_NAME fixes it.

Sitecore must have the API key registered, not only present in .env. The GUID in SITECORE_API_KEY_APP_STARTER must also be a Sitecore item under /sitecore/system/Settings/Services/API Keys/. The same GUID is registered by import-templates.ps1 and dotnet sitecore ser push.

Sitecore sites need hostname bindings. API keys and config do not prevent a 404 until the site's Hostname field in Sitecore matches its rendering host. The CM's layout service uses that binding.

What Could Be Simplified Further

• Template-driven .env generation: generate .env files for N codebases, not only three.
• Compose profiles: use Docker Compose profiles to switch modes instead of deploy.replicas: 0.
• Single-codebase fallback: remove COMPOSE_FILE from .env to restore standalone mode.
• Automated API key registration: one script can generate, register, and configure the key for each codebase.

The total change is about 10 lines per codebase in the Docker compose files, one sitecore.config.ts update, and a handful of infrastructure files at the root.

If you've been juggling multiple XM Cloud projects and constantly stopping and starting Docker environments, I hope this saves you some time and frustration. The checks above are the places I would start: the network driver, the file separator, the router names, the local API settings, key registration, and hostname binding. The linked example is the starting point I used while putting the three environments together. It still needs fine tuning, but it shows the shape of the solution and the checks that made the three hosts respond. Drop a comment if you've found other approaches or run into edge cases - I'd love to hear about them. That is the whole idea. Keep the first run small. Check one route, then the next. It keeps some backtracking out of the process. It was enough to make the setup usable. I would start there.

GitHub (not fully operable, must be fine-tuned in some way)

This post is merely a cheatsheet focused on XM Cloud DevOps and deployment, which I left for myself to have all the important Sitecore CLI commands in one place.

SitecoreAI gives teams three paths for managing deployments: the DeployApp web UI in the Cloud Portal, the Deploy API REST endpoints, and the Sitecore CLI with the SitecoreAI plugin. This post focuses exclusively on the CLI path. Whether you are wiring up a GitHub Actions workflow, an Azure DevOps pipeline, or scripting a repeatable release process, the commands below are your complete reference.

Content

• Authentication
• Project and Environment Hierarchy
• Key Deployment Commands
• Decoupled Deployments Explained
• Serialization and Publishing Workflow
• Important Notes

Authentication

Before any CLI command can talk to Sitecore Cloud, you need an authenticated session. There are two modes.

Interactive login (developer workstations)

Opens a browser-based login flow, ideal for local development:

dotnet sitecore cloud login

Non-interactive login (CI/CD pipelines)

Pass client credentials directly with no browser prompt. This is the right option for automated pipeline steps:

dotnet sitecore cloud login   --client-credentials   --client-id <your-client-id>   --client-secret <your-client-secret>

Permission requirement: The authenticating identity must hold the Organization Admin or Organization Owner role in the Sitecore Cloud Portal. Without it, project and environment creation commands will be rejected.

Project and Environment Hierarchy

SitecoreAI organizes resources in a three-level hierarchy: Project, Environment, and Deployment. Each level must exist before you can create the next.

Create a project

dotnet sitecore cloud project create -n <projectname>

The command returns the project-id you will need for the next step.

Create an environment

# Non-production environment
dotnet sitecore cloud environment create   --name <environment-name>   --project-id <project-id>   --cm-only

# Production environment - add --prod for SLA coverage
dotnet sitecore cloud environment create   --name <environment-name>   --project-id <project-id>   --cm-only   --prod

Note on --cm-only: This flag signals a CM-only authoring environment topology. Deployment architecture options have evolved with the January 2026 decoupled model, so always verify the exact flag behaviour against the CLI plugin version in your project, as options may differ across releases.

Key Deployment Commands

Authoring environment (CM) deployment

This is the primary command to deploy your XM Cloud authoring environment. The --upload flag packages and uploads your repository directly from the CLI:

dotnet sitecore cloud deployment create   --environment-id <environment-id>   --upload

Editing host deployment

From January 2026 onward, the editing host is deployed as a separate unit. This command targets the editing host component independently:

dotnet sitecore cloud editinghost deploy   --environment-id <environment-id>   --upload

Repository size limit: The maximum repository size for --upload deployments is 500 MB. Plan your build pipeline to stay under this threshold, or use the Deploy API with a pre-built artifact URL for larger repositories.

Retrieving logs

There are two separate log surfaces worth knowing about: runtime environment logs and deployment-specific logs. Both are accessible via the CLI without touching the portal.

To list available log files for an environment:

Since the decoupled model produces independent logs per component, you will want to check environment logs for CM runtime issues and deployment logs for build or provisioning failures separately.list -id <environment-id> --latest

To print a runtime-specific log file directly to the console:

dotnet sitecore cloud environment log view -id <environment-id> --log <log-file-name>

You can also download a log file to a local path instead, which may be helpful for the cases oа implementing a "log drain" feature:

dotnet sitecore cloud environment log download -id <environment-id> --log <log-file-name> -o <output-path>

For deployment-specific logs (useful when diagnosing a failed or stuck deployment), use the deployment log command:

dotnet sitecore cloud deployment log -id <deployment-id> -o <output-path>

Note: Since the decoupled model produces independent logs per component, you will want to check environment logs for CM runtime issues and deployment logs for build or provisioning failures separately.

Decoupled Deployments Explained

The recommended deployment model since January 2026 separates the CM authoring environment from the Editing Host. Each component is deployed independently using its own CLI command:

• Authoring (CM): cloud deployment create --upload
• Editing Host (EH): cloud editinghost deploy --upload

The practical benefits of this approach:

• Faster release cycles - deploy the CM without rebuilding the EH, and vice versa
• Independent rollback - revert one layer without touching the other
• Granular observability - each component produces its own deployment logs, making root-cause analysis faster
• Pipeline flexibility - CI/CD stages can be parallelised or gated independently per component

Serialization and Publishing Workflow

Code deployment covers the application layer. Content serialization and Edge publishing are separate steps that run after the environment is live.

Step 1: Push serialized content to the CM

Sync your Sitecore Content Serialization items into the target environment:

dotnet sitecore serialization push -n <environmentName>

Step 2: Publish to Experience Edge

Once content is in the CM, publish it to Experience Edge so your head application can consume the updated data:

dotnet sitecore publish --pt Edge -n <environmentName>

Important Notes

• Repository size limit: 500 MB maximum for CLI uploads via --upload.
• Auto-deploy option: DeployApp offers a "Trigger deployment on commit to branch" setting. For pure CLI pipelines, replicate this by calling deployment create from a git webhook or pipeline trigger.
• Required role: Organization Admin or Organization Owner in the Sitecore Cloud Portal is required for creating projects and environments.
• Decoupled model: CM and EH deployed separately is the recommended approach since January 2026. Favour this for all new projects.
• Plugin version: Always run dotnet sitecore --version to confirm your XM Cloud plugin is current. Flag behaviour such as --cm-only may differ across plugin releases.

Are you using CLI or DeployApp for your CI/CD pipeline? Share your setup in the comments below!

When a GitHub Repository Stops You in Your Tracks

There are moments in a developer's life when you stumble across something on GitHub and your immediate, instinctive reaction is: "Wait - this should already exist everywhere." That was precisely my reaction when I landed on the official Sitecore Labs repository for the Layout Container component for XM Cloud.

If you work with Sitecore XM Cloud and Headless SXA, you will recognize the pain almost instantly. Your content authors want freedom, they want to build rich, multi-column, responsive page layouts without raising a development ticket. Your developers want to deliver clean, maintainable frontend code without copy-pasting bespoke wrapper <div> hierarchies all over the codebase. Your architects want a composable, reusable structural primitive that the entire team can rally around. And yet, out of the box, the XM Cloud Starter Kit leaves you to solve all of that yourself.

Enter the Layout Container - a deceptively simple name for a component that carries enormous potential. Built and published by the Sitecore Labs team (the same group that maintains the xmcloud-foundation-head starter kit and other first-party accelerators), this single component quietly addresses one of the most common friction points in any Headless SXA project: how do you give content authors meaningful layout control without handing them a blank canvas and a prayer?

What makes it truly exciting is what I'd call its universality. Unlike a "Hero" or a "Promo" component - which solves one specific presentational problem - the Layout Container is infrastructure. It is the scaffolding upon which every other component lives. Its scope is not a feature; it is a fundamental authoring primitive, and discovering it tucked away in a labs repository rather than shipped as a platform default is both a delight and, as we'll discuss, a genuine head-scratcher.

Let's dig into what this component actually does and why it matters so much.

Inside the Codebase - What Makes the Layout Container "Universal"

The repository is refreshingly lean. Its footprint consists of a LayoutContainer.tsx React/TypeScript component, a dedicated SCSS stylesheet folder, and a set of Sitecore-serialized content items that wire everything together on the Content Management side. That austerity is intentional - this is a utility component, and utility components should not carry unnecessary weight. But don't let the simplicity fool you: the architectural thinking behind it is substantial.

The Sitecore Item Architecture

The Sitecore side of the component is serialized using the Sitecore CLI (dotnet sitecore ser push) and lives under the familiar Headless Experience Accelerator rendering path: /sitecore/layout/Renderings/Feature/Headless Experience Accelerator/Layout Container.

This placement is deliberate and telling. By living under the Feature layer of the HEA namespace, right alongside the out-of-the-box Page Content components - the Layout Container is explicitly designed to behave as a peer to first-party SXA components, not a bolted-on afterthought. It is enabled through the site's Available Renderings configuration under the Page Structure group, which is exactly where structural components belong. This tells content authors unambiguously: "This component organizes other components. It is not content itself."

The module definition (layoutcontainer.module.json) follows the standard Sitecore CLI module pattern, meaning it integrates cleanly with existing serialization workflows. There is no custom build step, no exotic dependency, and no configuration magic required - just a clean dotnet sitecore ser push -i LayoutContainer and you are live.

The React Component: Flexibility Through Parameters

The heart of the component is LayoutContainer.tsx, a Next.js/React component following the canonical Headless SXA pattern that every XM Cloud developer will recognize:

type LayoutContainerProps = {
  params: { [key: string]: string };
  fields?: { [key: string]: Field };
};

This signature is significant. The heavy lifting in this component happens through params - the rendering parameters, rather than through datasource fields. This is the correct architectural choice for a structural component. Layout decisions (column count, spacing, background color, alignment) are rendering concerns, not content concerns. Using params instead of a datasource means the Layout Container does not pollute the content tree with structural data items, keeping the authoring experience clean and the content model honest.

The component dynamically assembles its CSS class list by composing values from its rendering parameters - including the built-in GridParameters that Headless SXA passes to every component. This means it inherits the full grid vocabulary of the SXA grid system right out of the box, without needing to reinvent it.

SCSS Architecture - Responsive by Design

The SCSS module (layout-container/) follows the same BEM-influenced, SCSS-variable-driven conventions used in the XM Cloud Starter Kit, making it trivially easy to integrate with an existing project's design token system. Rather than hardcoding breakpoint values or pixel measurements, the styles are structured to compose with the host project's existing _variables.scss and _mixins.scss infrastructure.

More importantly, the CSS is structured around CSS Grid and Flexbox semantics, giving it the full power of the modern layout cascade. This means:

• Column configurations (halves, thirds, quarters, asymmetric splits) are expressed as CSS Grid template columns, which adapt naturally to content reflow.
• Vertical stacking on mobile is handled via media query breakpoints that collapse multi-column grids to a single-column layout - no JavaScript required, no layout shift.
• Gap/spacing control maps to CSS gap properties, keeping spacing consistent with the browser's natural rendering model.

The upshot is a component whose visual output is responsive, accessible, and performant - not because of clever JavaScript, but because it leans on what CSS is already brilliant at.

Component Nesting: The Real Superpower

If you've been reading this and thinking "okay, it's a grid wrapper - so what?" - this is the part that should change your mind.

The Layout Container is designed to be infinitely nestable, both with itself and with any other Sitecore component. In XM Cloud Pages, because it appears in the Page Structure available renderings group, it can be dropped onto a page as a top-level structural element. But critically, it can also be placed inside another Layout Container, creating a recursive composition model that is genuinely rare in out-of-the-box Sitecore experiences.

Consider some concrete scenarios where this nesting capability becomes indispensable:

Scenario A: The Marketing Landing Page. A content author building a campaign page might want a full-width hero at the top, then a three-column content row (icons + text), then a two-column row (image left, rich text right), then a full-width CTA strip. Without the Layout Container, this requires a developer to hardcode multiple distinct page template zones or create bespoke wrapper components. With it, the author drops Layout Containers like building blocks - no development ticket required.

Scenario B: The Card Grid Within a Tab. A developer has built a Tabs component. Inside each tab, a content author wants to place a 2×3 grid of Card components. Without a nestable layout primitive, the developer either has to bake the grid logic into the Tabs component (coupling concerns that should be separate) or accept that the tab body is a single linear column. With the Layout Container nested inside the tab's placeholder, the author gets the grid; the developer keeps a clean separation of concerns.

Scenario C: Asymmetric Editorial Layouts. A content team building a magazine-style article page wants a wide left column for body text and a narrow right column for a related-links sidebar, with the sidebar itself containing a small two-column author bio grid. This is a nested grid - a layout inside a layout inside a layout. Without a universal container, you either write it in code (slow, inflexible) or you don't do it at all (bad for editors). With the Layout Container, the author assembles it themselves in Pages, live, without a deployment.

This nesting behavior is not merely a developer convenience - it is a fundamental empowerment of the content author role, and it is one of the clearest indicators that whoever designed this component understood the day-to-day reality of editorial workflows.

Configuration Options - What Authors Can Control

Based on the component's architecture and the Headless SXA rendering parameters pattern, the Layout Container exposes a meaningful set of authoring controls in XM Cloud Pages:

Grid Parameters inherit from the SXA grid system, allowing authors to choose how the container spans the page grid (full width, contained, offset columns). This is the same parameter available on every SXA component, so authors already know how to use it.

Custom CSS Classes / Styles can be passed as additional rendering parameters, enabling developers to pre-define named variants (e.g., "layout--highlight-band", "layout--dark-bg") that authors can select without touching code. This is the Headless SXA variant pattern applied at the structural level.

Column Count and Layout Mode parameters map to specific CSS Grid configurations in the SCSS module, letting authors switch between common layouts (equal columns, sidebar-left, sidebar-right, masonry-ready) through a simple dropdown in Pages - no CSS knowledge required.

Spacing Controls allow authors to add or remove padding between the container and its children, supporting the common design system requirement of consistent whitespace tokens (e.g., spacing-sm, spacing-md, spacing-lg).

The beauty of the params-based approach is that developers define the vocabulary (which class names and configurations are valid) while authors make the choices within that vocabulary. It strikes the precise balance between control and guardrails that every enterprise DXP project demands.

Reusability, Extensibility, and the Development Workflow

From a developer's perspective, the Layout Container represents a philosophy shift in how Headless SXA projects should be structured. Instead of building N bespoke two-column, three-column, or asymmetric-layout components - each with its own rendering definition, datasource template, and SCSS file - you build one structural primitive and compose everything else on top of it.

This has a profound effect on the development lifecycle:

• Onboarding time drops. New developers on the project only need to learn one layout abstraction, not a proliferating zoo of structural wrapper components.
• QA scope shrinks. One well-tested Layout Container component, rather than a dozen layout variants, means fewer regression paths when the design system updates.
• Extending it is trivial. Want to add a new layout variant (say, a five-column grid for a data dashboard)? Add a CSS class to the SCSS module, add the parameter value to the rendering parameters template in Sitecore, and the new layout is immediately available to content authors. The component code itself does not change.
• Designers and developers speak the same language. When the layout vocabulary is codified in a single component's parameter schema, design token changes and grid system updates have a single, clear, authoritative integration point.

Content authors, meanwhile, gain something that is often underestimated in its value: the confidence to experiment. When a layout is a drag-and-drop combination of Layout Containers and components rather than a hardcoded template, authors can try different page structures, get feedback from stakeholders, and iterate - all without waiting for a sprint cycle.

The Big Question - Why Isn't This Already in the Base Image?

Let's step back and state what should, by now, be obvious: the Layout Container component solves a universal problem. Not a vertical-specific problem. Not a "large enterprise only" problem. Not a "nice to have for power users" problem. Every single Headless SXA project built on XM Cloud needs a way for content authors to compose multi-column, responsive page layouts without developer intervention. Every. Single. One.

Which makes the central question of this post genuinely difficult to dismiss: Why is this component not shipped as a standard part of the XM Cloud Headless SXA base image?

The Starter Kit (xmcloud-foundation-head) ships with a solid collection of baseline components - Rich Text, Image, Promo, Navigation, Container, and others. These give teams a running start with content-level components. But the Layout Container - a structural primitive that sits one level of abstraction above all of those - is absent. Teams that don't discover this Labs repository must either build their own (reinventing the wheel, probably with less polish) or ship projects where content authors are constrained to the column structures that developers hardcoded during the initial build.

Consider the cumulative cost of that gap across the Sitecore partner and customer ecosystem. Every implementation team that has ever built a bespoke "TwoColumnLayout.tsx" or "SidebarWrapper.tsx" component - which is almost certainly every implementation team - has spent time solving a problem that this component already solves cleanly and correctly. That is not just redundant effort; it is inconsistent effort, producing different quality levels, different authoring experiences, and different maintenance burdens across the ecosystem.

There is also an onboarding and adoption story to consider. XM Cloud's pitch to new customers and partners includes the power of XM Cloud Pages and the visual, drag-and-drop composability of Headless SXA. But that pitch rings hollow if the first thing an author discovers is that they cannot create a two-column layout without filing a ticket. Including the Layout Container in the base image would make the out-of-the-box authoring experience substantially more compelling - not just for power users, but for day-one evaluators.

To be clear: the Sitecore Labs team deserves real credit for building this and publishing it openly. Making it available as a discoverable Labs component is genuinely better than not having it at all, and the quality of the implementation reflects careful thinking about how it should work within the Sitecore ecosystem. The installation guide is clear, the integration path is clean, and the component follows all the right conventions.

But "discoverable if you know to look for it" is a fundamentally different value proposition than "available by default." The former relies on developers reading the right blog posts (like this one, perhaps!), attending the right community sessions, or being lucky enough to have a colleague who found it first. The latter means every XM Cloud customer gets the benefit from day one - regardless of their implementation partner's GitHub browsing habits.

If the hesitation is about keeping the base image lean and avoiding "bloat," that concern is understandable but worth challenging. The Layout Container is not an opinionated business component - it carries no brand, no domain logic, and no content model assumptions. It is as unopinionated as a <div>. It is infrastructure. And infrastructure belongs in the foundation, not in a labs addendum.

If the hesitation is about support scope - that adding more components to the base increases the surface area Sitecore must maintain - then perhaps the answer is a tiered model: a curated "recommended additions" bundle that partners and customers can opt into during project setup, with the Layout Container as its flagship entry.

Whatever the path, the status quo is leaving value on the table. Every XM Cloud project that ships without this component, or ships with a lesser hand-rolled substitute, is a reminder of a gap that Sitecore Labs has already, quietly, filled. It's time to bring it in from the cold.

Have you considered integrating the Layout Container into your SitecoreAI project? Drop a comment below or reach out on the Sitecore Community Slack - I'd love to hear how your team has extended it, what rendering parameter configurations you've found most useful, and whether you've hit any edge cases with deep nesting in XM Cloud Pages. And if you haven't explored it yet, the GitHub repository is the place to start - your content authors will thank you for it.

Every year I create a special Christmas postcard to congratulate my readers on a new oncoming year, full of changes and opportunities. Wish you all the best in 2026!

The Sitecore MVP program recognizes individuals who have demonstrated advanced knowledge of the Sitecore platform and a commitment to sharing knowledge and technical expertise with community partners, customers, and prospects over the past year. The program is open to anyone passionate about Sitecore and eager to contribute to the community.

Over the past application year, starting from December 1st, 2024, I have been actively involved in the Sitecore community, contributing in a number of ways.

Sitecore Symposium 2025 Presentation

Together with Vasiliy Fomichev, we led a very insightful 50-minute workshop on building agentic copilots for Sitecore, during which Vasiliy provided the full theoretical foundation for the topic. I took it from there with a practical, hands-on demo of what it takes to make one from zero to the actual work, essentially giving the step-by-step instructions one could reproduce to get this done in under an hour. 

My demo showcased the effort and key decisions required to build a Microsoft Teams copilot, enabling marketers to perform specific operations (mass rebranding in our case, but could be anything) in the fastest, safest way. 

The whole chain looks as follows:

    Ms Teams ==> Teams Bot ==> LLM ==> Custom MCP Server ==> PowerShell ==> SPE (and the same reverse way back)

Recordings are available:

• My practical demo recording
• Full session recording (from my phone)

Agentic AI Challenge

Thrilled to be recognized as a Top 2nd Finalist in the Sitecore AI Challenge out of 150 submissions globally!

The AI Visibility app I've built will help SitecoreAI XM Cloud clients optimize their websites for AI within minutes. Like Michelle Boockoff-Bajdek mentioned, it's sometimes surprising to learn the fundamental questions people ask about your brand. Our app takes the guesswork out of AI optimization and helps Sitecore users gain a competitive advantage in digital. 

The app is now being reworked (implementing all the recent changes released after Sym) for review to join the public SitecoreAI Marketplace.

Awarding ceremony recording.

Sitecore Blogs 

This year, I have written 24 blog posts on various topics related to Sitecore, top-notch findings about XM Cloud and other composable products, best practices, tips and tricks, and case studies:

• Sitecore PowerShell working from a SitecoreAI Marketplace app
• Case Study: Search Solutions Comparison for Sitecore XM Cloud Migration
• The Game Has Changed: Sitecore AI and the Dawn of the Agentic Era
• Sitecore Content SDK 1.2 brings App Router into XM Cloud
• The new and shiny Sitecore Marketplace
• Auto-migrating any Sitecore XP website to XM Cloud is actually possible!
• Top 10 Mistakes Organizations Make on Sitecore XM Cloud Implementations
• Resolving broken images issue on XM Cloud starter kit running in local containers
• Changing item ID in XM Cloud from the item's context menu
• Dictionary in XM Cloud
• Using these XM Cloud hotkeys can significantly boost your productivity
• Using Sitecore Pipeline Profiler
• XM Cloud productivity tip: Use Cloud Portal Auto Login extension for Chrome
• SUGCON Europe 2025 Takeaways
• XM Cloud: Beyond the Serialization
• XM Cloud Headless Endpoints - Local vs Cloud vs Preview
• Sitecore XP vs XM Cloud full guide: which one to choose in 2025
• Compliance and Geographic Hosting Considerations for Sitecore XM/XP vs XM Cloud
• Redirects in Sitecore XM Cloud - know your options!
• SQL-level access to the database in XM Cloud
• All you need to know about transforming Web.config on Sitecore XM Cloud
• Rendering Parameters vs. Rendering Variants - when should we use one or another
• Experience Edge: Know Your Limitations
• Sitemaps in Sitecore XM Cloud: Automation, Customization, and SEO Best Practices

YouTube Videos

I have reverse-engineered the Sitecore PowerShell Extension and reassembled it into a SitecoreAI Marketplace app!

This PoC is essentially a blueprint app. On its own, it is a universally working example. Still, its real benefit comes from this app providing a ready-to-use boilerplate that can be reused to build a variety of specialized SitecoreAI Marketplace apps on top of the SPE approach.

The most awesome feature is that all of your Marketplace context values could be easily passed into a remotely executed PowerShell script as a script parameter: there is a convenient Script Parameters mapping with maramater token preview (so that you never miss the right value!)

Here's what it looks like:

To enable SPE with Remoting:

1. From SitecoreAI Deploy, add SPE_REMOTING_SECRET environmental CM secret, then re-deploy.
2. Install a package, which will enable SPE with Remoting: SPE_with_Remoting.zip (3.93 kb)
3. This package also adds a disabled sitecore\speremoting user with admin rights, which you must enable manually from User Manager

Once this setup is complete, the environment is fully prepared to use the app. The Marketplace app supports multitenancy; however, SPE Remoting must be enabled individually for every environment you intend to work with.

1. Introduction

This case study presents a high-level comparison of four leading search solutions - Coveo, Sitecore Search, Algolia, and SearchStax - for a Benelux-based financial organization considering a migration to Sitecore AI. The analysis focuses on licensing costs, implementation effort, potential hidden fees, technical limitations, and the availability of React-based frontend SDKs for each platform. The goal is to provide the necessary information to enable an informed decision on whether to migrate from Sitecore XP and to determine which solution best suits the organization's needs and budget.

The website has the following traffic characteristics, taken into consideration:

• Annual Traffic: ~700K sessions in 2024 and ~850K sessions in 2023.
• Components: ~160 unique components.
• Budget Expectations: under to €10K for a “composable” (external) search provider

Section 4 of this document contains the conclusion and the considered recommendation based on the balance of individual organizations’ parameters.

2. Executive Summary

The following table provides a high-level comparison of the four search solutions:

3. Detailed Analysis

3.1. Coveo

Coveo is a powerful, AI-driven enterprise search platform that offers advanced personalization and relevance tuning capabilities. It is a mature product with a strong presence in the Sitecore ecosystem, well-suited for large organizations with complex search requirements.

Licensing and Cost

Coveo's pricing is geared towards enterprise clients and is generally the highest of the four options. The pricing model is based on a combination of query volume and the number of indexed items, with subscriptions typically sold on an annual or multi-year basis.

• Coveo for Sitecore Plans: The Pro+ plan starts at 200,000 queries per month, while the Enterprise+ plan starts at 300,000 queries per month and offers volume-based pricing. Given the client's traffic, they would likely fall into the lower tiers of these plans.
• Implementation Cost: A typical enterprise-level deployment, including licensing and professional services, can range from $50,000 to over $100,000 USD. This does not include ongoing maintenance or support costs.
• Hidden Fees: Additional costs can arise from add-on features such as Generative AI, advanced security, and dedicated technical support. Overages on query limits are handled through a discussion with a customer manager rather than automatic charges, providing some flexibility but also potential for unexpected cost increases.

Implementation Effort

Coveo's integration with Sitecore is well-documented and mature, but it is not a simple plug-and-play solution. The platform's power and flexibility come at the cost of increased complexity.

• Complexity: Coveo has a steep learning curve and often requires dedicated developer time to configure even moderately complex use cases.
• Expertise: Successful implementation typically requires specialized knowledge of the Coveo platform, and many organizations opt for professional services from Coveo or a certified partner.
• Time to Value: The complexity of configuration and optimization can lead to a longer implementation timeline compared to other solutions.

React SDK and Frontend Components

Coveo provides a comprehensive set of tools for building modern search UIs with React.

• Coveo Atomic React (@coveo/atomic-react): A React wrapper around the core atomic web component library, providing a rich set of components for building search interfaces.
• Plasma Design System: A React-based design system used in the Coveo Cloud Administration Console, which can be leveraged for a consistent look and feel.

Technical Limitations

While powerful, Coveo does have its limitations.

• File Size: The maximum size for a single indexed item is approximately 256 MB, which includes metadata and permissions.
• Configuration Complexity: The platform's extensive features can be difficult to manage, and the documentation is sometimes considered vague or incomplete.
• Cost at Scale: Although the client's current traffic is low, a significant increase in search queries or indexed content could result in substantial cost increases.

3.2. Sitecore Search

Sitecore Search is the native search solution for the Sitecore ecosystem, designed to provide a seamless and integrated experience. It is an AI-powered, headless platform that focuses on delivering personalized and predictive search results.

Licensing and Cost

Detailed pricing for Sitecore Search is not publicly available and requires a direct quote from Sitecore. However, it is often bundled as part of the unified SitecoreAI (ex. XM Cloud) offering, which can make it a cost-effective option for organizations already invested in the Sitecore ecosystem.

• Pricing Model: The cost is likely tied to the overall Sitecore contract and may not be broken down as a separate line item. This can simplify budgeting, but also makes it difficult to compare directly with other solutions.
• Implementation Cost: As a native solution, the initial setup is generally more straightforward than third-party integrations. However, customization and optimization will still require development effort.
• Hidden Fees: Potential hidden costs could arise if the bundled search capacity is exceeded.

Implementation Effort

Sitecore Search is designed for seamless integration with XM Cloud, which should reduce the initial implementation effort compared to third-party solutions.

• Native Integration: The platform is designed to seamlessly integrate with Sitecore's content models and personalization features, streamlining the integration process.
• Developer Expertise: Implementation can typically be handled by developers with standard Sitecore expertise, without requiring specialized third-party knowledge.
• Time to Value: Native integration and a familiar development environment can lead to a faster time to value for most projects.

React SDK and Frontend Components

Sitecore provides a native and well-supported React SDK for building search experiences.

• Sitecore Search JS SDK for React: A dedicated SDK that allows developers to quickly integrate search experiences into React applications. It includes a full set of UI components and a starter kit to accelerate development.

Technical Limitations

As a relatively new product, Sitecore Search has some limitations and operational challenges that need to be considered.

• Indexing Delays: Crawling content from multiple sites with a single source can lead to prolonged indexing times, sometimes exceeding an hour. This can be a significant issue for time-sensitive content.
• Scalability: For large, multi-site implementations, it is recommended to create separate sources for each site to improve indexing efficiency. This adds a layer of management complexity.
• Real-Time Updates: The platform currently relies on full crawls for index updates, and there is a lack of a "Push API" for immediate, incremental updates. This can result in a delay of several minutes for new content to appear in search results.

3.3. Algolia

Algolia is a developer-focused search-as-a-service platform known for its speed and real-time capabilities. It provides a flexible and powerful set of APIs that enable the creation of fast and responsive search experiences.

Licensing and Cost

Algolia's pricing is transparent and based on a pay-as-you-go model, making it very cost-effective for organizations with low to moderate search traffic. For the client's current traffic levels, the costs would be minimal.

• Pricing Model: The Grow and Grow Plus plans offer a free tier of 10,000 search requests per month, with additional requests billed at a low rate of $1,000 per 1,000 requests. The number of records (~350 pages) is well within the free tier of 100,000 records.
• Cost Estimate: Based on the client's average annual traffic of ~775,000 sessions, the estimated annual licensing cost for Algolia would be between $17 and $197 USD, depending on the plan and the actual search rate.
• Hidden Fees: The primary "hidden" cost with Algolia is the implementation effort, as there is no native Sitecore connector. While the licensing is inexpensive at this scale, a significant increase in traffic or a move to the enterprise Elevate plan could result in substantial cost increases, with average enterprise plans costing around $350,000 annually.

Implementation Effort

While Algolia is known for its developer-friendly APIs, the lack of a native Sitecore connector means that integration requires custom development.

• Custom Integration: Implementing Algolia with Sitecore requires building a custom integration to index content and create the search interface. This can be a time-consuming and expensive process.
• Third-Party Connectors: Third-party connectors are available, such as the "Algolia Index Builder for Sitecore" by Brimit, which can simplify the integration process. However, these connectors may come with their own licensing costs and support limitations.
• Developer Expertise: The implementation requires developers with experience in both Sitecore and API-based integrations.

React SDK and Frontend Components

Algolia offers an actively maintained open-source React library.

• React InstantSearch (react-instantsearch): A comprehensive library that lets developers create an instant search result experience with a rich set of pre-built widgets. It is highly performant and customizable.

Technical Limitations

Algolia's focus on speed and simplicity comes with some trade-offs.

• Manual Tuning: Achieving high search relevance often requires manual tuning and configuration of the search algorithm.
• eCommerce Features: While it can be used for e-commerce, it has limited specialized features compared to platforms like Coveo.
• Indexation Time: Some users have reported that indexation time can be a factor that impacts user experience, particularly for large and complex datasets.

3.4. SearchStax

SearchStax offers both a fully managed site search solution (Site Search) and a managed Apache Solr hosting service (Managed Search). For a Sitecore XM Cloud implementation, the Site Search product is the most relevant, as it is designed to integrate directly with modern, headless architectures.

Licensing and Cost

SearchStax Site Search pricing is based on a tiered subscription model, with the entry-level Essential plan starting at $799 per month (billed annually).

• Pricing Model: The plans scale based on the number of indexed items, monthly searches, and advanced features. The Advanced and Premium plans require a custom quote.
• Implementation Cost: The cost of implementation is moderate, as SearchStax provides a dedicated Sitecore module and UI kits to accelerate development.
• Hidden Fees: Additional costs could arise from overages on search requests or indexed items, or from the need for advanced security and support add-ons available with the Managed Search product.

Implementation Effort

SearchStax has invested in creating a smooth integration experience for Sitecore users, including those on XM Cloud.

• Sitecore Integration: SearchStax offers a dedicated module for Sitecore, which connects directly to the Site Search solution, as well as connectors for their Managed Search product.
• Developer Expertise: The availability of UI kits and pre-built components reduces the required level of specialized expertise, allowing developers with standard React and Sitecore knowledge to implement the solution effectively.
• Time to Value: The combination of a dedicated Sitecore module and React UI kits can significantly accelerate the development process and reduce the time to value.

React SDK and Frontend Components

SearchStax provides a comprehensive set of tools for building search interfaces with React.

• Search UI Kits: SearchStax offers UI kits for JavaScript, Vue, Angular, and React/Next.js, which include pre-built components to streamline the development of the search UI.

Technical Limitations

SearchStax has some service limits in place to ensure stability and performance.

• API and Document Limits: There are limits on API requests per second (20+), document size (100KB), and payload size (10MB).
• Feature Limits: There are also limits on the number of facet values (50), promoted items (10), and other features.
• User-Reported Issues: Some users have reported that the platform can be expensive and that there are limitations on the number of search results that can be displayed per category.

4. Conclusion and Recommendations

Each of the four search solutions offers a viable path for a Sitecore XM Cloud migration, but they cater to different priorities and budgets. The availability of React-based SDKs and component libraries from all four vendors is a significant advantage, as it simplifies the development of the front-end search experience.

1. Coveo remains the top-tier enterprise solution, offering the most advanced AI and personalization features. Its high cost is justified by its power and its proven track record in the financial services industry.
2. Sitecore Search provides the tightest integration with the SitecoreAI ecosystem, which can lead to a more streamlined implementation and a unified user experience.
3. Algolia is the most budget-friendly option for the client's current traffic, but the lack of a native Sitecore connector and some basic features introduces significant implementation risk and long-term maintenance overhead.
4. SearchStax presents a compelling middle ground. It offers a robust, AI-powered search solution with a clear integration path for Sitecore XM Cloud and a more accessible price point than Coveo. Its managed Solr foundation provides a high degree of security and reliability.

Recommendations

1. Primary Recommendation: Sitecore Search.It should be considered a seamless, all-in-one solution from a single vendor, thus natively fits in the product space. A thorough proof of concept is essential to validate that its performance and scalability meet the client's needs. Native integration and the presence of the best-breed front-end components make this choice the best balance among these platforms. It totally fits the aligned budget. Additionally, it features AI personalization capabilities and operates within the newly created Unified Data, alongside XM Cloud (for tracking, analytics, personalization, and more).
2. For a financial institution that prioritizes a premium, secure, and highly personalized user experience, Coveo could be a recommended solution. Its enterprise-grade features and strong compliance posture are well-suited to the needs of the financial services industry. However, due to budget concerns, Coveo is not a suitable option. Coveo's minimal tier times exceed the organization’s desired budget range.
3. Strong Alternative: SearchStax.If the cost of Coveo is a significant barrier, SearchStax is a strong alternative. It provides a powerful, AI-driven search experience with a supported integration path for Sitecore XM Cloud. Its balance of features, cost, and ease of implementation makes it a very attractive option. However, despite being a budget option, the total cost of ownership can often be higher compared with Sitecore Search and Algolia.
4. Budget-Constrained Option: Algolia.Algolia should only be considered if the budget is the primary driver, and the organization has a strong in-house development team to manage custom integration. The long-term total cost of ownership may be higher than the initial licensing fees suggest.

The choice between Sitecore Search and SearchStax will likely come down to a trade-off between the advanced, integrated features of the native Sitecore product and yet still powerful solution offered by SearchStax.

5. References

• Coveo Pricing
• Coveo for Sitecore Pricing
• Why Use Coveo Enterprise Search Software
• Coveo Platform Limits
• Coveo File Size Limit
• Sitecore Search Pricing on TrustRadius
• Sitecore Search Accelerate Cookbook
• Addressing Operational Challenges in Sitecore Search
• Algolia Pricing
• Algolia Pricing: Is it Worth The Money?
• Comparing All The Options For Website Search in Sitecore
• Algolia Index Builder for Sitecore by Brimit
• Algolia Alternatives
• Why we churned from Algolia
• Coveo Atomic React Wrapper
• Coveo Plasma Components
• Sitecore Search JS SDK for React
• Sitecore Search JS SDK Starter Kit
• Algolia React InstantSearch
• SearchStax Site Search Pricing
• SearchStax Managed Search Pricing
• SearchStax Sitecore Module
• Building Sitecore Search with SearchStax Search UI Components
• SearchStax Site Search Service Limits
• SearchStax Reviews on G2