How to build End-to-End custom applications in Cloud Foundry

Hi developer!

Cloud Foundry is really cool! Many of us are continuously exploring it and pushing our new projects there.

However, I’m sure many of you struggled a bit to create and deploy your apps to Cloud Foundry. Documentation is spread, and in a typical configuration (Node.js backend app + HANA + Angular / React / Vue.js / UI5 / or whatever HTML5 app…) there are many things to connect and orchestrate.

Today I’m going to explain how configure all of this step by step, following a meaningful order, describing important details to take into account, and pointing to the documentation when possible.

Let’s start…

Index

1. What are we building?
2. Requirements
3. Recommended
4. Step-by-Step Configuration
   1. Create a CAP Project
   2. Add a HANA database to your project
   3. Deploy your app with MTA
   4. Add an HTML5 custom application as your FrontEnd app
   5. The Application Router

What are we building?

• A Node.js backend application and a HANA database instance, exposing your services via OData. We will use Cloud Application Programming Model (CAP) for this.

• An HTML5 application in your frontend side. No matter if using React, Angular, Vue.js, UI5 or any other HTML5 tech you like.

• An application router to dispatch you request to the correct place. Configure your mta.yaml file to deploy everything as an MTA application.

Requirements

In your computer:

In your BTP Cloud Foundry account, you need access to the following services:

Recommended

Step-by-Step configuration

1. Create a CAP Project

Navigate to your workspace and create a new CAP project running:

cds init your-app-name

This creates the backend application barebones with the recommended project structure and required dependencies. Read more about this in CAP documentation - Getting Started

Create a schema.cds file in the db/ folder and define your entities.

Read more about CDS Entity and Type definition in CAP documentation - Definition Language CDL (Entity and Type definitions)

Create a yourServiceName-service.cds file in the srv/ folder and declare your services.

Read more about CDS Service definition in CAP documentation - Definition Language CDL (Services)

2. Add a HANA database to your project

To persist your data in the cloud you might want to use a HANA database. To be able to add a HANA DB to your project, you have to log in to your CF account first:

cf login -a CF_ACCOUNT_API_ENDPOINT

Follow the command prompt to enter your credentials and select the space where you want access the HANA Instance.

Then add a HANA DB to the project with:

cds add hana

This command adds a db/src/.hdiconfig file with the required information to conect to your HANA instance in the cloud, and sets the db "kind" to "hana" in your project package.json file.

To be able to bind a HANA instance you must suscribe to SAP HANA Schemas & HDI Containers service via the Service Marketplace in your SAP Cloud Platform space.

3. Deploy your app with MTA

To deploy apps to our Cloud Foundry environment we will use the MTA concept.

MTA allows to deploy multiple application artifacts in one single file, making the process much simpler and avoiding errors. To know more about MTA visit the documentation.

Add the MTA descriptor file

cds add mta

Create your build archive and deploy it

mbt build
cf deploy mta_archives/<your-app-mtar-archive-name>.mtar

Once the deployment is finished, the console logs the application endpoint as follows:

Application "my-srv" started and available at "your-subaccount-space-and-app-name.cfapps.eu10.hana.ondemand.com"

This is your API endpoint.

4. Add an HTML5 custom application as your FrontEnd app

At this point you probably want to add an UI to your application, and this could be a quite big topic depending on your needs.

There is no technology limitations in this area, so you can use whatever HTML5 and JavaScript based technology like SAP UI5, ReactJS, Angular, VueJS, or plain HTML5 and vanilla JavaScript for example.

As you can imagine, it is not feasible to make a tutorial for all the option in the market. The following lines detail the process for the most common options, so it can guide you to follow an equivalent path for any other technology you might choose.

Adding a ReactJS application

Create your React Application in the /app folder:

cd app/
npx create-react-app .

Adding an Angular application

Use angular CLI to create your app in the /app folder:

npm install -g @angular/cli   #Skip this command if you already have Angular CLI installed in your computer
ng new app

Adding a Vue.js application

Use Vue CLI to create your app in the /app folder:

npm install -g @vue/cli   #Skip this command if you already have Vue CLI installed in your computer
vue create app

4.1 Set your application ID

To host our HTML5 application we use the HTML5 Application Repository service.

To know more about this service visit the documentation

To identify our app in the HTML5 Application Repository, we have to provide an ID in the manifest.json file.

If this file doesn't exist yet, create it and make sure it is included in the application build.

In the manifest.json file add the following lines:

{
  ...
  "sap.app": {
    "id":"yourHtml5ApplicationId",
    "applicationVersion":{
      "version": "1.0.0"
    }
  }
}

Make sure yourHtml5ApplicationId is unique in your HTML5 Application Repository. If there is another HTML5 application with the same id in the HTML5 Application Repository, a new deployment will overwrite it.

4.2 Add HTML5 Deployer

HTML5 application deployer handles the upload of the HTML5 applications content to the HTML5 Application Repository.

For more information about the HTML5 Application Deployer read the documentation

1. Creates an html5Deployer/ folder in the app root directory.

Add a new package.json file in the new html5Deployer/ folder with the following content.

{
  "name": "html5Deployer",
  "engines": {
    "node": ">=6.0.0"
  },
  "dependencies": {
    "@sap/html5-app-deployer": "2.0.0"
  },
  "scripts": {
    "start": "node node_modules/@sap/html5-app-deployer/index.js"
  }
}

4.3 Update MTA.yaml file to include the HTML5 Application

Edit the mta.yaml file with your favorite text editor.

1. Add deploy_mode: html5-repo to the main parameters block

parameters:
  enable-parallel-deployments: true
  deploy_mode: html5-repo

2. Add the commands to build your HTML5 application to the before-all > commands block.

- npm --prefix ./app install ./app
- npm run build --prefix ./app

3. Add the following code to the modules block

# --------------------- HTML5DEPLOYER MODULE -----------------
- name: my-hmtl5-deployer
  # ------------------------------------------------------------
  type: com.sap.html5.application-content
  path: html5Deployer
  requires:
    - name: my-html5-host
  build-parameters:
    requires:
      - name: my-app
        artifacts:
          - './*'
        target-path: resources/app

# --------------------- REACT APP MODULE ---------------------
- name: my-app
  # ------------------------------------------------------------
  type: html5
  path: app
  build-parameters:
    supported-platforms: []
    build-result: build # This is the folder containing the build files

4. Add the following code to the resources block

# --------------------- HTML5 Runtime ----------------------
- name: my-html5-runtime
  # ------------------------------------------------------------
  parameters:
    service-name: my-html5-runtime
    service-plan: app-runtime
    service: html5-apps-repo
  type: org.cloudfoundry.managed-service

# --------------------- HTML5 Host -------------------------
- name: my-html5-host
  # ------------------------------------------------------------
  parameters:
    service-name: my-html5-host
    service-plan: app-host
    service: html5-apps-repo
  type: org.cloudfoundry.managed-service

You can change the name of your modules and resources, making them consistant with your project name. If you do it, make sure you keep the relationships between modules and resources using the correct names in the requires and provides blocks.

5. The Application Router

The application router is the single point-of-entry for an application running in the Cloud Foundry environment on SAP Cloud Platform. The application router is used to serve static content, authenticate users, rewrite URLs, and forward or proxy requests to other microservices while propagating user information.

The following diagram illustrates where the App Router sits in a typical Cloud Foundry architecture:

This diagram includes a connection to an on-premise system which we will not see in this tutorial.

5.1 Add the Application Router to the project

1. Creates an approuter/ folder in the app root folder.

2. Add a new package.json file in the new approuter/ folder with the following content.

{
  "name": "approuter",
  "version": "1.0.0",
  "description": "My App Router",
  "dependencies": {
    "@sap/approuter": "^6.8.2"
  },
  "scripts": {
    "start": "node node_modules/@sap/approuter/approuter.js"
  }
}

3. Add a new xs-app.json file in the new approuter/ folder with the following content.

{
  "welcomeFile": "/index.html",
  "authenticationMethod": "none",
  "routes": [
    {
      "source": "^(.*)",
      "target": "yourHtml5ApplicationId/$1",
      "service": "html5-apps-repo-rt"
    }
  ]
}

The yourHtml5ApplicationId must be the same included in the application manifest.json file, explained in the Step 4.1.

The xs-app.json file describes the App router behaviour, like routing, authentication method, etc. The configuration proposed above sends every HTTP request to the HTML5 application, with no authentication required. To modify this bahaviour, please read the documentacion

5.2 Add XSUAA resource

Edit the mta.yaml file with your favourite text editor.

1. Add the following code to the resources block:

# --------------------- XSUAA Service ---------------------
- name: my-xsuaa
  # ------------------------------------------------------------
  parameters:
    path: ./xs-security.json
    service-plan: application
    service: xsuaa
  type: org.cloudfoundry.managed-service

2. Create the xs-security.json file in root folder of the project with the following code

{
  "xsappname": "my-approuter",
  "tenant-mode": "dedicated",
  "description": "Security profile of called application",
  "scopes": [
    {
      "name": "uaa.user",
      "description": "UAA"
    }
  ],
  "role-templates": [
    {
      "name": "Token_Exchange",
      "description": "UAA",
      "scope-references": ["uaa.user"]
    }
  ]
}

5.3 Update MTA.yaml file to include the App Router

Edit the mta.yaml file with your favorite text editor.

1. Add the following code to the modules block:

# --------------------- APPROUTER MODULE ---------------------
- name: my-approuter
  # ------------------------------------------------------------
  type: approuter.nodejs
  path: approuter
  requires:
    - name: my-html5-runtime
    - name: my-xsuaa

6. Access data from your HTML5 app

To consume the services defined with CAP in Step 1 (and therefore, the data in our HANA DB) we have to set a destination pointing to our backend service (the CAP application) and configure the App Router to manage routing accordingly.

6.1 Set a destination in your mta.yaml file

Modify the App Router module definition as follows:

# --------------------- APPROUTER MODULE ---------------------
- name: my-approuter
  # ------------------------------------------------------------
  type: approuter.nodejs
  path: approuter
  requires:
    - name: my-html5-runtime
    - name: my-xsuaa
    - name: srv-binding
      group: destinations
      properties:
        name: srv-binding
        url: ~{srv-url}
        forwardAuthToken: true

6.2 Configure your App Router to use the destination

The following configuration sets the Application Router to redirect all the <host>:<port>/api requests to your backend service via the destination called srv-binding. Any other request will be redirected to the HTML5 application

{
  "routes": [
    {
      "source": "/api/(.*)",
      "target": "$1",
      "destination": "srv-binding",
      "authenticationType": "none"
    },
    {
      "source": "^(.*)",
      "target": "yourHtml5ApplicationId/$1",
      "service": "html5-apps-repo-rt"
    }
  ]
}

7. Re-deploy your application with the new components

Run:

mbt build
cf deploy mta_archives/<your-app-mtar-archive-name>.mtar

You can always get your MTA applications details running the command:

cf mta <your-mta-app-ID>

Find the MTA App ID in the mta.yaml file

cf mta command is only available if your installed the MTA plugin for CF CLI mentioned in the recommended tools