Configure Managed Cloud

Walkthrough: Adding the JSS module

Version:

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:

In Powershell, run 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 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:

{
    "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:

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

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

---   
- 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

In the root directory of the repository, open the main.yaml file.

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

      include_role:
        name: ingress-configuration

Insert the following:

      include_role:
        name: nginx-underscores

Run the application pipeline.

Run the Mssql-init-jss container without disaster recovery

To run the Mssql-init-jss container:

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

---
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

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:

- 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 }}"

Run the application pipeline.

Run the Mssql-init-jss container with disaster recovery

To run the Mssql-init-jss container:

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

---
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

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-jss job to the file, add the following code:

- 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 }}"

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

If you have suggestions for improving this article, let us know!