Perform a Headless Build

A headless build is a method of building and publishing an app without launching the Eclipse environment that hosts Quantum Visualizer. Instead, Ant manages the build and publish process. Ant is an open-source software tool developed by the Apache Software Foundation taht automates build processes.

Conducting headless builds has a number of advantages.

A developer does not have to open Quantum Visualizer to build the application. This helps to integrate the compilation and building of Quantum Visualizer projects with continuous build and integration tools like Cruise Control, Maven, and Hudson.
A non-developer can handle release management.
You can specify the binaries to be copied to a specific location of your choice, which reducing the manual effort of copying the files to a specific location.
You can easily deploy an application to multiple servers.
You can build the applications for multiple platforms with a single command.
You can build applications with binaries protected mode enabled.
You will need to configure few other settings for this to work. See Application Security for more information.

Running a headless build involves the following tasks:

Prerequisites for a Headless Build
Configure the HeadlessBuild.properties File
Configure the HeadlessBuild-Global.properties File
Increase Heap Memory
Build the Application

NOTE: Before using conducting a headless build, ensure you have the files mentioned in Prerequisites

For headless builds, the following two files are required:

HeadlessBuild.properties
HeadlessBuild-Global.properties

Most of the effort in preparing a headless build involves configuring these files. Ant gives you the flexibility to build an app or publish it. The decision of building or publishing is configured using Modes. The modes are:

Mode 0 - The application is built, and all the binaries are generated.
Mode 1 - The application is published on Quantum Fabric.
Mode 2 - Through this combination of modes 0 and 1, the application is built and published on the Quantum Fabric.
Mode 3 - This mode generates a web archive file that is combined with the Quantum Fabric archive and also generates either a .war or .ear file, depending on what you specify. You must manually deploy the app on the server, or use a separate script.
Mode 4. A combination of modes 0 and 3. The application is built and a web archive file that is combined with the Quantum Fabric archive also is generated, along with either a .war or .ear file, depending on what you specify. You must manually deploy the app on the server, or use a separate script.

Prerequisites

Following are the prerequisites for doing headless build:

Before doing headless builds, you have to do a blank publish to Quantum Fabric to use services in your app. Building the application is not required in this case.
Quantum Visualizer is installed on your computer.
Headless builds are supported only on Kony Studio 4.1 plug-ins and above.
Ensure that there is no space in the file or folder names, and in the parents folder name.
If you are doing headless builds for iPhone or iPad, ensure that the Xcode in the Mac machine is available in the /Applications directory instead of the /Developers directory. To change the directory, use the command. xcode-select.
For iOS, make sure to obtain a 10-digit development team identifier from Apple. The Team ID can be found in the Membership Details of your Apple Developer account.

Note: The Team ID must not include spaces. Otherwise, the IPA generation in Quantum Visualizer fails.

Configure the HeadlessBuild.properties File

The following sections explain where to find the HeadlessBuild.properties file and how to configure it. Depending on what mode you are building (either 0, 1, 2, 3, or 4), you need to set particular values in the HeadlessBuild.properties file. These are detailed in Configure the Mode.

How to Find the HeadlessBuild.properties File
Configure the Mode

How to Find the HeadlessBuild.properties File

The file HeadlessBuild.properties is stored in the project folder of your workspace. For example, if the name of your project is HelloWorld, and the name of your workspace folder is Workspace, the path in Microsoft Windows will be:

C:\Users\<username>\Workspace\HelloWorld

Example of HeadlessBuild.properties file

Following is an example of sections that are present in the HeadlessBuild.properties file and the values that can be used.

IMPORTANT: If the values for any variables are left blank, then the values set through Quantum Visualizer will be retained while building the application.

#Note: Please escape '\' with '\\' in all file paths#
#This file represents the Application level properties used by headless build.
project.name=app1

#mode 0-Build; 1-Publish; 2-Build & Publish; 3-Combine Web Application+Kony Server Archive; 4-Build & Combine Web Application+Kony Server Archive;
#mode-0: Application will be built for the selected build platforms
#mode-1: Based on publish.web, publish.service properties, app will be published & services will be published
#mode-2: Application will be built for selected build platforms and publish will be performed.
#mode-3: Combines web archive of app & kony server archive and generates combined war/ear file
#mode-4: Application will be built & Generated web archive will be combined with Kony server archive and final war/ear will be generated
mode=0

#build mode [release | debug]
build.mode=release

#Application details
appid=app1
#Please ensure that this is incremented while doing multiple Headless builds involving the modes 0 or 1 or 2
version=1.0.0
map_google_key=
default_locale=
#The android packagename can follow the pattern com.<orgname>.<appid>
android.packagename=com.orgname.app1

#Cloud Mode credentials (Applicable only for cloud)
cloud.username=
cloud.password= 

#Provide Quantum Fabric specific details 
konyfabric.url=

# Environment.Name used for publishing example using the format LocalDevEnv
# For example, if your Quantum Fabric Environment URL is:
# https://mycompany.konycloud.com
# then the value is as follows: environment.name=mycompany
environment.name=
account.id=
mf.appname=

#Specify the platforms for which the headless build needs to run.
#Mobile Channel.
iphone=false
android=false

#Tablet Channel.
ipad=false
androidtablet=false

#Selecting Windows10 will also trigger builds for X86,X64,ARM architectures.
windows10=false

#Desktop Channel.
desktop_kiosk=false
desktopweb=false 

#Wearbles channel.
iphonewatch=false

#Universal Channel.
universal.iphone=false
universal.android=false

#App Extensions
iosappextension=false

#Provide iOS deployment target details in the case of iPhone or iPad.

#Ex: 8.0, 9.0, 10.0
mac.iosdeploymenttarget=
#Ex: 2.0, 3.0, 4.0
mac.watchosdeploymenttarget=
#Ex: 4.0, 5.0
mac.swiftversion=

#Provide following details to generate IPA file in the case of iPhone or iPad.
mac.ipaddress=
mac.username=
mac.password=

keychain.password=
#Possible values for method are "app-store", "ad-hoc", "enterprise", "development"
method=
#Examples for development.team are "G9B5P7QDV2", "PM7453S8QE"
development.team=
#Possible values are true/false
genipaiphone=false
genipaipad=false

#middleware server properties
middleware_server_ip=192.168.251.1
middleware_http_port=80
middleware_https_port=443
#used in cloud mode
cloud.middleware.url=


middleware_web_context=middleware
mobileweb_web_context=app1

#To build binaries with protected mode enabled. 
protectedmodeenabled.ios=true
protectedmodeenabled.android=true
protectedmodeenabled.web=true
#If not specified, by default final binaries will be copied to 'binaries' folder inside project
binaries.location=

#Combine Web Application+Kony Server Archive. Applicable for mode = 3 or 4 #
#Full path of middleware archive (war/ear).If project has Kony session Manager, 
#provide with-cache archive, for Http session Manager, provide without-cache archive.
combinewar.middlewarearchive=
combinewar.context=
#combinewar.war,combinewar.ear are mutually exclusive(Only one of them should be true)
combinewar.war=false
combinewar.ear=false
#Provide full path of dependant libraries,Separate with semicolon(;) if there are multiple libraries
combinewar.dependencylibraries=

# Supported context paths for Quantum Fabric components, if customized.
context.path.identity
context.path.workspace
context.path.accounts
context.path.console

#Siteminder login URL if your on-premise Quantum Fabric is protected by siteminder.
login.siteminder.url

IMPORTANT: If you do not want to store your password in the headless build.properties file, you can use mfcli to encrypt your password. You can download the mfcli.jar from https://community.kony.com/downloads.

Ensure that you use the corresponding version of MFCLI as that of the Visualizer. i.e 7.x viz, 7.x mfcli, 8.x viz, 8.x mfcli.

To encrypt the password using mfcli (using default password.encryption.key),
java -jar mfcli.jar encrypt "Kony@1234" Encrypted password is: en1801f1abee7b9e12426c062509e1b18epd

Configure the Mode

Depending on what mode you are building for (either 0, 1, 2, 3, or 4), you need to set values in the HeadlessBuild.properties file.

Mode 0 Properties

In Mode 0, the application is built, binaries are generated at the location specified in HeadlessBuild.properties, additionally if no location is specified they will also be copied to <drive>/<workspace>/<project>/binaries, apart from the temp folder. To configure build.properties for mode 0, in addition to setting mode=0, simply set the platform you are building for to true.

For example, iphone=true

Mode 1 Properties

In mode 1, the application or services are published, the application or services are published to Quantum Fabric, depending on the Quantum Fabric details in HeadlessBuild.properties file. The properties are in addition to setting mode=1.

NOTE: In order to publish, initial build has to be done in mode 0 before you execute mode 1 and mode 2.

Mode 2 Properties

Because mode 2 is a combination of modes 0 and 1, you must set the properties described in the Mode 0 properties and Mode 1 properties, and set the property mode=2 in order to build and publish to Quantum Fabric. For example:

#Cloud Mode credentials (Applicable only for cloud)
cloud.username=username@kony.com
cloud.password=Abc@123

#Provide Quantum Fabric specific details 
konyfabric.url=https://mbaastest25.konylabs.net:443

# Environment.Name used for publishing example using the format LocalDevEnv
# For example, if your Quantum Fabric Environment URL is:
# https://mycompany.konycloud.com
# then the value is as follows: environment.name=mycompany
environment.name=

Mode 3 Properties

In mode 3, Quantum Visualizer combines the web archive and the Quantum Fabric archive which presumes the web archive is already built and generates a combined war/ear file. If the application is not built or the web archive is not available, then Quantum Visualizer displays an error. To configure HeadlessBuild.properties for mode 3, in addition to setting mode=3, the following properties must be set:

#Full path of middleware archive (war/ear). If project has Kony session Manager, provide with-cache archive, for Http session Manager, provide without-cache

archive.combinewar.middlewarearchive= <Path to middleware archive (war/ear, based on whether combinewar.ear / combinewar.war properties)>
combinewar.context= <Provide context name with which final war/ear will be generated.>

#combinewar.war and combinewar.ear are mutually exclusive(only one of them should be true)
combinewar.war=false
combinewar.ear=false

#Provide full path of dependent libraries, separated by semicolons(;) if there are multiple libraries
combinewar.dependencylibraries= <All MobileWeb dependency jars (full path) separated by semicolons(;) should be provided.>

Mode 4 Properties

Because mode 4 is a combination of modes 0 and 3, you must set the properties described in the headings Mode 0 Properties and Mode 3 Properties, and set the property mode=4.

Configure Quantum Fabric Parameters

To configure Quantum Fabric parameters, follow these steps:

Open HeadlessBuild.properties file.
Provide user-name at cloud.username.
Provide password at cloud.password.
Provide Quantum Fabric URL at konyfabric.url.

Provide Quantum Fabric environment name at environment.name.

NOTE: Providing user-name, password, and Quantum Fabric URL are mandatory to build an application from the command line.

#Cloud Mode credentials (Applicable only for cloud)
cloud.username=username@kony.com
cloud.password=Abc@123

#Provide Quantum Fabric specific details 
konyfabric.url=https://mbaastest25.konylabs.net:443

# Environment.Name used for publishing example using the format LocalDevEnv
# For example, if your Quantum Fabric Environment URL is:
# https://mycompany.konycloud.com
# then the value is as follows: environment.name=mycompany
environment.name=

In order to enable services, you need to publish the app at least once from IDE.

Configure the HeadlessBuild-Global.properties File

The following sections explain where to find the HeadlessBuild-Global.properties file and how to configure it.

How to Find the build.properties File

The file HeadlessBuild-Global.properties is stored in the root folder of your workspace. For example, if the name of your workspace folder is Workspace, the path in Microsoft Windows would be something like this:

C:\Users\<username>\Workspace

Example of HeadlessBuild-Global.properties File

The following illustrates the sections that comprise the global.properties file and the values that can be used.

#The file represents the workspace level properties relevant for Headless Build
#Note: Please escape '\' with '\\' in file paths (Ex: C:\\workspace\\project)

 #Specify the eclipse workspace path where the project exists.
workspace.location=

#Full Path to a jar file whose name starts with 'org.eclipse.equinox.launcher_' in eclipse plugins folder
#Example: D:\\eclipse\\plugins\\org.eclipse.equinox.launcher_1.1.0.v20100507.jar
eclipse.equinox.path=

#Android Home-Please specify the path of Android SDK. This is needed only if Android Builds are being triggered
android.home=

Increase Heap Memory

If required, you can increase the heap memory available to your build by modifying the run file (either run.bat or run.sh). To increase the heap memory, type the following memory options in the run file.

java -Xms40m -Xmx512m -Dinput.file=%1 -Dglobal.file=%4 -cp %3 org.eclipse.core.launcher.Main -data %2 -application com.pat.tool.keditor.konyapplication

Generating IPA

To generate IPA, following fields need to be configured before triggering the build.

Open HeadlessBuild.properties file.
Provide Mac User-name at mac.username.
Provide Mac password at mac.password.

Provide IP address at mac.ipaddress.

#Provide following details to generate IPA file in the case of iPhone or iPad.
mac.ipaddress=xx.xx.xx.xx
mac.username=Username
mac.password=p@ssword

Provide profile key chain password, export method, and Team ID.

keychain.password=p@ssword
#Possible values for method are "app-store", "ad-hoc", "enterprise", "development"
method="development"
#Examples for development.team are "G9B5P7QDV2", "PM7453S8QE"
development.team="G9B5P7QDV2"

Based on the requirement, user should set genipaiphone or genipaipad value to true.
```
#Possible values are true/false
genipaiphone=true
genipaipad=false
```
Value of the respective channel should be set to true.
```
#Mobile Channel.
iphone=True
android=false
```
Build the application to generate IPA.

Build the Application

To build the application, follow these steps:

Navigate to your application's workspace.
Make sure the files run.bat, build.xml, HeadlessBuild.properties, and HeadlessBuild-Global.properties are present in the workspace.
Update the HeadlessBuild-Global.properties file with details like workspace location, eclipse.equinox.path, and preference. For example.
workspace.location = c:\\Myprojects\\Releases
eclipse.equinox.path = c:\\Eclipse_6.5\\plugins\\org.eclipse.equinox.launcher_1.1.1.R36x_v20101122_1400.jar
Update the HeadlessBuild.properties file with details like project.name, application, and platforms that you are building the application for.
Open the command prompt in the workspace.
Type ant in the command prompt. You can see the status of the build on the command prompt window.

NOTE: If you want to write the console statements to a file for later viewing, such as for evaluating errors, use the command ant > <drive:\filename>
If the app is built for Android, you can expect the folder to have the following structure (unless otherwise defined in the binaries section of the HeadlessBuild.properties file).