SAP HANA Deployment Shell

This document describes how the SAP HANA Deployment shell works.

Introduction

The SAP HANA Deployment shell (Dshell) is a cloud-hosted service provided by SAP for developers to deploy HTML and JavaScript sources to SAP HANA development edition.

Using the Dshell enables developers to develop and deploy with the tool of their choice. This provides developers especially for the development of HTML/CSS and JavaScript a wide variety on tools to use for building native applications. Through the integration with Github developer can host and share their repositories with the open source community or within the team using private repositories.

The SAP HANA Studio offers a comprehensive Integrated Development Environment (IDE) for developing SAP HANA based applications. SAP HANA Studio is the default tool for end-to-end development including modeling and building native objects like stored procedures or analytical models.

As an additional offering the Dshell enables simple development of apps which focus just on building with HTML5 or JavaScript.

Basics

The DShell basically allows you to deploy your GitHub hosted application to your HANA instance without using the HANA studio.

All you need to have is a

• Github account (If you don't have an account yet, you can sign up here)
• Hosted HANA instance that is publicly available

The design of the DShell is based on the following considerations:

• The Dshell enables easy deployment to SAP HANA from a variety of IDEs via Github
• Opens SAP HANA to a variety of developer environments supporting the choices of developers
• Provides developers an easy way to share SAP HANA development using Github

This diagram shows an overview of the basic components of a Dshell based HANA development:

Once you push your development to Github the service hook is triggered. It fires a post receive notification to the Dshell. The Dshell then pulls the repository files from Github and pushes them to the HANA instance.

As you see in the communication diagram the actual push to HANA is done with a tool called regi. This is SAPs internal tool for pushing code to HANA.

One major objective of the Dshell is to hide the complexity of regi, so we will in this documentation not talk about how regi works.

Process

Development and deployment of a JavaScript/HTML 5 application for HANA consist of different steps. The actual deployment onto the HANA Server is a highly automated process that runs in the background once the developer commits to Github.

1. Create new repository or clone existing repository in Github
2. Define service hooks towards DShell
3. Define Deployment strategy
4. Develop your application
5. Commit to Github
6. Automatic deployment to HANA instance is triggered
7. Run the application

Prerequisites

Before start working with the deployment shell make sure you have the following information available:

• hostname and port of your HANA instance (typically IP adress or URL)
• user and password for the HANA instance
  

You will need this information for setting up the Github repository in a way that it can communicate with the Dshell.

Starting with a Hello World example

The easiest way to start using the deployment shell for deploying applications to HANA is by forking a Hello World Application.

Once logged in to Github you can search for the simple HelloWorld application of user "SAPDshell". Type "SAPDshell" in the search field of Github and press enter:

Select <users> and then click on SAPDshell:

You'll see the "Home" page of user SAPDshell. Under "Popular repositories" click on the helloworld repository and then <fork>

Once the fork process is finished you should see your own version of the helloworld application in your repository list. The helloworld is already prepared for using the Dshell for the deployment to HANA.

You now need to change the settings of that repository like described in the next chapter.

Setting up a new Github repository

Repository structure

Using SAP DShell requires a specific structure of the GIT repository.

• The root of the repository must contain the strategy definition file deployment.json as described in next chapter
  and
• The root-folder of the application that actually contains the application source code files
  • this folder is named in the deployment file (see next chapter)
  • only this folder and subfolders are deployed
• Top level files are generally not deployed to HANA

Example:

The application subfolder must contain the two files .XSACCESS and .XSAPP:

.XSACCESS contains the following rows:
                        {
                        "exposed": true,
                        "authentication" : [{ "method" : "Form" }]
                        }

.XSAPP is just an empty file.

Those two files are standard files that need to be there when building HANA HTML/Javascript applications. You can easily created them in Github itself or create them in your local development environment and push them to Github .

In Github you would have to add them by pushing the plus button in the repository to create a file:

DShell Deployment strategies

The actual deployment of an application from Github to HANA is defined via a deployment configuration file. This configuration file is part of the application repository on Github and evaluated by Dshell.

The file must be nameddeployment.json and it basically contains:

• Deployment strategy (for HANA XS its always:   "strategy":"hanaxs" )
• HANA hostname:port ( <3>instance><15> )
• Root folder of Repository

Example:

Define Service Hook

To setup continuous deployment with Github and DShell, access the Settings section of your repository:

Click Service Hooks and then <WebHook URLs>. You will be presented with a form with one field where you have to enter the URL of the system that runs the Dshell and your user and password of the HANA instance to which you deploy:

The path of the URL is defined like this:

http://HANAusername:password@dshell.saphana.com:1237/?repo=Github repository address

• Username and password are the ones of your HANA instance, you should have got them when singin up for the HANA instance.
• The Github repository adress is the URL of the repository in which you are working right now. It basically looks like this
  https://github.com/<your github user name>/<repository name>
  
  You will find the same in the browsers adress field. Example: https://github.com/joerg-latza/helloworld

Example of the complte URL for the Service hook:

http://Testuser:IloveDShell@dshell.saphana.com:1237/?repo=https://github.com/joerg-latza/helloworld

The Service Hooks settings are private even if the repository itself is public, so nobody is able to see user and password other than the owner of the repository.

The Service Hooks are also not copied when a repository is forked.

Execution

Once the deployment is done you can start your application. The URL of the application is basically the HANA hostname with port 8000 followed by the root folder name  / start html.

Please consider, that the name of the root folder is prefixed with your HANA user name to ensure that no duplicates are deployed. This is to ensure that other developers with same repository structure would not overwrite yor application.

So the URL is defined as following:

http://<HANAhostname>:8000/<HANA User name-rootfoldername>/<startscreen>

of your application

In our example the hostname is

     http://hanasvr-08.sapdevcenter.com:8000/Testuser-foo/helloworld.xsjs

Summary

Once the deployment.json and the service hook is defined, Github will call the deployment shell with every commit you do into your Github repository and the Dshell will push the changes to the HANA instance that you have maintained in the deployment.json.

After some seconds you can then refresh or start your application on the HANA instance and should see the latest version of your development.

Error Handling

For technical reasons, the Dshell cannot send error messages back to Github so you won't recognize any errors that happend as part of the deployment.

If you figure out, that your most recent changes are not reflected when opening your application it might be that an error occured during the deployment.

This can be either a syntax error or wrong settings for the service hook or in the deployment.json.

In that case you can simple copy and paste the URL of the Web Hook entry into your browsers adress field and run. The browser will show the errors that happened during deployment.

Further information can be found here:

• HANA developer guide: http://help.sap.com/hana/hana_dev_en.pdf
• Git:http://git-scm.com/
• Github service hooks: https://github.com/github/github-services