Basic Configs

The above two units display the outer side of a JPS usage and now let’s have a closer look at the inner side - a code of a package with all required configurations.

The JPS manifest is a file with .json extension, which contains an appropriate code written in JSON format. This manifest file includes the links to the web only dependencies. This file can be named as you require.

The code should contain a set of strings needed for a successful installation of an application. The basis of the code is represented by the following string:

    type: string
    name: any required name
    
    {
        "type": "string",
        "name": "any required name"
    }
    

  • type
    • install - creating at least one environment
    • update - extension, installing in one of existing environments
  • name - JPS custom name

This is a mandatory body part of the application package, which includes the information about JPS name and the type of the application installation (the 'install' mode initiates a new environment creation required for a deployment, the 'update' mode performs actions on the existing environment). This basic string should be extended with the settings required by the application you are packing. The following configuration details are included beside the 'type': " " parameter:

Manifest Overview

There is a set of available parameters to define a manifest installation behaviour, custom description and design, application icons and success texts etc.

Basic Template

    type: string
    version: string
    name: string
    logo: string
    description: string
    homepage: string
    categories: array
    baseUrl: string
    settings: object
    nodes: array
    engine: string
    region: string
    ssl: boolean
    ha: boolean
    displayName: string
    appVersion: string
    onInstall: object/string
    startPage: string
    actions: array
    addons: array
    success: object/string
    ...: object
    
    {
      "type": "string",
      "version": "string",
      "name": "string",
      "logo": "string",
      "description": "object/string",
      "homepage": "string",
      "categories": "array",
      "baseUrl": "string",
      "settings": "object",
      "nodes": "array",
      "engine": "string",
      "region": "string",
      "ssl": "boolean",
      "ha": "boolean",
      "displayName": "string",
      "appVersion": "string",
      "onInstall": "object/array",
      "startPage": "string",
      "actions": "array",
      "addons": "array",
      "success": "object/string",
      "...": "object"
    }
    

  • type [optional] - type of the application installation. Available values are install and update. More details described above.
  • version - [optional] - JPS type supported by the Jelastic Platform. See the correspondence between version page.
  • name [required] - JPS custom name
  • logo [optional] - JPS image that will be displayed within custom add-ons
  • description - text string that describes a template. This section should always follow the template format version section.
  • homepage [optional] - link to any external aplication source
  • categories - categories available for manifests filtering
  • baseUrl [optional] - custom relative links
  • settings [optional] - custom form with predefined user input elements
  • nodes - an array to describe information about nodes for an installation. Required option for JPS with type install.
  • engine [optional] - engine version, by default java6
  • region [optional] - region, where an environment will be installed. Required option for type install.
  • ssl [optional] - Jelastic SSL status for an environment, by default false. Parameter is available only with type install mode.
  • ha [optional] - high availability for Java stacks, by default false. Parameter is available only with type install mode.
  • displayName [optional] - display name for an environment. Required option for type install.
  • appVersion [optional] - custom version of an application
  • onInstall [optional] - event that is an entry point for actions execution
  • startPage [optional] - path to be opened via the Open in browser button through a successful installation message
  • actions [optional] - objects to describe all custom actions
  • addons [optional] - includes JPS manifests with the type update as a new JPS installation
  • success [optional] - success text that will be sent via email and will be displayed at the dashboard after installation. There is an ability to use Markdown syntax. More details here.
  • "..." - the list of events can be predefined before manifest is installed. More details

Environment Installation

The environment can be installed in case when the type parameter is set to install. Then the set of nodes with their parameters should be defined also.

Nodes Definition

The list of available parameters are:

  • nodeType [required] - the defined node type. The list of available stacks are here.
  • cloudlets [optional] - a number of dynamic cloudlets. The default value is 0. flexible is an alias.
  • fixedCloudlets [optional] - a mount of fixed cloudlets. The default value is 1.
  • count [optional] - a mount of nodes in one group. The default value is 1.
  • nodeGroup [optional] - the defined node layer. A docker-based containers can be predefined in any custom node group.
  • displayName [optional] - node's display name (i.e. alias)
  • extip [optional] - attaching public IP address to a container. The default value is 'false'.
  • addons [optional] - a list of addons, which will be installed in current nodeGroup. Addons will be installed after environment installation and onInstall action will be finished. More details here
  • tag [optional] - an image tag for dokerized Jelastic templates with nodeType parameter. Full list of supported tag here.

The following parameters are available for Docker nodes only:

  • image [optional] - name and tag of Docker image
  • links [optional] - Docker links
    • sourceNodeGroup - source node to be linked with a current node
    • alias - prefix alias for linked variables
  • env [optional] - Docker environment variables
  • volumes [optional] - Docker node volumes
  • volumeMounts [optional] - Docker external volumes mounts
  • cmd [optional] - Docker run configs
  • entrypoint [optional] - Docker entry points

Nodes Actions

Specific Cloud Scripting actions for Docker containers include operations of volumes, links and environment variables management.

There are three available parameters to set Docker volumes:

  • volumes - list of volume paths
  • volumeMounts - mount configurations
  • volumesFrom - list of nodes the volumes are imported from

All of the fields are set within the Docker object:

    type: install
    name: docker volumes
    
    nodes:
      nodeGroup: sqldb
      image: centos:7
      volumes: []
      volumeMount: {}
      volumesFrom: []
    
    {
      "type": "install",
      "name": "docker volumes",
      "nodes": [
        {
          "nodeGroup": "sqldb",
          "image": "centos:7",
          "volumes": [],
          "volumeMounts": {},
          "volumesFrom": []
        }
      ]
    }
    

Volumes

This field represents a string array:

    - volumes:
      - /external
      - /data
      - /master
      - /local
    
    [
      {
        "volumes": [
          "/external",
          "/data",
          "/master",
          "/local"
        ]
      }
    ]
    

VolumeMounts This parameter is an object. It can be set like within the example below:

    volumeMounts:
      /example-path:
        sourcePath: ''
        sourceNodeId: 0
        sourceNodeGroup: ''
        sourceHost: ''
        readOnly: true
    
    {
      "volumeMounts": {
        "/example-path": {
          "sourcePath": "",
          "sourceNodeId": 0,
          "sourceNodeGroup": "",
          "sourceHost": "",
          "readOnly": true
        }
      }
    }
    
Here:

  • /example-path - path to place the volume at a target node
  • sourcePath [optional] - default value that repeats volume path (/example-path in our sample)
  • sourceNodeId - node identifier the volume should be mounted from (optional, in case of the sourceNodeGroup parameter using)
  • sourceHost [optional] - parameter for external mounts usage
  • readOnly - defines write data permissions at source node, the default value is false
  • sourceNodeGroup - any available nodeGroup within a source environment (ignored if the sourceNodeId parameter is specified). The list of mounted volumes is defined by a master node.

In case not all source node volumes are required to be mounted, the particular ones can be specified:

    - sourceNodeGroup: storage
      volumes: 
        - /master
        - /local
    
    [
      {
        "sourceNodeGroup": "storage",
        "volumes": [
          "/master",
          "/local"
        ]
      }
    ]
    

*VolumeMounts* examples

Master Node Mount:
Samples to mount a particular volume by exact node identifier & path (/master) and to mount all volumes from the layer master node by nodeGroup (/master-1)

    volumeMounts:
      /master:
        sourcePath: /master
        sourceNodeId: 81725
        readOnly: true
      /master-1:
       sourceNodeGroup: current-node-group
    
    {
      "volumeMounts": {
        "/master": {
          "sourcePath": "/master",
          "sourceNodeId": 81725,
          "readOnly": true
        },
        "/master-1": {
          "sourceNodeGroup": "current-node-group"
        }
      }
    }
    

Here, sourcePath and readOnly parameters are optional.

Mount Data Container:
Samples to mount all volumes from a particular node by exact node identifier & path (/node) and to mount master node volumes by nodeGroup type (/data)

    volumeMounts:
      /node:
        sourceNodeId: 45
      /data:
        sourceNodeGroup: storage
    
    {
      "volumeMounts": {
        "/node": {
          "sourceNodeId": 45
        },
        "/data": {
          "sourceNodeGroup": "storage"
        }
      }
    }
    

External Server Mounts:
Sample to mount a volume (/external) from external server by indicating its host (sourceHost), path (sourcePath) and access permissions (readOnly).

    volumeMounts:
      /external:
        sourceHost: external.com
        sourcePath: /remote-path
        readOnly: true
    
    {
      "volumeMounts": {
        "/external": {
          "sourceHost": "external.com",
          "sourcePath": "/remote-path",
          "readOnly": true
        }
      }
    }
    
Short Set for External Server:
Sample to mount a number of volumes from external server by specifying the required parameters (i.e. volume path, sourceHost, sourcePath, access permissions) for each of them within one string.
    volumeMounts:
      /ext-domain: aws.com
      /ext-domain/ro: aws.com;ro
      /ext-domain/path: aws.com:/121233
      /ext-domain/path/ro: aws.com:/121233:ro
    
    {
      "volumeMounts": {
        "/ext-domain": "aws.com",
        "/ext-domain/ro": "aws.com:ro",
        "/ext-domain/path": "aws.com:/121233",
        "/ext-domain/path/ro": "aws.com:/121233:ro"
      }
    }
    

Here, "ro" stands for readOnly permissions.

Environment Variables

Docker environment variable is an optional topology object. The env instruction allows to set the required environment variables to specified values.

    type: install
    name: Environment variables
    
    nodes:
      - nodeGroup: cp
        image: wordpress:latest
        env:
          WORDPRESS_VERSION: 4.6.1
          PHP_INI_DIR: /usr/local/etc/php
    
    {
      "type": "install",
      "name": "Environment variables",
      "nodes": [
        {
          "nodeGroup": "cp",
          "image": "wordpress:latest",
          "env": {
            "WORDPRESS_VERSION": "4.6.1",
            "PHP_INI_DIR": "/usr/local/etc/php"
          }
        }
      ]
    }
    

Links

Docker links option allows to set up interaction between Docker containers, without having to expose internal ports to the outside world.

The example below illustrates the way to link sql and memcached nodes to cp container.

    - image: wordpress:latest
      links:
        - db:DB
        - memcached:MEMCACHED
      cloudlets: 8
      nodeGroup: cp
      displayName: AppServer
    
    - image: mysql5:latest
      cloudlets: 8
      nodeGroup: db
      displayName: database
    
    - image: memcached:latest
      cloudlets: 4
      nodeGroup: memcached
      displayName: Memcached
    
    [
      {
        "image": "wordpress:latest",
        "links": [
          "db:DB",
          "memcached:MEMCACHED"
        ],
        "cloudlets": 8,
        "nodeGroup": "cp",
        "displayName": "AppServer"
      },
      {
        "image": "mysql5:latest",
        "cloudlets": 8,
        "nodeGroup": "db",
        "displayName": "Database"
      },
      {
        "image": "memcached:latest",
        "cloudlets": 4,
        "nodeGroup": "memcached",
        "displayName": "Memcached"
      }
    ]
    
where:

  • links - object that defines nodes to be linked to cp node by their nodeGroup and these links names
  • db - MYSQL server nodeGroup (environment layer)
  • memcached - Memcached server nodeGroup (environment layer)

As a result, all the environment variables within db and memcached nodes will be also available at cp container.

Here, environment variables of linked nodes will have the names, predefined within the links array.
For example:

  • variable MYSQL_ROOT_PASSWORD from sql node is DB_MYSQL_ROOT_PASSWORD in cp node
  • variable IP_ADDRESS from memcached node is MEMCACHED_IP_ADDRESS in cp node

The relative links functionality is intended to specify the JPS file’s base URL, in relation to which the subsequent links can be set throughout the manifest. This source destination (URL) can point either to the text of the file or its raw code. Therefore, it is passed in the manifest through the baseUrl parameter or specified while importing a corresponding JPS file via the Jelastic dashboard.

Note

The baseUrl value declared within the manifest has higher priority than installation via URL (i.e. Import).

Example

    type: update
    name: Base URL test
    baseUrl: https://github.com/jelastic-jps/minio/blob/master
    
    onInstall:
      log: Base URL test
    
    onAfterRestartNode [cp]:
      script: build-cluster.js
    
    success: README.md
    
    {
        "type" : "update",
        "name" : "Base URL test",
        "baseUrl" : "https://github.com/jelastic-jps/minio/blob/master",
        "onInstall" : {
            "log" : "Base URL test"
        },
        "onAfterRestartNode [cp]" : {
            "script" : "build-cluster.js"
        },
        "success" : "README.md"
    }
    

In case of the manifest installation via URL by means of the Jelastic Import functionality, the baseUrl placeholder will be defined if the specified path is set as in the example below:

{protocol}://{domain}/myfile.extension
where:

  • {protocol} - http or https protocols
  • {domain} - domain name of the website, where the manifest is stored
  • myfile.extension - name of the file with indicated extension (i.e. jps) at the end

There are the following Cloud Scripting rules applied while parsing file's relative path:

  • baseUrl parameter is being defined
  • verification that the linked file’s text doesn't contain whitespaces (including tabs and line breaks)
  • verification that the linked file’s text doesn't contain semicolons and round brackets

If installation is being run from GitHub and URL includes ‘/blob/’, it will be replaced with ‘/raw/’. In case the baseUrl parameter is defined without a slash at the end, it will be added automatically.

There are a list of JPS blocks which can use resources from related links:

  • logo - JPS application image is shown while jps installation
  • script - action,= for executing javascript and java scripts
  • description - information about JPS which is shown before install process
  • success - message after successfull application installation

The Cloud Scripting engine also supports a ${baseUrl} placeholder. It can be used throughout the users’ customs scripts (within the cmd and script actions).

For example:

    type: update
    name: Test Base URL
    baseUrl: http://example.com/
    
    onInstall:
      cmd [cp]: curl -fSs '${baseUrl}script.sh'    
    
    {
      "type" : "update",
      "name" : "Test Base URL",
      "baseUrl" : "http://example.com/",
      "onInstall" : {
        "cmd [cp]" : {
          "curl -fSs '${baseUrl}script.sh'"
        }
      }
    }