• Requirements
• Architectural Concept
• Configuration
  • Intershop Commerce Management (ICM)
  • Intershop Progressive Web App (PWA)
  • Mapping Table
• PWA Adaptions
  • Preparing the PWA for the Hybrid Approach with the Responsive Starter Store
• Development Environment
  • Configuration of a Development Domain
  • ICM
  • PWA
  • NGINX
  • Docker Compose for PWA/NGINX
• Further References

This document describes how to run PWA and ICM using the Hybrid Approach, so that pages from the Intershop Progressive Web App and pages from the classic storefront (Responsive Starter Store) can be run in parallel.

A possible scenario would be to have the shopping experience with all its SEO optimizations handled by the PWA and to delegate highly customized parts of the checkout or My Account area to ICM.

Requirements

The minimum version requirements for the involved systems are as follows:

• PWA 8.0.0
• ICM 13.1.2

You can use older ICM versions, but they have limitations that require evaluation.
For this reason, examples for ICM 7.10.x versions are included where it seems helpful.

The secure access required for the PWA/NGINX deployments in production-like environments is handled by the Ingress controller, so the PWA and the NGINX container itself can be deployed without SSL.
ICM needs to be deployed with secure access only which is the default with ICM 11 and later versions.

Architectural Concept

For a minimally invasive implementation, the mechanics for the Hybrid Approach are mainly implemented outside of ICM and in deployment-specific components of the PWA.

ICM is proxied in the express.js server of the server-side rendering (SSR) process and hereby made available to the outside.
A newly introduced mapping table is used in the SSR to decide whether an incoming request should be handled by the PWA or ICM.
This mapping table is also used in the browser-side PWA to switch from the single-page application context to ICM.

Configuration

Intershop Commerce Management (ICM)

ICM must be run with Secure URL-only Server Configuration, which can be done by adding SecureAccessOnly=true to the appserver configuration.
This is the default for ICM 11+ deployments.

Furthermore, the synchronization of the apiToken cookie must be switched on, so that users and baskets are synchronized between PWA and ICM.
See Concept - Integration of Progressive Web App and inSPIRED Storefront.

If you also want to support the correct handling for links generated in e-mails, the property intershop.WebServerSecureURL must point to NGINX.

Configuration via icm_as Helm chart:

INTERSHOP_APITOKEN_COOKIE_ENABLED: true
INTERSHOP_APITOKEN_COOKIE_SSLMODE: true
INTERSHOP_WEBSERVERSECUREURL: https://<NGINX>

Configuration via icm.properties (ICM 11+ in a Docker container):

intershop.environment.HYBRID=intershop.apitoken.cookie.enabled=true,intershop.apitoken.cookie.sslmode=true
intershop.WebServerSecureURL=https://<NGINX>

Configuration via $SERVER/share/system/config/cluster/appserver.properties (ICM 7.10):

SecureAccessOnly=true
intershop.apitoken.cookie.enabled=true
intershop.apitoken.cookie.sslmode=true
intershop.WebServerSecureURL=https://<NGINX>

Intershop Progressive Web App (PWA)

The server-side rendering process must be started with SSR_HYBRID=1.

Also, the Service Worker must be disabled for the PWA, as it installs itself in the browser of the client device and takes over the routing process, making it impossible to break out of the PWA and delegate to ICM.
The Service Worker is disabled by default.

Mapping Table

The mapping table resides in the PWA source code and provides the page-specific mapping configuration for the Hybrid Approach.

  {
    id: "Product Detail Page",
    icm: `${ICM_CONFIG_MATCH}/ViewProduct-Start.*(\\?|&)SKU=(?<sku>[\\w-]+).*$`,
    pwaBuild: `product/$<sku>${PWA_CONFIG_BUILD}`,
    pwa: `^.*/product/([\\w-]+).*$`,
    icmBuild: `ViewProduct-Start?SKU=$1`,
    handledBy: "icm"
  }

Each entry contains:

• A regular expression to detect a specific incoming URL as ICM or PWA URL (icm and pwa)
• Corresponding instructions to build the matching URL of the counterpart (pwaBuild and icmBuild)
• A property handledBy (either icm or pwa) to decide on the target upstream

The properties icm and pwaBuild can use named capture groups.
They are only used in the node.js process running on the server.
However, pwa and icmBuild are used in the client application where named capture groups are not yet supported by all browsers.

PWA Adaptions

With version 0.23.0 the PWA has been changed to no longer reuse the Responsive Starter Store application types, but rather to be based on the newly introduced headless application type for REST clients - intershop.REST.
This application type is completely independent of the Responsive Starter Store.
For this reason, the PWA must be configured to know which application to use to work with the Responsive Starter Store again (hybridApplication).

Preparing the PWA for the Hybrid Approach with the Responsive Starter Store

• Use a recent PWA version
• Configure the icmApplication setting in the environment files to specify the intershop.REST-based application used by the PWA (usually rest in the inSPIRED demo scenario).
• Configure the hybridApplication setting in the environment files to specify the Responsive Starter Store application (usually - in the inSPIRED demo scenario).
• Follow the Hybrid configuration setup

Development Environment

This section describes how to develop and test a PWA using the Hybrid Approach in a local development environment.

This development environment includes a local installation of ICM with the Responsive Starter Store, the PWA, and the NGINX.

After successful configuration and deployment, you can access the different systems with these URLs:

Configuration of a Development Domain

For a more realistic Hybrid Approach environment, do not use localhost as the development domain or 127.0.0.1 as the IP address.
Instead, configure a different domain in the operating system's etc/hosts file, pointing to the real IP address of your computer.
This guide uses example.com as the domain.
For better distinction we use separate subdomains for pwa and icm.

192.168.178.77 pwa.example.com
192.168.178.77 icm.example.com

The different parts of the server will then listen on different ports.
For this guide ICM will listen on port 8443 and the PWA SSR process will listen on port 4200 while the NGINX will respond on the default HTTPS port 443.

ICM

ICM needs to be set up like a regular ICM development environment with the Responsive Starter Store (icm-responsive).

The icm.properties file must contain the following:

intershop.WebServerURL = http://pwa.example.com
intershop.WebServerSecureURL = https://pwa.example.com

webserver.http.port = 8080
webserver.https.port = 8443

intershop.environment.HYBRID=intershop.apitoken.cookie.enabled=true,intershop.apitoken.cookie.sslmode=true

• ICM must point to NGINX, in this case https://pwa.example.com
• The synchronization of the apiToken cookie must be enabled
• ICM must run in secure-only mode (ICM 11+ does this by default)

PWA

The configurations relevant to the Hybrid Approach for running the PWA are:

• ICM_BASE_URL points to ICM https port - https://icm.example.com:8443
• For development scenarios with a self-signed certificate for ICM, this means that you have to set TRUST_ICM=true
• To enable the Hybrid Approach functionality in the SSR process, SSR_HYBRID=true must be set
• LOGGING=true helps with analysis and debugging

A local PWA built from the current PWA project sources can be run in a number of ways:

Via Docker

docker build -t dev_pwa . && docker run -it -p 4200:4200 -e ICM_BASE_URL=https://icm.example.com:8443 -e TRUST_ICM=true -e SSR_HYBRID=true -e LOGGING=true --name hybrid-pwa dev_pwa

Via bash

ICM_BASE_URL=https://icm.example.com:8443 TRUST_ICM=true SSR_HYBRID=true LOGGING=true npm run start

Via bash with SSR development server with auto compile

ICM_BASE_URL=https://icm.example.com:8443 TRUST_ICM=true SSR_HYBRID=true LOGGING=true npm run start:ssr-dev

ICM_BASE_URL=https://icm.example.com:8443 TRUST_ICM=true SSR_HYBRID=true LOGGING=true npm run start:ssr-dev -- --ssl

NGINX

The configurations relevant to the Hybrid Approach for running the NGINX are:

• UPSTREAM_PWA points to the PWA SSR process - http://pwa.example.com:4200
• ICM_BASE_URL points to ICM https port - https://icm.example.com:8443
• For secure access, set SSL=true
• To avoid unexpected caching side effects, set CACHE=false
• Set NGINX to respond to the default https port 443

To start the NGINX container from the project sources with Docker:

docker build -t dev_nginx nginx && docker run -it -p 443:443 -e UPSTREAM_PWA=http://pwa.example.com:4200 -e SSL=true -e CACHE=false --name hybrid-nginx dev_nginx

Docker Compose for PWA/NGINX

You can also start the PWA and NGINX with docker compose.
This is the easiest way to start and test the PWA part of a development Hybrid Approach environment.
For actual development on the PWA side, starting the SSR development server with auto compile might be more efficient.

services:
  pwa:
    image: intershophub/intershop-pwa-ssr
    build:
      context: .
    ports:
      - '4200:4200'
    environment:
      ICM_BASE_URL: 'https://icm.example.com:8443'
      SSR_HYBRID: 'true'
      TRUST_ICM: 'true'
      LOGGING: 'true'

  nginx:
    image: intershophub/intershop-pwa-nginx
    build: nginx
    depends_on:
      - pwa
    ports:
      - '443:443'
    environment:
      UPSTREAM_PWA: 'http://pwa:4200'
      ICM_BASE_URL: 'https://icm.example.com:8443'
      SSL: 1
      CACHE: 0

Further References

• Guide - Building and Running Server-Side Rendering
• Guide - Handle rewritten ICM URLs in the Hybrid Approach
• Concept - Multi-site handling