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
Don’t worry, we are here to help…
A few weeks ago I published a post about the tool my colleagues albertodelgado, sergio-delgado and myself have build to create and deploy End-to-End apps to Cloud Foundry with just one command. Jump to the following link if you want to use it and make it work in minutes: https://blogs.sap.com/2020/07/29/cf-create-app-create-end-to-end-apps-and-deploy-to-cloud-foundry-in...
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
- What are we building?
- Requirements
- Recommended
- Step-by-Step Configuration
- Create a CAP Project
- Add a HANA database to your project
- Deploy your app with MTA
- Add an HTML5 custom application as your FrontEnd app
- 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:
| Node.js v12 | Download |
| Cloud Foundry CLI | Download |
| Cloud Application Model CLI | Download |
In your SCP Cloud Foundry account, you need access to the following services:
| HTML5 Application Repository | html5-apps-repo |
| SAP HANA Schemas & HDI Containers | hana |
| Authorization & Trust Management | xsuaa |
Recommended
| The MTA plugin for CF CLI | Download |
| HTML5 Applications Repository CF CLI Plugin | Download |
Step-by-Step configuration
1. Create a CAP Project
Navigate to your workspace and create a new CAP project running:
cds init your-app-nameThis 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_ENDPOINTFollow 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 hanaThis command adds adb/src/.hdiconfigfile with the required information to conect to your HANA instance in the cloud, and sets the db "kind" to "hana" in your projectpackage.jsonfile.
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 mtaCreate your build archive and deploy it
mbt build
cf deploy mta_archives/<your-app-mtar-archive-name>.mtarOnce the deployment is finished, the console logs the application endpoint as follows:
Application "my-srv" started and available at "csi-development-team-factory-cfaccount-sandbox-cap-boil36d2a520.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 appAdding 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 app4.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 sureyourHtml5ApplicationIdis unique in your HTML5 Application Repository. If there is another HTML5 application with the sameidin 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
- Creates an
html5Deployer/folder in the app root directory. - Add a new
package.jsonfile in the newhtml5Deployer/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.- Add
deploy_mode: html5-repoto the mainparametersblock
parameters:
enable-parallel-deployments: true
deploy_mode: html5-repo- Add the commands to build your HTML5 application to the
before-all > commandsblock.
- npm --prefix ./app install ./app
- npm run build --prefix ./app- Add the following code to the
modulesblock
# --------------------- 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
- Add the following code to the
resourcesblock
# --------------------- 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-serviceYou can change thenameof 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 therequiresandprovidesblocks.
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. Please review this document for more details about this scenario.
5.1 Add the Application Router to the project
- Creates an
approuter/folder in the app root folder. - Add a new
package.jsonfile in the newapprouter/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"
}
}- Add a new
xs-app.jsonfile in the newapprouter/folder with the following content.
{
"welcomeFile": "/index.html",
"authenticationMethod": "none",
"routes":[{
"source":"^(.*)",
"target":"yourHtml5ApplicationId/$1",
"service":"html5-apps-repo-rt"
}]
}TheyourHtml5ApplicationIdmust be the same included in the applicationmanifest.jsonfile, explained in the Step 4.1.
Thexs-app.jsonfile 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.- Add the following code to the
resourcesblock:
# --------------------- XSUAA Service ---------------------
- name: my-xsuaa
# ------------------------------------------------------------
parameters:
path: ./xs-security.json
service-plan: application
service: xsuaa
type: org.cloudfoundry.managed-service- Create the
xs-security.jsonfile 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.- Add the following code to the
modulesblock:
# --------------------- APPROUTER MODULE ---------------------
- name: my-approuter
# ------------------------------------------------------------
type: approuter.nodejs
path: approuter
requires:
- name: my-html5-runtime
- name: my-xsuaa6. 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: true6.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 filecf mta command is only available if your installed the MTA plugin for CF CLI mentioned in the README file > Recommended toolsWhat’s next?
Cool! Now you know how to build and deploy your apps to Cloud Foundry. You have now many possibilities to explore, and I am sure it will not be difficult to enhance your apps digging a bit into the documentation provided.
Remember that you can skip all this manual configuration and have everything ready in a few minutes, using the tool I mention at the beginning: https://blogs.sap.com/2020/07/29/cf-create-app-create-end-to-end-apps-and-deploy-to-cloud-foundry-in...
And do not hesitate to leave a comment if you have any insights, ideas, feedback, errors, or just want to share how useful was this for you.
Cheers
- SAP Managed Tags:
15 Comments
