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 the development edition of SAP HANA platform.

The Dshell enables developers to develop and deploy applications with the tool of their choice. Whereas developers use the SAP HANA studio as the default tool for end-to-end native application development, the Dshell enables you to focus on building applications only with HTML5 or JavaScript. Through the Dshell integration with GitHub, developers can host and share their repositories with the open source community or within the team using private repositories.

Basics

The Dshell allows you to deploy your GitHub hosted application to your instance of SAP HANA without using the SAP HANA studio.

All you need is

• A GitHub account (If you don't have an account yet, you can sign up here)
• A hosted instance of SAP HANA that is publicly available

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

• Enables intuitive deployment to SAP HANA from a variety of integrated development environments via GitHub
• Opens SAP HANA to a variety of developer environments, supporting the choices of developers
• Provides developers with an intuitive way to share development of SAP HANA using GitHub

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

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 instance of SAP HANA.

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

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

Process

Development and deployment of a JavaScript/HTML5 application for SAP HANA comprises different steps. The actual deployment onto the server for SAP HANA 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 hook for DShell
3. Define deployment strategy
4. Develop your application
5. Commit to GitHub
6. Trigger automatic deployment to SAP HANA
7. Run the application

Prerequisites

Before starting work with the Dshell make sure you have the following information available:

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

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 SAP HANA is by forking a "Hello World" Application.

Once logged into GitHub you can search for the simple "Hello World" 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 "Hello World" application in your repository list. The "Hello World" is already prepared for when you use the Dshell for the deployment to SAP HANA.

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

Setting up a new Github repository

Repository structure

Using the Dshell requires a specific structure of the GitHub 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 SAP 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 HTML/Javascript applications for SAP HANA. You can create them in GitHub itself or create them in your local development environment and push them to GitHub.

In GitHub, you 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 SAP HANA is defined with a deployment configuration file. This configuration file is part of the application repository on GitHub and is evaluated by Dshell.

The file must be nameddeployment.json and it contains:

• Deployment strategy (for HANA XS its always:   "strategy":"hanaxs" )
• SAP HANA hostname:port ( with port = <3>instance><15> )
• Root folder of Repository
• root package name ("pattern")

Example:

The parameter "pattern" is used to define the name of the root package. If defined, it overrules the default behaviour which is <user-name>-<root> for the root package name.

Please consider that this is intended for exclusive HANA instances only. If used for shared instance this might lead to overwriting other package with the same setting for "pattern"

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>. In the form, enter the URL of the system that runs the Dshell and your user and password of the instance of SAP HANA to which you deploy:

The path of the URL is defined as follows:

http://<SAP HANAusername>:<password>@dshell.saphana.com:1237/?repo=GitHub repository address

• The username and password are the ones of your instance of SAP HANA; you should have received them when signing up for the 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 browser's adress field. Example: https://github.com/joerg-latza/helloworld

Example of the complete URL for the service hook:

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

The service hook settings are private even if the repository itself is public, so no one is able to see user and password other than the owner of the repository.

Also, the service hooks are 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 hostname of SAP HANA with port 8000 followed by the root folder name  / start html.

Prefix the name of the root folder with your user name for SAP HANA to ensure that no duplicates are deployed and that no other developers with same repository structure can overwrite yor application.

The URL is defined as following:

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

In our example the URL of the application is

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

Its different when you have maintained parameter "pattern" in deployment.json. Lets assume you have "pattern" : "mydemo" the URL would look like this:

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

Summary

Once you define the deployment.json and the service hook, GitHub will call the deployment shell with every commit you make into your Github repository. In addition, the Dshell will push the changes to the instance of SAP HANA that you have maintained in the deployment.json.

After several seconds you can then refresh or start your application on SAP HANA and you 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 occured as part of the deployment.

If you determine 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 either case you can simply copy and paste the URL of the Web Hook entry into your browser's adress field and run it. The browser will show the errors happened during deployment.

Further information can be found here:

• Developer guide for SAP HANA: http://help.sap.com/hana/hana_dev_en.pdf
• Git:http://git-scm.com/
• GitHub service hooks: https://github.com/github/github-services