Walkthrough: Adding the SXA module

Version: 10.1

Sitecore Experience Accelerator (SXA) is a Sitecore module developed to speed up the production of websites and to reuse components, layouts, and templates across a variety of sites. To add the SXA module, you must create specific Docker images and push them to the Azure Container Registry (ACR) and then change them in the Application repository before running the SearchStax Solr and Mssql containers.

This walkthrough describes how to:

Prepare the Docker images
Push the images to the ACR
Change the images in the Application repository
Run the Searchstax-solr-init-sxa-spe-container:
- Without disaster recovery.
- With disaster recovery.
Run the Mssql-init-sxa-spe container:
- Without disaster recovery.
- With disaster recovery.

Prepare the Docker images

Refer to the Add Sitecore modules topic to learn how to create a custom SXA module.

To be able to work with SXA, you must create the following images:

cm-sxa-spe
cd-sxa-spe
Mssql-init-sxa-spe
Searchstax-solr-init-sxa-spe

Note

When you build the solr-init image for sxa, ensure that the base image is designed for use with Searchstax. In the Sitecore image repository, these images have tags that end with -searchstax, for example, sitecore-xp1-solr-init-searchstax.

Push the images to the Azure Container Registry

To push the images to the ACR:

In PowerShell, execute the docker push command. You must push all images to the pre-provisioned ACR: {infrastructure_id}acr

Change the images in the Application repository

Now you can add the SXA-specific naming and the two new properties to the Application repository.

To change the images in the Application repository:

Navigate to the Application repository config/docker-images and edit docker-images.json as follows:
- Replace the cm image with cm-sxa-spe.
- Replace the cd image with cd-sxa-spe.
- Add the Mssql-init-sxa-spe property.
- Add the Searchstax-solr-init-sxa-spe property.

Run the Searchstax-solr-init-sxa-spe container without disaster recovery

To run the Searchstax-solr-init-sxa-spe container:

Navigate to roles\sitecore-{topology}\templates\ and add the Searchstax-solr-init-sxa-spe job file under the name: searchstax-solr-init-sxa-spe.yaml. For example:

RequestResponse

---
apiVersion: batch/v1
kind: Job
metadata:
  name: searchstax-solr-init-sxa-spe
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/os: windows
      imagePullSecrets:
        - name: sitecore-docker-registry
      initContainers:
      - name: wait-solr
        image: "{{ docker_images.external.windowsservercore }}"
        command: ["pwsh"]
        args: ["-Command", "do { Start-Sleep -Seconds 3 } until ((tnc $env:SERVER -port $env:PORT).TcpTestSucceeded)"]
        env:
        - name: SERVER
          value: "{{ solr_fqdn }}"
        - name: PORT
          value: "{{ solr_port }}"
      containers:
      - name: solr-init
        image: "{{ docker_images.sitecore.solr_init_sxa_spe }}"
        env:
          - name: SEARCH_STAX_APIKEY
            valueFrom:
              secretKeyRef:
                name: sitecore-solr-searchstax
                key: sitecore-searchstax-apikey.txt
          - name: SEARCH_STAX_ACCOUNT_NAME
            valueFrom:
              secretKeyRef:
                name: sitecore-solr-searchstax
                key: sitecore-searchstax-account-name.txt
          - name: SEARCH_STAX_DEPLOYMENT_UID
            valueFrom:
              secretKeyRef:
                name: sitecore-solr-searchstax
                key: sitecore-searchstax-deployment-uid.txt
          - name: SITECORE_SOLR_CONNECTION_STRING
            valueFrom:
              secretKeyRef:
                name: sitecore-solr
                key: sitecore-solr-connection-string.txt
          - name: SOLR_CORE_PREFIX_NAME
            value: sitecore
          - name: SOLR_COLLECTIONS_TO_DEPLOY
            value: sxa
      restartPolicy: Never
  backoffLimit: 5

To add the Ansible tasks to run the Searchstax-solr-init-sxa-spe job, go to roles\sitecore-{topology}\tasks\init.yaml and add the following scripts at the end of the file:

RequestResponse

- name: Execute sxa-spe solr-init job
  k8s:
    apply: true
    namespace: "{{ solution_id }}"
    state: present
    definition: "{{ lookup('template', 'searchstax-solr-init-sxa-spe.yaml') }}"

- name: 'Wait - SXA-SPE Solr-init job'
  k8s_info:
    kind: Job
    name: searchstax-solr-init-sxa-spe
    namespace: "{{ solution_id }}"
  register: sxa_spe_solr_init_result
  until: (sxa_spe_solr_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
  retries: 60
  delay: 60

- name: Get all SXA-SPE Solr completed pods
  k8s_info:
    kind: Pod
    namespace: "{{ solution_id }}"
    label_selectors:
      - job-name = searchstax-solr-init-sxa-spe
  no_log: true
  register: solr_sxa_spe_pod_list

- name: Remove SXA-SPE Solr job's pods
  k8s:
    kind: Pod
    name: "{{ item.metadata.name }}"
    namespace: "{{ solution_id }}"
    state: absent
  no_log: true
  with_items: "{{ solr_sxa_spe_pod_list.resources }}"

Run the application pipeline.

Run the Searchstax-solr-init-sxa-spe container with disaster recovery

To run the Searchstax-solr-init-sxa-spe container:

Navigate to roles\sitecore-{topology}\templates\ and add the Searchstax-solr-init-sxa-spe job file under the name: searchstax-solr-init-sxa-spe.yaml. For example:

RequestResponse

---
apiVersion: batch/v1
kind: Job
metadata:
  name: searchstax-solr-init-sxa-spe
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/os: windows
      imagePullSecrets:
        - name: sitecore-docker-registry
      initContainers:
      - name: wait-solr
        image: "{{ docker_images.external.windowsservercore }}"
        command: ["pwsh"]
        args: ["-Command", "do { Start-Sleep -Seconds 3 } until ((tnc $env:SERVER -port $env:PORT).TcpTestSucceeded)"]
        env:
        - name: SERVER
          value: "{{ solr_fqdn }}"
        - name: PORT
          value: "{{ solr_port }}"
      containers:
      - name: solr-init
        image: "{{ docker_images.sitecore.solr_init_sxa_spe }}"
        env:
          - name: SEARCH_STAX_APIKEY
            valueFrom:
              secretKeyRef:
                name: sitecore-solr-searchstax
                key: sitecore-searchstax-apikey.txt
          - name: SEARCH_STAX_ACCOUNT_NAME
            valueFrom:
              secretKeyRef:
                name: sitecore-solr-searchstax
                key: sitecore-searchstax-account-name.txt
          - name: SEARCH_STAX_DEPLOYMENT_UID
            valueFrom:
              secretKeyRef:
                name: sitecore-solr-searchstax
                key: sitecore-searchstax-deployment-uid.txt
          - name: SITECORE_SOLR_CONNECTION_STRING
            valueFrom:
              secretKeyRef:
                name: sitecore-solr
                key: sitecore-solr-connection-string.txt
          - name: SOLR_CORE_PREFIX_NAME
            value: sitecore
          - name: SOLR_COLLECTIONS_TO_DEPLOY
            value: sxa
      restartPolicy: Never
  backoffLimit: 5

Create a custom init.yaml file, for example custom-init.yaml, and put it under the following folder: /roles/sitecore-{topology}/tasks.

To add the Searchstax-solr-init-sxa-spe job, add the following stripts to the file:

RequestResponse

- name: Execute sxa-spe solr-init job
  k8s:
    apply: true
    namespace: "{{ solution_id }}"
    state: present
    definition: "{{ lookup('template', 'searchstax-solr-init-sxa-spe.yaml') }}"

- name: 'Wait - SXA-SPE Solr-init job'
  k8s_info:
    kind: Job
    name: searchstax-solr-init-sxa-spe
    namespace: "{{ solution_id }}"
  register: sxa_spe_solr_init_result
  until: (sxa_spe_solr_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
  retries: 60
  delay: 60

- name: Get all SXA-SPE Solr completed pods
  k8s_info:
    kind: Pod
    namespace: "{{ solution_id }}"
    label_selectors:
      - job-name = searchstax-solr-init-sxa-spe
  no_log: true
  register: solr_sxa_spe_pod_list

- name: Remove SXA-SPE Solr job's pods
  k8s:
    kind: Pod
    name: "{{ item.metadata.name }}"
    namespace: "{{ solution_id }}"
    state: absent
  no_log: true
  with_items: "{{ solr_sxa_spe_pod_list.resources }}"

To call the custom init.yaml file, go to /roles/sitecore-{topology}/tasks/main.yaml and add the following code at the end of the file:
RequestResponse
```
- name: Execute custom init jobs 
  include_tasks: custom-init.yaml
```
Run the application pipeline.
If the custom job has been successfully created, comment out the Execute custom init jobs role.

Run the Mssql-init-sxa-spe container without disaster recovery

To run the Mssql-init-sxa-spe container:

Navigate to roles\sitecore-{topology}\templates\ and add the mssql-init-sxa-spe job file under the name: mssql-init-sxa-spe.yaml. For example:

RequestResponse

apiVersion: batch/v1
kind: Job
metadata:
 name: sxa-spe-mssql-init
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/os: windows
      imagePullSecrets:
        - name: sitecore-docker-registry
      containers:
      - name: mssql-init
        image: "{{ docker_images.sitecore.mssql_init_sxa_spe }}"
        env:
        - name: sitecore_admin_password
          valueFrom:
            secretKeyRef:
              name: sitecore-admin
              key: sitecore-adminpassword.txt
        - name: SQL_ADMIN_PASSWORD
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-databasepassword.txt
        - name: SQL_ADMIN_LOGIN
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-databaseusername.txt
        - name: SQL_SERVER
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-databaseservername.txt
        - name: SQL_ELASTIC_POOL_NAME
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-database-elastic-pool-name.txt
        - name: DATABASES_TO_DEPLOY
          value: spe,sxa
      restartPolicy: Never
  backoffLimit: 5

To add the Ansible tasks to run the mssql-init-sxa-spe job, go to roles\sitecore-{topology}\tasks\init.yaml and add the following scripts at the end of the file:

RequestResponse

- name: Execute sxa-spe mssql-init jobs
  k8s:
    apply: true
    namespace: "{{ solution_id }}"
    state: present
    definition: "{{ lookup('template', 'mssql-init-sxa-spe.yaml') }}"

- name: 'Wait - SXA-SPE Mssql-init job'
  k8s_info:
    kind: Job
    name: sxa-spe-mssql-init
    namespace: "{{ solution_id }}"
  register: sxa_spe_mssql_init_result
  until: (sxa_spe_mssql_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
  retries: 60
  delay: 60

- name: Get all SXA-SPE Mssql completed pods
  k8s_info:
    kind: Pod
    namespace: "{{ solution_id }}"
    label_selectors:
      - job-name = sxa-spe-mssql-init
  no_log: true
  register: sxa_spe_mssql_pod_list

- name: Remove SXA-SPE Mssql job's pods
  k8s:
    kind: Pod
    name: "{{ item.metadata.name }}"
    namespace: "{{ solution_id }}"
    state: absent
  no_log: true
  with_items: "{{ sxa_spe_mssql_pod_list.resources }}"

Run the application pipeline.

Run the Mssql-init-sxa-spe container with disaster recovery

To run the Mssql-init-sxa-spe container:

Navigate to roles\sitecore-{topology}\templates\ and add the mssql-init-sxa-spe job file under the name: mssql-init-sxa-spe.yaml. For example:

RequestResponse

apiVersion: batch/v1
kind: Job
metadata:
 name: sxa-spe-mssql-init
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/os: windows
      imagePullSecrets:
        - name: sitecore-docker-registry
      containers:
      - name: mssql-init
        image: "{{ docker_images.sitecore.mssql_init_sxa_spe }}"
        env:
        - name: sitecore_admin_password
          valueFrom:
            secretKeyRef:
              name: sitecore-admin
              key: sitecore-adminpassword.txt
        - name: SQL_ADMIN_PASSWORD
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-databasepassword.txt
        - name: SQL_ADMIN_LOGIN
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-databaseusername.txt
        - name: SQL_SERVER
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-databaseservername.txt
        - name: SQL_ELASTIC_POOL_NAME
          valueFrom:
            secretKeyRef:
              name: sitecore-database
              key: sitecore-database-elastic-pool-name.txt
        - name: DATABASES_TO_DEPLOY
          value: spe,sxa
      restartPolicy: Never
  backoffLimit: 5

Create a custom init.yaml file, for example custom-init.yaml, and put it under the /roles/sitecore-{topology}/tasks folder.

To add the mssql-init-sxa-spe job to the file, add the following code:

RequestResponse

- name: Execute sxa-spe mssql-init jobs
  k8s:
    apply: true
    namespace: "{{ solution_id }}"
    state: present
    definition: "{{ lookup('template', 'mssql-init-sxa-spe.yaml') }}"

- name: 'Wait - SXA-SPE Mssql-init job'
  k8s_info:
    kind: Job
    name: sxa-spe-mssql-init
    namespace: "{{ solution_id }}"
  register: sxa_spe_mssql_init_result
  until: (sxa_spe_mssql_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
  retries: 60
  delay: 60

- name: Get all SXA-SPE Mssql completed pods
  k8s_info:
    kind: Pod
    namespace: "{{ solution_id }}"
    label_selectors:
      - job-name = sxa-spe-mssql-init
  no_log: true
  register: sxa_spe_mssql_pod_list

- name: Remove SXA-SPE Mssql job's pods
  k8s:
    kind: Pod
    name: "{{ item.metadata.name }}"
    namespace: "{{ solution_id }}"
    state: absent
  no_log: true
  with_items: "{{ sxa_spe_mssql_pod_list.resources }}"

To call the custom init.yaml file, go to /roles/sitecore-{topology}/tasks/main.yaml and add the following role at the end of the file:
RequestResponse
```
- name: Execute custom init jobs 
  include_tasks: custom-init.yaml
```
Run the application pipeline.
If the custom job has been successfully created, comment out the Execute custom init jobs role.

Do you have some feedback for us?

If you have suggestions for improving this article,