tutorial_01_02_yaas

Deploying n-odata-server App to CF Platform (YaaS)

In this tutorial we will see how easy it is to deploy and run a n-odata-server application onto/in the cloud. In todays world a lot of applications are run in the cloud namely on the industry standard cloud platform Cloud Foundry (CF). CF has a lot of advantages to other proprietary solutions and all of the big IT companies jump on this bandwagon at the moment. Read more about this on the Cloud Foundry homepage.
As all big companies jump on this bandwagon also SAP does with it's Hana Cloud Platform. Hence we will use the Hana Cloud Platfrom CF Services to deploy our application that we created in step one of this series of tutorials to the HCP.

Source Code

The source code of this tutorial can be found on github. For each step we create a new branch. The master branch always contains the last evolution of this tutorial. The source code of this tutorial is available in branch 02_yaas.
Check this branch out if you don't want to do all the typing yourself.

Prerequisites

If you want to try this tutorial on you own you have to have an account on SAP Hana Cloud Platform as well as on SAPs microservice platform YaaS. Both platforms can be used for development and test purposes free of charge.

Preparing the system landscape

To be able to deploy to the CF Platform on HCP you have to prepare your CF system landscape. This procedure is described very well here. If you simply follow the steps of this document it does not take more than 10 minutes and you are ready to deploy an application to the cloud.

Application adjustment

In step one of this series of tutorials we created a n-odata-server application that can be executed as local node application on your desktop computer. Cause we want to deploy this application to the cloud now and run it there, we have to make a few adjustments to it.

Define node version in package.json

In the last step of this series of tutorials we ran the application locally with the node runtime that was installed on your machine. Cause there is always only one node runtime active at a local machine it is well defined which one is used for running our n-odata-server application. On CF it is possible to use several node versions. The ones that can be used are defined by the CF buildpacks. You can have a look at the supported runtimes by executing the

cf buildpacks

command after you have logged in to your CF account.
In the result you'll find a line that looks like this:

nodejs_buildpack       4          true      false    nodejs_buildpack-cached-v1.5.15.zip

This shows you which node buildpack is currently used on you CF platform. In this case it is v1.5.15. With this information you can go to corresponding release notes and see which node versions are supported. With version 1.5.15 we can use some 0.10.x, 0.12.x, 4.x.x, 5.x.x and 6.x.x versions. For this tutorial we will use the 4.4.x version cause this, at the time writing this, is the latest released LTS version (so we stay at the secure side of life).

To tell CF to use this version we have to define it in our package.json file. We add the engines section to it:

  "name": "n_odata_server_tut_01",
  "version": "1.1.0",
  "engines": {
    "node": "4.4.x"
  },
  "main": "server/server.js",

The entry "node": "4.4.x" means CF should use the latest supported version that starts with 4.4.
Please note that we also changed the version of our app from 1.0.0 to 1.1.0 to emphasize a change to our application.

Manifest.yml

CF apps are configured via the file manifest.yml that is located in the root directory of the project. This file contains instructions for the CF runtime when the application is deployed and started. It is a simple text file with indentation (be aware of the fact that you have to use spaces, not tabs, for indentation). The manifest file for our n-odata-server application looks like this:

applications:
- path: .
  memory: 256M
  disk_quota: 512M
  instances: 1
  domain: cfapps.us10.hana.ondemand.com
  name: n-odata-server-tut-01
  # change the next line, see below description for details
  host: n-odata-server-tut-01
  buildpack: nodejs_buildpack

The first line defines an applications section
The dash followed by one space in the second line starts a block for our application. The following lines that belong to this block are indented by two spaces
The path attribute tells CF where to find the application (in this case in the current folder)
memory defines the amount of RAM that is associated to the application.
disk_quota is used for allocation of disk space used by our application.
instances defines the number of app instances that are running in parallel. With this attribute you can easily scale your app if the traffic raises.
domain defines the domain that is used. On YaaS (trial) this is always cfapps.us10.hana.ondemand.com
name defines the name of the app. This attribute is mandatory at deployment time and can be either defined in manifest.yml or at command line.
host defines the subdomain of the url for your app. If omitted the name attribute will be used as subdomain. Please use another hostname than I used. Otherwise you will probably run into problems cause in the trial account all CF organizations seem to run on the same domain
buildpack tells CF which buildpack should be used to run the application. In this case we use the nodejs buildpack. If omitted CF will dynamically evaluate an appropriate buildpack.

For details about the manifest file have a look at the CF documentation.

.cfignore

There's one more thing to mention. If you define a .cfignore file in the root folder of your project all files and folders listed in this file will be ignored during deployment of your app. As an advice add the node_modules folder to this file cause this dramatically increases deployment times. The npm packages which are copied to this folder will be installed by CF via a npm install call before starting the application.

Application deployment

After we made the before mentioned adjustments to our application deployment is a child's play. Just login to your CF provider account at command line

cf login

with your credentials and then push the application via a call to

cf push

After one or two minutes you should see something like the following in your terminal

requested state: started
instances: 1/1
usage: 256M x 1 instances
urls: <your hostname>.cfapps.us10.hana.ondemand.com
last uploaded: Mon Sep 19 10:39:22 UTC 2016
stack: cflinuxfs2
buildpack: nodejs_buildpack  

     state     since                    cpu    memory           disk             details   
#0   running   2016-09-19 12:40:09 PM   0.0%   227.2M of 256M   188.2M of 512M ```

Use the application

As you used the local application in our last tutorial step you can now use the application in the cloud. Just replace the protocol (https), the hostname (copy from the output above) and delete the port (gets automatically set).
Here are some requests you can send to the server (if you don't like to work with curl you can of course also use your browser with a plugin like Postman e.g.)

Retrieve the service document

Invoke

curl -X GET -H "Accept: application/json" "https://<your hostname>.cfapps.us10.hana.ondemand.com/odata/"

The result should be

{
    "d": {
        "EntitySets": [
            {
                "name": "people",
                "url": "people"
            }
        ]
    }
}

Retrieve service metadata

curl -X GET -H "Accept: Accept: application/atom+xml" -H "Content-Type: application/atom+xml" "https://<your hostname>.cfapps.us10.hana.ondemand.com/odata/\$metadata"

results to

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" Version="1.0">
  <edmx:DataServices m:DataServiceVersion="2.0">
    <Schema xmlns="http://schemas.microsoft.com/ado/2008/09/edm" Namespace="NODATASERVER">
      <EntityType Name="person">
        <Key>
          <PropertyRef Name="id"/>
        </Key>
        <Property Name="firstname" Type="Edm.String"/>
        <Property Name="lastname" Type="Edm.String"/>
        <Property Name="id" Type="Edm.Int32"/>
      </EntityType>
      <Association/>
      <EntityContainer Name="NODATASERVER" m:IsDefaultEntityContainer="true">
        <EntitySet Name="people" EntityType="NODATASERVER.person"/>
        <AssociationSet/>
      </EntityContainer>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

Save a person

curl -X POST -H "Content-Type: application/json" -d '{
  "firstname": "Helmut",
  "lastname": "Tammen"
}' "https://<your hostname>.cfapps.us10.hana.ondemand.com/odata/people"

Result:

{
    "d": {
        "firstname": "Helmut",
        "id": 1,
        "lastname": "Tammen"
    }
}

Retrieve the saved person

curl -X GET -H "Accept: Accept: application/json" -H "Content-Type: application/json" "https://<your hostname>.cfapps.us10.hana.ondemand.com/odata/people"