SAP CAP Lessons Learned: Deploy app on HTML5 Repository

[LucasMagriniRigo]

Good day fellow CAPpers,

Today I'll share one of the lessons I've learned working with CAP, something that may not be clear in the current tutorials or documentation. It's about deploying the front-end, the UI, of your CAP application in the SAP BTP's HTML5 Repository instead of creating an AppRouter, a separate Cloud Foundry application, for it.

Pre-requisite on BTP:

To display or run HTML5 applications, your BTP SubAccount will need to have one of these services enabled/subscribed:

• SAP Build Work Zone, standard edition
• SAP Build Work Zone, advanced edition
• SAP SuccessFactors Work Zone
• SAP Cloud Portal service

I recommend SAP Build Work Zone, standard edition, because it's the simplest to setup. It will be used in this guide.

Assumption about your CAP project:

The guide will assume you have the standard project structure for an MTA application:

/project
 /app
  /my-app
   ...
   package.json
   ui5-deploy.yaml
   ui5.yaml
 /db
 /srv
 package.json
 mta.yaml

Note: the database module is optional.

Considering this, your mta.yaml will require 3 modules:

1. A module for the app itself, with type: html5 and path: app/my-app​
   - Each different app will require one of these modules
   - It effectively zips the application and stores in the /resources folder
2. A deployer module with type: com.sap.application.content
   - This module can be reused for different apps, but needs a parameter for​ each app
   - It takes the .zip files from /resources folder and sends to the HTML5 Repo
3. An app-content module with type: com.sap.application.content that will effectively do the setup of the HTML5 Repository​
   - This module is unique and don't need to be edited if new apps are added.
   - It sets up the connection between your app and the HTML5 Repository service and the service bindings

These modules will require 3 resources:

1. Repo Host: the service for HTML5 Repository Host
2. Destination: the service that allows your UI (/app) to communicate with the service (/srv)
3. XSUAA: User Authorization and Authentication. You can make it work without this service, but I wouldn't recommend.

The resulting mta.yaml would look like this:

_schema-version: "3.1"
ID: cap-app-id
description: CAP app with UI on HTML5 Repo
version: 1.0.0

# build parameters added by the generator
parameters:
  deploy_mode: html5-repo
  enable-parallel-deployments: true
build-parameters:
  before-all:
    - builder: custom
      commands:
        - npm install
        - npx cds build --production

modules:
  # srv
  - name: my-srv
    type: nodejs
    path: gen/srv
    build-parameters:
      builder: npm
    parameters:
      buildpack: nodejs_buildpack
      readiness-health-check-http-endpoint: /health
      readiness-health-check-type: http
      routes:
        - route: ${space}-my-srv.${default-domain}
    provides:
      - name: srv-api
        properties:
          srv-url: ${routes/0/route}
    requires:
      - name: my-auth
      - name: my-destination-service

  # app content deployer
  - name: my-deployer
    type: com.sap.application.content
    path: .
    requires:
      - name: my-repo-host
        parameters:
          content-target: true
    build-parameters:
      build-result: resources
      requires:
        - artifacts:
            - my-app.zip
          name: myapp
          target-path: resources/
        - artifacts:
            - my-other-app.zip
          name: myotherapp
          target-path: resources/

  # my app itself
  - name: myapp
    type: html5
    path: app/my-app
    build-parameters:
      build-result: dist
      builder: custom
      commands:
        - npm install
        - npm run build:cf
      supported-platforms:
        []

  # my other app itself
  - name: myotherapp
    type: html5
    path: app/my-other-app
    build-parameters:
      build-result: dist
      builder: custom
      commands:
        - npm install
        - npm run build:cf
      supported-platforms:
        []

  # app html5 repo host
  - name: my-app-content
    type: com.sap.application.content
    build-parameters:
      no-source: true
    requires:
      - name: my-auth
        parameters:
          service-key:
            name: my-auth-key
      - name: my-repo-host
        parameters:
          service-key:
            name: my-repo-host-key
      - name: my-destination-service
        parameters:
          content-target: true
    parameters:
      content:
        instance:
          existing_destinations_policy: update
          destinations:
            - Name: my-repo-host
              ServiceInstanceName: my-html5-srv
              ServiceKeyName: my-repo-host-key
              sap.cloud.service: my.app
            - Name: my-auth
              Authentication: OAuth2UserTokenExchange
              ServiceInstanceName: my-auth
              ServiceKeyName: my-auth-key
              sap.cloud.service: my.app

resources:
  - name: my-repo-host
    type: org.cloudfoundry.managed-service
    parameters:
      service: html5-apps-repo
      service-name: my-html5-srv
      service-plan: app-host
  - name: my-destination-service
    type: org.cloudfoundry.managed-service
    requires:
      - name: srv-api
    parameters:
      config:
        HTML5Runtime_enabled: true
        init_data:
          instance:
            destinations:
              - Authentication: NoAuthentication
                Name: ui5
                ProxyType: Internet
                Type: HTTP
                URL: https://ui5.sap.com
              - Name: app-dest # defined in the apps xs-app.json
                Authentication: NoAuthentication
                ProxyType: Internet
                HTML5.ForwardAuthToken: true
                HTML5.DynamicDestination: true
                Type: HTTP
                URL: https://~{srv-api/srv-url} # reference to the service
            existing_destinations_policy: update
        version: 1.0.0
      service: destination
      service-name: my-destination-service
      service-plan: lite
  - name: my-auth
    type: org.cloudfoundry.managed-service
    parameters:
      service: xsuaa
      service-plan: application
      path: ./xs-security.json
      config:
        xsappname: my-app # update as required
        tenant-mode: dedicated
 

EDIT: Very important: Remember to set the resources repo-host parameter HTML5Runtime_enabled to true. It generates as false and may cause you a headache until you find it.

May this post help you on your troubleshooting. Reply if you find any issues so I, and the community, can help.

Lucas Magrini Rigo

SAP Business Technology Platform SAP Cloud Application Programming Model HTML5 SAP Fiori Launchpad SAP Build Work Zone, standard edition