Java Custom Application

Abstract

In addition to the legacy shiva applications, you may want to bring your own Java application. You get the ability to write your own app, add it to punch binaries and customize a shell to launch it as a shiva command.

Warning

You should learn the shiva documentation before going further : Shiva documentation

Requirements

To proceed to a Shiva app customization, ensure that :

• Shiva is deployed
• Punch Operator is deployed
• You have an ssh access to these servers
• You have read and write permissions on {setups_root} folder on these servers

Info

Check the {setups_root} configuration inside the platform section in punchplatform-deployment.settings documentation

Create a custom Shiva application

A custom Shiva application is divided into 3 parts :

• A custom binary file application
• A custom shell command, using the custom binary
• A custom channel structure, using the remote custom shell

Custom binary

The custom jar binary must be placed inside your deployer's archives :

├── punch-deployer-6.1.0
│   └── archives
│       └── extlib
|           └── shiva
│               └── my_app
|                   ├── my_java_application.jar
|                   └── log4j2.properties

The custom jar will be deployed on your platform with Shiva:

punchplatform-deployer.sh --deploy -Kk -t shiva

After the deployment, the custom jar will be placed on the shiva servers inside :

├── punch-binaries-6.1.0
│   └── extlib
│       └── shiva
│           └── my_app
|               ├── my_java_application.jar
|               └── log4j2.properties

Info

The punch-binaries-6.1.0 folder is located inside {setups_root}

Warning

Your own jar file should always contains all the required dependencies to run.

Info

Refer to this documentation to get more details about how to deploy an external library.

Custom shell

The custom shell must be located on an Operator server, inside a channel configuration directory :

├── pp-conf
│   └── tenants
│       └── mytenant
│           └── channels
|               └── mychannel
|                   └── myshell

You may use the following pattern to customize your own launcher :

#!/bin/bash

#
# SET YOUR EXTERNAL RESOURCES HERE
#

SHIVA_EXTLIB="/path/to/punch-binaries-6.1.0/extlib/shiva"
JAR_PATH="my_app/my_java_application.jar"
log4j2_conf_user="your log conf"

#
# BIN MANAGEMENT
#

serviceJar=($(ls -1 ${SHIVA_EXTLIB}/${JAR_PATH} 2> /dev/null )) 
if [ -z ${serviceJar:-} ] ; then
    echo "FATAL ERROR : Unable to find ${JAR_PATH} in ${SHIVA_EXTLIB}." 1>&2
    exit 1
fi

#
# LOG MANAGEMENT
#

log4j2_conf_default="${PUNCHPLATFORM_LOG4J_CONF_DIR}/log4j2.properties"
if [ "${log4j2_conf_user}" != "your log conf" ] ; then
  log4j2_conf=${log4j2_conf_user}
else
  log4j2_conf=${log4j2_conf_default}
fi

logOpts=(
    "-Dlog4j.configuration=file://${log4j2_conf}"
    )

#
# EXECUTE JAR
#

exec java "${logOpts[@]}" -jar ${SHIVA_EXTLIB}/${JAR_PATH} $@

retcode=$?
exit ${retcode}

Make your shell executable by the Shiva daemon user :

cd /path/to/punch-shiva-6.1.0/bin
chmod +x my_shell
chown shiva_user:shiva_user my_shell

Channel Structure

The custom channel_structure.json must be located on an Operator server, inside a channel configuration directory :

├── pp-conf
│   └── tenants
│       └── mytenant
│           └── channels
|               └── mychannel
|                   ├── myshell
|                   └── channel_structure.json

You may use the following pattern to customize your own channel :

{
    "version": "6.0",
    "start_by_tenant" : false,
    "stop_by_tenant" : true,
    "applications": [
        {
            "name": "my_app",
            "runtime" : "shiva",
            "command": "my_shell",
            "agrs": [
                "myarg1", "myarg2"
            ],
            "cluster": "local",
            "shiva_runner_tags": [
                "local"
            ]
        }
    ]
}

Info

Check more information about channel structure in Channels documentation

Check the validity of your new channel :

channelctl -t my_tenant status

channel:my_channel ................................................. STOPPED

You can now start your custom Shiva application using this new channel !

channelctl -t mytenant start --channel mychannel