Deploying a CAP app with Fiori app standalone (HTML5 Repo Host)

[Christopher_Ketzler]

Typically, a CAP app with a Fiori frontend is deployed using SAP Workzone or Launchpad. You just need to run "cds add portal" or "cds add workzone" to extend the configuration and deploy the app to Cloud Foundry (Deploy to Cloud Foundry | capire). The application will then be listed in the HTML5 tab of your subaccount. However, this approach is only applicable if you are subscribed to SAP Workzone or Launchpad (see below). A few months ago I was asked how to deploy a standalone CAP application with UI. Here is a step-by-step guide to deploying a CAP app with frontend.

There are at least two different approaches. The first exposes the frontend application through the approuter. The other exposes the frontend application to the HTML5 Repo Host (SAP Discovery Center Service - HTML5 Application Repository Service). This has several advantages over the approuter:

• Zero Down-Time Enablement, the frontend application is decoupled from the application router, meaning that content updates do not require a restart of the application router.
• The service supports versioning and permissions.
• Improved availability and performance.

How to deploy a Fiori-CAP app to the html5-repo-host:

For simplicity, we will set up a new tiny bookshop example. Based on this backend, we will generate a simple Fiori List Page app.

cds init bookshop --add tiny-sample
cd bookshop

Run the commands below to add some features. We will extend the configuration of the components later.

cds add hana,html5-repo,approuter,mta
cds add xsuaa --for production

Now we are ready to add a Fiori List Report application. Right click on the mta.yaml and select 'Create MTA Module from Template'. The App Wizard will open and you will be able to configure a new Fiori app.

To make the html5 application accessible through the app router, we need to make some changes to its configuration. Locate the router configuration in the “app/router” folder.  Add the “welcomeFile” and “authenticationMethod” properties to the xs-app file. In general, you can add a path to a file or the name of a Fiori app as a welcome file. The app router will redirect the user if accessing the app router. We need to add the name of the Fiori app as "welcomeFile" property. If you have defined a namespace when building the frontend app, make sure you include the namespace without delimiter. After deployment, the app router configuration below will redirect you to the Fiori app.

{
  "welcomeFile": "<Fiori app name>",
  "authenticationMethod": "route",
  "routes": [
    {
      "source": "^/(.*)$",
      "target": "$1",
      "destination": "srv-api",
      "csrfProtection": true
    }
  ]
}

Next, we need to extend the xs-app.json of the Fiori app itself. Add a new route for the odata service to make your cap service accessible from the Fiori app. Add the following snippet to the routes array before the html5-repo route.

{
   "source": "^/odata/(.*)$",
   "target": "/odata/$1",
   "destination": "srv-api",
   "csrfProtection": true
}

The app router applies the routes in the order given in the routes array, i.e. if the first route matches, the others are ignored. The target is the service name defined in mta.yaml. The xs-app.json should now look similar to this one.

{
  "welcomeFile": "/index.html",
  "authenticationMethod": "route",
  "routes": [
    {
      "source": "^/resources/(.*)$",
      "target": "/resources/$1",
      "authenticationType": "none",
      "destination": "ui5"
    },
    {
      "source": "^/test-resources/(.*)$",
      "target": "/test-resources/$1",
      "authenticationType": "none",
      "destination": "ui5"
    },
    {
      "source": "^/odata/(.*)$",
      "target": "/odata/$1",
      "destination": "srv-api",
      "csrfProtection": true
    },
    {
      "source": "^(.*)$",
      "target": "$1",
      "service": "html5-apps-repo-rt",
      "authenticationType": "xsuaa"
    }
  ]
}

Now we need to add the requires section below to the Fiori app's mta.yaml configuration. This snippet defines the service binding of the frontend app to the CAP service.

 - name: books
  type: html5
  path: app/books
  build-parameters:
    build-result: dist
    builder: custom
    commands:
    - npm install
    - npm run build:cf
    supported-platforms: []
  requires:
  - name: srv-api
    group: destinations
    properties:
      forwardAuthToken: true
      name: srv-api
      url: ~{srv-url}

If you are deploying to a BTP trial account, add the following snippet to the xs-security in the cap root folder. Make sure the link matches the cf api url for your environment.

"oauth2-configuration": {
    "redirect-uris": ["https://*.cfapps.us10-001.hana.ondemand.com/**"]
  }

Add the environment variable "COOKIE_BACKWARD_COMPATIBILITY" to the “app/router/default-env.json” file. The app asked me to add this configuration. For more information, see the app router documentation (@sap/approuter - npm).

{
  "destinations": [
    {
      "name": "srv-api",
      "url": "http://localhost:4004",
      "forwardAuthToken": true
    }
  ],
  "COOKIE_BACKWARD_COMPATIBILITY": true
}

We are all almost done! Install the dependencies, build the CAP app and deploy to Cloud Foundry.

npm i
mbt build
cf deploy …. (or context menu of the mta_archive)

After successfully deploying the application, retrieve the URL using the html5 cf plugin. Run the terminal command below. Add the app name (with namespace) and "index.html" to the URL to open the Fiori app.

cf html5-list -a <app name>-srv -u

Alternatively, navigate to the subaccount in the BTP Cockpit, access your app router and follow the application route. The router will redirect you to the Fiori app.  

Find the app router on the application tab.

Follow the application route and access the fiori app.

Further information:

https://www.youtube.com/watch?v=Jbq6zaKEUyY