Using the "No UI" Dev Client


Introduction

To allow for the deployment and upgrading of apps directly from the command line Helium provides a "no ui" version of the Helium Dev Client. As with the normal Dev Client, it's provided as a jar file that needs at minimum the Java 8 Runtime Environment (JRE) in order to run.



Basic Usage

Basic usage involves running the provided jar while specifying the command and relevant arguments:

java -jar NoUiDevClient.jar <command> <argument string>

Valid values for <command> as specified above are:

  • help
  • build
  • release
  • createapp
  • upgrade

A valid argument string contains zero or more key value pairs to identify the argument being specified and the value for that argument.

The key is used to identify which command specific argument is being specified and can be represented using the alias or name for that argument.

Alternatively arguments can be specified using environment variables where the variable name conforms to a specific standard. This is discussed more in the following section. 

Output varies for each command but in all cases, if the command was successfully executed the last line of output will contain the following:

Success <optional id for created entity>

The optional id will only be displayed in case an entity was created on the server as part of the command execution. In that case the id will represent the unique UUID of the entity on the server.

Currently this only applies to the release and createapp commands.


Specifying Arguments

As mentioned in the previous section, arguments can be specified in different ways. The examples below demonstrates this using the help command.

The help command can be run without any arguments.

In addition, an optional argument can be provided to specify for which command help should be displayed. Usage details for the help command is as follows:

-------------------------------------------------------------------------------------------------------
Alias    | Name                            | Description                                    | Required 
-------------------------------------------------------------------------------------------------------
c        | command                         | Command for which to display help              | false 
-------------------------------------------------------------------------------------------------------

From this we can see that the alias for the single argument supported by the help command is 'c' and the name is 'command'. We cal also see that the argument is not required.

Specifying Arguments Using the Argument Alias

In order to run a command using an argument alias, the alias should be preceded by a '-'.

Command using an argument alias
java -jar NoUiDevClient.jar help -c build

Specifying Arguments Using the Argument Name

In order to run a command using an argument name, the name should be preceded by a '--'.

Command using an argument name
java -jar NoUiDevClient.jar help --command build

Specifying Arguments Using Environment Variables

In addition to the above methods, arguments can also be specified using environment variables. Note that the name of the variable must start with "heliumDev" followed by the argument name starting with upper case:

Command using an environment variable
heliumDevCommand=build
export heliumDevCommand
java -jar NoUiDevClient.jar help

Values specified as arguments in the argument string, takes precedence over any environment variable values.

Validation And Error Messages

The following validation is performed when processing arguments:

  • All required arguments must be specified using one of the three methods discussed above
  • All arguments must be specified as a key value pair
  • Instead of ignoring argument that do not belong to the specified command an error message will be displayed and the command will not be executed. This is included as a safety measure to avoid unintended usage.

The following error messages demonstrate these exceptional cases:

Invalid Argument Example

java -jar NoUiDevClient.jar help -f help
The provided key, "f", is not valid for the command, "help".

Argument Without Value Example

java -jar NoUiDevClient.jar help -c
Unexpected end of argument string at position, 2. Expected a token of type argument value.

Omitting a Required Argument Example

java -jar NoUiDevClient.jar build
The required key, "l", for command, "build", representing "location (Source location)", was not specified.


Help Command

The help command provides usage details for the tool. If an optional command  argument is specified, usage details specific to the specified command is displayed.

Below is the output for the help command with the help command specified as optional argument:

help:
-------------------------------------------------------------------------------------------------------
Alias    | Name                            | Description                                    | Required 
-------------------------------------------------------------------------------------------------------
c        | command                         | Command for which to display help              | false 
-------------------------------------------------------------------------------------------------------


Build Command

The build command compiles source code found at the specified location. It can also optionally fetch any shared libraries before attempting to build. To fetch shared libs the repoServer , repoUserName  and repoPassword  must be specified. If any one of these are omitted, the command will build the specified source code without fetching any shared libraries. The debug argument sets the debug global context to the specified value (true/false). See: Using the HeliumDev Client and Deploying Apps#DebugMode. Similarly the verbose argument sets the global verbose variable to the specified value (true/false). See: Using the HeliumDev Client and Deploying Apps#VerboseMode. Both the debug and the verbose arguments are only available from version 1.28 of the dev client: 1.28 Release Notes
The runTests argument sets the test global context to the specified value (true/false). See: Using the HeliumDev Client and Deploying Apps#TestMode. This is only available from version 1.31 of the dev client: 1.31 Release Notes

Below is the output for the help command with the build command specified as optional argument:

build:
-----------------------------------------------------------------------------------------------------------------------
Alias    | Name                            | Description                                    				| Required 
-----------------------------------------------------------------------------------------------------------------------
rs       | repoServer                      | Optional URI for shared libs repo              				| false 
ru       | repoUserName                    | Optional username for shared libs repo         				| false 
l        | location                        | Source location                                				| true 
rp       | repoPassword                    | Optional password for shared libs repo         				| false 
dbg		 | debug						   | Optional argument to switch on/off debug mode  				| false
v		 | verbose						   | Optional argument to switch on/off verbose mode (default on)	| false
t        | runTests						   | Optional argument to switch on/off test mode (default off)		| false
-----------------------------------------------------------------------------------------------------------------------

Build Usage Example

Example usage
java -jar NoUiDevClient.jar build \
-l "/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk" \
-rs "http://jm.stb.mezzanineware.com" \
-ru "username" \
-rp "password" \
-dbg true \
-v false \
-t true
Example output
Purging shared libraries
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JMath-1.2/utilities/JMath.mez
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JMath-1.2/utilities
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JMath-1.2
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/utilities/JAudit.mez
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/utilities
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/sql-scripts/RecordSchemaUpgrade.sql
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/sql-scripts
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/model/SchemaUpgradeRecord.mez
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/model
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs
Fetching shared libraries
Loading source files...
Tests run
Compiling the application...
The project "Project" compiled successfully
Compiling the Jasper reports...
The project "Project's" Jasper reports compiled successfully
Success

Note from the output above that the internal representation of the project in the Dev Client uses a fixed name "Project". Similarly the server and app is internally represented using the names "Server" and "App" respectively.

This is done to simplify the internal configuration of the Dev Client for "no ui" usage and has no effect on the values that end up on the server.


Release Command

The release command releases source code to a Helium server. It also builds the source code and attempts to fetch any shared libraries if the optional repoServer , repoUserName  or repoPassword  arguments are specified.

Below is the output for the help command with the release command specified as optional argument:

release:
-------------------------------------------------------------------------------------------------------
Alias    | Name                            | Description                                    | Required 
-------------------------------------------------------------------------------------------------------
p        | password                        | Password                                       | true 
rs       | repoServer                      | Optional URI for shared libs repo              | false 
s        | server                          | Server URI                                     | true 
ru       | repoUserName                    | Optional username for shared libs repo         | false 
d        | releaseDescription              | Release description                            | true 
u        | userName                        | Username                                       | true 
g        | releaseGroup                    | Release group                                  | true 
l        | location                        | Source location                                | true 
n        | releaseName                     | Release name                                   | true 
rp       | repoPassword                    | Optional password for shared libs repo         | false 
-------------------------------------------------------------------------------------------------------

Release Usage Example

Example usage
java -jar NoUiDevClient.jar release \
-l "/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk" \
-rs "http://jm.stb.mezzanineware.com" \
-ru "username" \
-rp "password" \
-s "http://jm.stb.mezzanineware.com" \
-u "username" \
-p "password" \
-n "Test Release V1" \
-d "Test Release Version 1" \
-g "test"
Example output
Purging shared libraries
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JMath-1.2/utilities/JMath.mez
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JMath-1.2/utilities
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JMath-1.2
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/utilities/JAudit.mez
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/utilities
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/sql-scripts/RecordSchemaUpgrade.sql
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/sql-scripts
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/model/SchemaUpgradeRecord.mez
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1/model
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs/JAudit-1.1
/Users/jacques/Workspace/helium-apps/gym-log-3.0-trunk/shared-libs
Fetching shared libraries
Loading source files...
Compiling the application...
The project "Project" compiled successfully
Compiling the Jasper reports...
The project "Project's" Jasper reports compiled successfully
Performing release

Loading source files...
Publishing a new release of "Project" to the "Server" server
An official release of "Project" has been published to "Server".
Success 688919e6-821b-4fe5-9271-bc28bf195555


Create App Command

The createapp command creates a basic app without an app release on a Helium server.

Below is the output for the help command with the createapp command specified as optional argument:

createapp:
-------------------------------------------------------------------------------------------------------
Alias    | Name                            | Description                                    | Required 
-------------------------------------------------------------------------------------------------------
p        | password                        | Password                                       | true 
s        | server                          | Server URI                                     | true 
d        | appUserFriendlyDescription      | User friendly app description                  | false 
u        | userName                        | Username                                       | true 
f        | appFqdnName                     | App fully qualified domain name                | false 
g        | appReleaseGroup                 | App release group                              | true 
n        | appName                         | App name                                       | true 
ds       | appDataSource                   | App datasource name                            | true 
-------------------------------------------------------------------------------------------------------

Create App Usage Example

Example usage
java -jar NoUiDevClient.jar createapp \
-s "http://jm.stb.mezzanineware.com" \
-u "username" \
-p "password" \
-n "My Test App" \
-g "test" \
-ds "default"
Example output
Success 9d8a0b2f-dd0b-433e-b949-bdd034a88c15


Upgrade Command

The upgrade command upgrades the specified app with the specified release. The app and release must both be on the server and are identified by the app and release arguments for which the values represent the unique app id and release id respectively.

Note that the value that is specified for the releaseGroup argument must match the release group of the app and release being used in the upgrade.

Below is the output for the help command with the createapp command specified as optional argument:

upgrade:
------------------------------------------------------------------------------------------------------------
Alias    | Name                            | Description                                         | Required 
------------------------------------------------------------------------------------------------------------
p        | password                        | Password                                            | true 
a        | app                             | Unique ID (UUID) of the app to upgrade              | true 
r        | release                         | Unique ID (UUID) of the release to use for upgrade  | true 
s        | server                          | Server URI                                          | true 
u        | userName                        | User name                                           | true 
g        | releaseGroup                    | Release group                                       | true 
------------------------------------------------------------------------------------------------------------

Upgrade Usage Example

Example usage
java -jar NoUiDevClient.jar upgrade \
-s "http://jm.stb.mezzanineware.com" \
-u "27763303624" \
-p "123456" \
-a "9d8a0b2f-dd0b-433e-b949-bdd034a88c15" \
-r "688919e6-821b-4fe5-9271-bc28bf195555" \
-g "test"
Example output
Success


Example Using a Bash Script

The example script below, builds source code, releases it to the server, creates an app and upgrades the app. At each step, the output is evaluated to ensure that the command has executed successfully. If not, execution halts and the output received from the tool is displayed for debugging purposes.

noui-dev-example.sh

The output of the script in case of successful execution is as follows:

--> Building source code
--> Build succeeded
--> Releasing source code to server
--> Source code successfully released
--> App release id:  a44b1a4e-72b3-40d9-9c2d-295563bd3773
--> Creating app on server
--> App successfully created
--> App id:  3ccb2eb1-3b1b-4cc0-a195-f5309ffc3500
--> Upgrading app with release
--> App successfully upgraded