Walkthrough: Adding the JSS module

Current version: 10.1

Sitecore JavaScript SDK (JSS) is a set of npm packages that let you implement Sitecore apps using modern JavaScript frameworks. To add the JSS 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 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 Mssql-init-jss 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 JSS module.

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

  • cm-jss

  • cd-jss

  • mssql_init_jss

Push the images to the Azure Container Registry (ACR)

To push the images to the ACR:

Change the images in the Application repository

Now you can add the JSS-specific naming images to the Application repository.

To change the images in the Application repository:

  • Go to the application repository config/docker-images and edit docker-images.json as follows:

    • Replace the cm value with the cm-jss image reference URL.

    • Replace the cd value with the cd-jss image reference URL.

    • Add the mssql_init_jss property.

    For example:

    RequestResponse
    {
        "sitecore":{
            "cm": "<newly built cm-jss image reference>",
            "cd": "<newly built cd-jss image reference>",
            "id": "scr.sitecore.com/sxp/sitecore-xml-id:10.1.0-ltsc2019",
            "mssql_init_jss": "<newly built mssql_init_jss image reference>",
        };
    ...

Enable the underscores in headers option for the ingress controller

The Nginx ingress controller drops request headers that contain underscores by default.

The JSS module uses some headers that contain underscores. To support this functionality, you must therefore enable the underscores in headers option.

To enable the underscores in headers option:

  1. Go to roles/ and create the following folder structure: roles/nginx-underscores/tasks.

  2. In the roles/nginx-underscores/tasks folder, add a main.yaml file that contains the following code:

    RequestResponse
    ---   
    - name: Customize
    nginx - enable underscores-in-headers
      k8s:
        definition:
          apiVersion: v1
          kind: ConfigMap
          metadata:
            name: ingress-nginx-controller
            namespace: nginx
          data:
            enable-underscores-in-headers: 'true'
        validate: 
          fail_on_error: yes
  3. In the root directory of the repository, open the main.yaml file.

  4. To add a new nginx- underscores role, after the section:

    RequestResponse
          include_role:
            name: ingress-configuration

    Insert the following:

    RequestResponse
          include_role:
            name: nginx-underscores
  5. Run the application pipeline.

Run the Mssql-init-jss container without disaster recovery

To run the Mssql-init-jss container:

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

    RequestResponse
    ---
    apiVersion: batch/v1
    kind: Job
    metadata:
      name: jss-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_jss }}"
            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: jss
          restartPolicy: Never
      backoffLimit: 5
  2. To add the Ansible tasks to run the mssql-init-jss job, go to roles\sitecore-xm\tasks\init.yaml and add the following scripts at the end of the file:

    RequestResponse
    - name: Execute jss mssql-init jobs
      k8s:
        apply: true
        namespace: "{{ solution_id }}"
        state: present
        definition: "{{ lookup('template', 'mssql-init-jss.yaml') }}"
    
    - name: 'Wait - JSS Mssql-init job'
      k8s_info:
        kind: Job
        name: jss-mssql-init
        namespace: "{{ solution_id }}"
      register: jss_mssql_init_result
      until: (jss_mssql_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
      retries: 60
      delay: 60
    
    - name: Get all JSS Mssql completed pods
      k8s_info:
        kind: Pod
        namespace: "{{ solution_id }}"
        label_selectors:
          - job-name = jss-mssql-init
      no_log: true
      register: jss_mssql_pod_list
    
    - name: Remove JSS Mssql job's pods
      k8s:
        kind: Pod
        name: "{{ item.metadata.name }}"
        namespace: "{{ solution_id }}"
        state: absent
      no_log: true
      with_items: "{{ jss_mssql_pod_list.resources }}"
  3. Run the application pipeline.

Run the Mssql-init-jss container with disaster recovery

To run the Mssql-init-jss container:

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

    RequestResponse
    ---
    apiVersion: batch/v1
    kind: Job
    metadata:
      name: jss-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_jss }}"
            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: jss
          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-jss job to the file, add the following code:

    RequestResponse
    - name: Execute jss mssql-init jobs
      k8s:
        apply: true
        namespace: "{{ solution_id }}"
        state: present
        definition: "{{ lookup('template', 'mssql-init-jss.yaml') }}"
    
    - name: 'Wait - JSS Mssql-init job'
      k8s_info:
        kind: Job
        name: jss-mssql-init
        namespace: "{{ solution_id }}"
      register: jss_mssql_init_result
      until: (jss_mssql_init_result.resources[0].status.conditions[0].type | default('')) == 'Complete'
      retries: 60
      delay: 60
    
    - name: Get all JSS Mssql completed pods
      k8s_info:
        kind: Pod
        namespace: "{{ solution_id }}"
        label_selectors:
          - job-name = jss-mssql-init
      no_log: true
      register: jss_mssql_pod_list
    
    - name: Remove JSS Mssql job's pods
      k8s:
        kind: Pod
        name: "{{ item.metadata.name }}"
        namespace: "{{ solution_id }}"
        state: absent
      no_log: true
      with_items: "{{ jss_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 mail.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,