Walkthrough: Adding the SXA module

Current version: 10.2

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:

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.

      Add the Searchstax-solr-init-sxa-spe property to the Application repository.

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

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

  1. 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
                valueFrom:
                   secretKeyRef:
                       name: sitecore-solr
                       key: sitecore-solr-core-prefix-name.txt 
              - name: SOLR_COLLECTIONS_TO_DEPLOY
                value: sxa
          restartPolicy: Never
      backoffLimit: 5
  2. 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 }}"
  3. Run the application pipeline.

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

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

  1. 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
                valueFrom:
                   secretKeyRef:
                       name: sitecore-solr
                       key: sitecore-solr-core-prefix-name.txt 
              - name: SOLR_COLLECTIONS_TO_DEPLOY
                value: sxa
          restartPolicy: Never
      backoffLimit: 5
  2. Create a custom init.yaml file, for example custom-init.yaml, and put it under the following folder: /roles/sitecore-{topology}/tasks.

  3. 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 }}"
  4. 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
    In the main.yaml file, call the init.yaml file.
  5. Run the application pipeline.

  6. 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:

  1. 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
  2. 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 }}"
  3. Run the application pipeline.

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

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

  1. 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
  2. Create a custom init.yaml file, for example custom-init.yaml, and put it under the /roles/sitecore-{topology}/tasks folder.

  3. 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 }}"
  4. 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
    In the main.yaml file, call the init.yaml file.
  5. Run the application pipeline.

  6. 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,