JPS (Jelastic Packaging Standard) for One-Click Installation of Complex Applications

By February 20, 2014 HowTo 2 Comments
Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedInEmail this to someone

Jelastic aims to make using and managing complex things simple and clear. Also, our goal is to reduce the time that developers usually waste on routine tasks and give them an opportunity to spend it in a more effective way. However, there is always room for improvement.

In this article we will present our unique solution for automation of app installation in just one click – Jelastic Packaging Standard (JPS). We will describe how to package your own application in order to share it as ready-to-use product.

one-click-install-jps

General Overview

JPS is a standard that can be used for preparing templates of fully configured applications which are ready to be installed on the Jelastic cloud in one click. This system provides an opportunity to create an automated installer for Java, PHP or Ruby applications (also other languages in the future).

This standard simplifies the applications installation and configuration for end-users. JPS manages creation and automation of an application’s deployment process, defines a default set of properties and clustering configurations for an application, specifies size of the required resources and the scaling limits for each container in the application environment.

With JPS you can offer your users a widget for fast installation of applications. This helps to improve the application’s distribution and sales funnel significantly, because it removes complexity of installation and configuration, simplifies the choice of a right place for hosting and as a result reduces barriers in customer engagement. In addition, JPS helps IT Ops to reduce application support and management costs.

JPS Installation Flow

Each installation widget contains application manifest (or a link to its source) with the description of environment topology needed for an application, and instructions for installation and application configurations. JPS manifest is based on JSON format.

application manifestTo install the packaged cloud application, a user needs to initiate the installation by clicking the widget and entering their own email address. A confirmation link for installation will be sent to the provided email. After following this link, a user will be forwarded to Jelastic’s Dashboard and will need to confirm the installation.

After that, it will take a few minutes for internal Jelastic processes to complete the installation (actual duration depends on the complexity of your chosen application). Jelastic’s Platform parses the manifest data and interconnects the required nodes (app servers, databases, load balancers, etc). As a result, a user gets a fully configured running application without any manual installation actions.

initiate installation

Below, you’ll find detailed technical information on how to prepare an application manifest and how to create an installation widget correctly. We will also show the process of one-click installation from an end-users side.

Application Manifest

Before starting to pack your application, we recommend to deploy it first to Jelastic’s cloud manually and check all required settings in order to be aware what configurations to specify in your manifest code.

To create an appropriate JPS manifest JSON format should be used (JSON Formatter & Validator). This code should contain a set of strings needed for successful installation of an application.

Body of the Code

The basis of the code is represented by the following strings:

{
  "jpsVersion":"0.2"
  "jpsType": "install",
  "application": { }
}

This is a mandatory body part of the application package which includes the information about JPS version and the type of the application installation (“install” mode initiates a new environment creation, required for deployment).

Application Parameters

The abovementioned basic strings should be extended with the required settings of the application you are packing. The configuration details are included to the “application”: { } parameter.

Firstly, you need to provide some general information about the application such as its title, version, type of programming language and so on.

Sample of code for OpenCMS application description:

{ application: {
      "id":"opencms",
      "name":"OpenCMS",
      "version":"8.5",
      "logo":"",
      "type":"java",
      "homepage": "",
      "description": {
          "en": "OpenCMS from Alkacon Software is a professional, easy to use website content management system. OpenCms helps content managers worldwide to create and maintain beautiful websites fast and efficiently.",
          "ru": "Russian description"
      },
     "startPage" : "/install.jsp",
     "success": {
    "text": "Dashboard success text",
    "email": "Email success text"
     }

}}

Follow the link to more detailed documentation about app description parameters.

Environment Parameters

You will need to specify details about the environment your application requires for optimized performance. The settings stated in this part of your code will be used for creating and configuring an appropriate environment while installing the package.

Use the “env”: { } parameter to insert in all required values using possible variants which are listed in this documentation. This parameter includes the following sections:

  • “topology”:{ } section includes data on the programming language of the environment, required nodes with their settings and provides ability to enable such extra functions as High Availability and SSL.

    "topology":{
                  "ha":value,
                  "engine":"value",
                  "ssl":value,
                  "nodes":[ ]
               },
  • “deployments”:[ ] section is responsible for setting the deployment process of the application archive to the configured environment.

    "deployments":[
                  {
                     "archive":"value",
                     "name":"value",
                     "context":"value"
                  }
               ]
  • “upload”:[ ] section can be added if your application requires any additional files (e.g. any library or module) to be uploaded and set.

    "upload":[
                  {
                     "nodeType":"value",
                     "sourcePath":"value",
                     "destPath":"value"
                  }
                            ],
  • “configs”:[ ] section lets you modify any configuration file at any node (application server, database, etc) to configure application settings (e.g. configure connection setting between application server and database) and also perform database related operations: apply initial database dump, apply database patch etc.

    "configs":[
                  {
                     "nodeType":"value",
                     "restart":value,
                     "replacements":[]
                     "path":"value",
                     "database":{},
                     }
                              ]

Sample of code with environment settings required for Hello World application:

"env": {
            "topology": {
                "engine": "php5.3",
                "nodes": [{
                        "extip": false,
                        "count": 1,
                        "cloudlets": 16,
                        "nodeType": "apache2"
                    }
                ],
                "ssl": false,
                "ha": false
            },
            "deployments": [{
                    "archive": "http://app.jelastic.com/xssu/cross/download/RDYYHFNuUQYJBFpPZQ08F0UWCRlUHxdBD0ZlTS4gcQJFFBJUDwIBQmNTTEBI",
                    "name": "Hello World",
                    "context": "ROOT"
                }
            ],
            "configs": []
        },

To get more detailed instructions on stating required parameters, follow this link – environment parameters.

JPS supports a list of placeholders that can be used in any section of a JPS file (if the section isn’t strictly limited with its content). JPS controller will try to resolve all placeholders during the package installation stage. If it’s not possible, placeholder will be unresolved and displayed in the text as is (e.g. ${placeholder}).

Checking Result

To check if your manifest is properly configured use the link that initiates the process of installation:

http://{hoster_domain}?manifest={manifest_code}

Note that in this link instead of the manifest code, it is recommended to use the URL to the JSON file with your manifest.

Example of Manifest for Magento

Here is an example of the Magento application manifest. You can use this code as a basis while preparing your own packaged application. More examples can be found here.

{
    "jpsVersion": "0.2",
    "jpsType": "install",
    "application": {
        "id": "magento",
        "logo": "https://app.jelastic.com/xssu/cross/download/RDYYHFNvBFQOA1RKYgFoRhdDWhRTS00RDxZtG34gIlYWHhdXDwIBQmNTTEBI/view",
        "description": {
            "en": "Magento is the eCommerce software and platform trusted by the world's leading brands. Grow your online business with Magento!"
        },
        "name": "Magento",
        "env": {
            "topology": {
                "engine": "php5.3",
                "nodes": [{
                        "extip": false,
                        "cloudlets": 16,
                        "count": 1,
                        "nodeType": "apache2"
                    }, {
                        "extip": false,
                        "cloudlets": 16,
                        "count": 1,
                        "nodeType": "mysql5"
                    }
                ],
                "ssl": false,
                "ha": false
            },
            "deployments": [{
                    "name": "magento-1.7.0.2.zip",
                    "context": "ROOT",
                    "archive": "https://app.jelastic.com/xssu/cross/download/RDYYHA9jBlRaAVRLZldjQUdFDhhUG0dACkY4TnpzJlFFEhZVDwIBQmNTTEBI"
                }
            ],
            "configs": [{
                    "nodeType": "mysql5",
                    "database": {
                        "dump": "https://app.jelastic.com/xssu/cross/download/RDYYHFM0UFEJU1VNNwVqRRBAXhhXGBEQChNrG31xdFQRFkBYDwIBQmNTTEBI",
                        "patch": "UPDATE magento.admin_user SET password=CONCAT(MD5('qX${user.appPassword}'), ':qX'), email='${user.email}' WHERE username='admin';",
                        "name": "magento",
                        "user": "magento"
                    }
                }, {
                    "replacements": [{
                            "replacement": "<![CDATA[${env.appid}]]>",
                            "pattern": "{{key}}"
                        }, {
                            "replacement": "<![CDATA[${nodes.mysql5.address}]]>",
                            "pattern": "{{db_host}}"
                        }, {
                            "replacement": "<![CDATA[${nodes.mysql5.database.user}]]>",
                            "pattern": "{{db_user}}"
                        }, {
                            "replacement": "<![CDATA[${nodes.mysql5.database.password}]]>",
                            "pattern": "{{db_pass}}"
                        }, {
                            "replacement": "<![CDATA[${nodes.mysql5.database.name}]]>",
                            "pattern": "{{db_name}}"
                        }, {
                            "replacement": "</config>",
                            "pattern": "{{db_name}}"
                        }
                    ],
                    "path": "/var/www/webroot/ROOT/app/etc/local.xml",
                    "nodeType": "apache2"
                }, {
                    "restart": true,
                    "replacements": [{
                            "replacement": "extension=gd.so",
                            "pattern": "; Dynamic Extensions ;"
                        }
                    ],
                    "path": "/etc/php.ini",
                    "nodeType": "apache2"
                }
            ]
        },
        "success": {
            "text": "Admin panel URL: <a href='${env.url}index.php/admin/' target='_blank'>${env.url}index.php/admin/</a><br/>Username: admin<br/>Password: ${user.appPassword}",
            "email" : "Admin panel URL: <a href='${env.url}index.php/admin/' target='_blank'>${env.url}index.php/admin/</a><br/>Username: admin<br/>Password: ${user.appPassword}"
        },
        "type": "php",
        "homepage": "http://www.magentocommerce.com/",
        "version": "1.7.0.2"
    }
}

Installation Widget

And now, let’s share the outer side of JPS usage. When your application manifest is ready, you can proceed to share it among users by means of providing an installation widget of the following types.

widget

Follow the instruction below to get the widget for your application’s one-click deployment. As an example, we have used the widget with Magento package.

1. Include the following JavaScript code on your page, ideally right after the opening <body> tag:

<html>  
<body>
<script>
    (function(d, s, id) {
        var js, fjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) return;
        js = d.createElement(s); js.id = id;
        js.async = true;
        js.src = "//go.jelastic.com/widgets.js";
        fjs.parentNode.insertBefore(js, fjs);
    }(document, 'script', 'jelastic-jssdk'));
</script>
</body>
</html>

2. Place the following code wherever you want the widget to appear on your page:

<div 
	class="je-app" 
	data-manifest="link_to_json_file" 
	data-width="280" 
	data-theme="flat-blue" 
	data-text="Get it hosted now!" 
	data-tx-empty="Type your email and click the button" 
	data-tx-invalid-email="Invalid email, please check the spelling" 
	data-tx-error="An error has occurred, please try again later" 
	data-tx-success="Check your email" 
	data-key="app.{hoster_domain}">
</div>

Here the attributes are as follows:

  • data-manifest specifies the link to the JSON file of your packaged application;
  • data-width – the width of the widget;
  • data-theme – the colour of the widget. Possible values: flat-blue, flat-purple, flat-orange, flat-green;
  • data-text – initial label inside the widget. Default text is “Get it hosted now!”;
  • data-tx-empty – this text is displayed inside the widget when you hover over it. Default text is “Type your email and click the button”;
  • data-tx-invalid-email – this text appears when email is entered incorrectly. Default text is “Invalid email, please check the spelling”;
  • data-tx-error – if any error occurs a user will see this message. Default text is “An error has occurred, please try again later”;
  • data-tx-success – this text will be shown when installation is successfully initiated and a confirmation email is sent. Default text is “Check your email”;
  • class – this parameter should always have “je-app” value;
  • data-key – optional parameter that represents a hosting provider. If this parameter is not specified hosting provider will be chosen by GeoIP (geographically close to user).

You can also use your own widget on any site, with any customization required. The only requirement is that this widget has to request a link of the following type:

http://reg.{hoster_domain}/installapp?email={user_email}&id={app_id}

Customer Side

When the widget is placed on a site, any user can initiate the installation of the packaged application by clicking the Get it hosted now! button and performing only a few steps to complete the deployment:

1. Enter your email address and select the pointer.

widget4

2. After that, a confirmation link will be sent to the email address provided.

By following this one-time link you’ll be redirected to Jelastic’s dashboard.confirmation email

If the email is already registered with Jelastic, a user will be logged in automatically.

If there is no such Jelastic account, a user will be signed up automatically and receive an email with login credentials (the provided email) and password.

3. Within the dashboard, a Confirm installation of application window will be opened with summary information about the application.

Type the name of the environment required to be created for deploying the application and click Install.

magento confirmation

4. The installation process begins. Wait a moment for Creating, Deploying and Configuring to be completed.

package-installing

The credentials and URL to the app admin panel will be displayed (if it is required by your application, as in the case with Magento).

magento credentials

5. Click the Open in browser button. In a moment the installed application will be opened.

magento opened

As you will see, your application is up and running. And it is that easy!

Summary

In this article we’ve described how easy it is to package your own application and provide your users with a simple way to deploy it. So just give a try! Package your apps and share them on your websites using one-click installation widgets. More widgets – more users! Start now and benefit with our JPS solution from Jelastic.

Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedInEmail this to someone

2 Comments

  • Jacob Fogg says:

    This is FANTASTIC! Now the question is, are you going to create a central repository to list all of the packages for deployment? A simple screen with a listing of all the one click installation packages. I know that competetors like dreamhost: http://wiki.dreamhost.com/How_to_Install_an_One-Click_Install are already doing this. Search and choose from a menu of deployment software packages from within Jelastic, click a button and the deployment page pops right up!

    • Tetiana Fydorenchyk says:

      Jacob, we are already working on such central repository and soon will present a page with all supported JPS apps. Right now you can find the list of these solutions at Jelastic dashboard of some hosting providers. And in the near future this option will be available for all Jelastic users at their dashboards by default.

Leave a Reply

Subscribe to get the latest updates