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 '-'.
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 '--'.
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:
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
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
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
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"
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
java -jar NoUiDevClient.jar createapp \ -s "http://jm.stb.mezzanineware.com" \ -u "username" \ -p "password" \ -n "My Test App" \ -g "test" \ -ds "default"
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
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"
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.
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