This chapter is intended for those who want to integrate their own Product to be deployed with BDeploy. Therefor a couple of YAML files are required. These files describe your product and all its applications together with some additional metadata. These artifacts are required:

app-info.yaml

product-info.yaml

product-version.yaml

application-template.yaml

instance-template.yaml

parameter-template.yaml

instance-variable-template.yaml

instance-variable-definitions.yaml

system-template.yaml

product-validation.yaml

This picture illustrates the relation between the various YAML files which are (can be) used to define a product. Almost all product information and data revolves around BDeploy enabling a user to configure instances and applications.

The app-info.yaml file is one of the most important parts of BDeploy. It describes an Application, especially its start command. This Application may be any application which contains an executable (script, executable, etc.) and which allows 'installation' by copy to a directory. This is important, as BDeploy will 'install' an application by ultimately copying the application to an automatically determined internal directory and launch it from there.

Basically, app-info.yaml allows you to specify which executable to run, and which parameters could potentially be used to configure the Application. The app-info.yaml does not specify an actual configuration, but describes all possible parameters for an Application.

The app-info.yaml file must be placed in the root directory of the Application it describes.

name: "My Application" <1>
type: CLIENT <2>
pooling: GLOBAL <3>

supportedOperatingSystems: <4>
  - LINUX
  - WINDOWS

branding: <5>
  icon: "branding/my-icon.ico"
  splash:
    image: "branding/my-splash.bmp"
    textRect:
      x: 20
      y: 174
      width: 400
      height: 20
      foreground: "#000000"
    progressRect:
      x: 15
      y: 194
      width: 450
      height: 12
      foreground: "#333333"

processControl: <6>
  supportedStartTypes:
   - INSTANCE
  supportsKeepAlive: true
  noOfRetries: 5
  gracePeriod: 3000
  attachStdin: false
  startupProbe: <7>
     endpoint: "Startup Endpoint"
  livenessProbe: <8>
     endpoint: "Liveness Endpoint"
     initialDelaySeconds: 5
     periodSeconds: 10
  configDirs: "/dir1,/dir2" <9>
  supportsAutostart: true

startCommand: <10>
  launcherPath: "{{WINDOWS:launch.bat}}{{LINUX:launch.sh}}"
  parameters:
    - id: "my.param.1"
      name: "My numeric parameter"
      longDescription: "This is a numeric parameter"
      groupName: "My Parameters"
      parameter: "--number"
      defaultValue: "{{X:instance-number}}"  <11>
      type: NUMERIC
    - id: "my.param.2"
      name: "My textual parameter"
      longDescription: "This is a textual parameter"
      groupName: "My Parameters"
      parameter: "--text"
      mandatory: true
      suggestedValues:
        - "Value 1"
        - "Value 2"
    - id: "my.param.3"
      name: "My conditional parameter"
      longDescription: "This is only visible and configurable if my.param.2 has value 'Value 1'"
      parameter: "--conditional"
      mandatory: true
      condition: <12>
        parameter: "my.param.2"
        must: EQUAL
        value: "Value 1"
    - template: param.template <13>

stopCommand: <14>
  ...

endpoints: <15>
  http:
    - id: "my-endpoint" <16>
      path: "path/to/the/endpoint"
      port: "{{V:port-param}}" <17>
      secure: false
    - id: "Startup Endpoint"
      type: PROBE_STARTUP <18>
      path: "startup/endpoint"
      port: "{{V:port-param}}"
      secure: false
    - id: "Liveness Endpoint"
      type: PROBE_ALIVE <18>
      path: "liveness/endpoint"
      port: "{{V:port-param}}"
      secure: false

runtimeDependencies: <19>
  - "adoptium/jre:1.8.0_202-b08"

1. A human readable name of the Application. Will be displayed in the Configure Application pane, and is also used as default name for any process instantiated from this Application.
2. The type of the application, may be SERVER or CLIENT. SERVER applications can be deployed to Nodes (including the master) and there be started as server processes. CLIENT applications in comparison cannot be deployed on a Node, but run on a client PC instead.
3. The supported pooling type for server applications. Supported values are GLOBAL, LOCAL and NONE. GLOBAL means that the application is fully poolable and may be installed once (per application version) and used by multiple instance versions of multiple instances. LOCAL means that there is limited pooling support, and the application may only be re-used inside a single instance (by multiple instance versions of that instance, e.g. when changing only configuration). NONE means that there is no pooling support and the application will be installed freshly per instance version, even if just configuration values changed. This gives some control over how to deploy applications which write data into their installation directory at runtime - which should of course be avoided for better pool-ability. This setting is currently ignored by the client application launcher. Client applications are always globally pooled.
4. List of supported operating systems. This list is solely used to verify during import of the Product, that the Application actually supports the operating system under which it is listed in the product-version.yaml.
5. Only relevant for CLIENT applications: The branding attribute controls the appearance of CLIENT type Applications when downloaded by the user. It can be used to specify an icon (used to decorate desktop links created by the client installer), and a splash screen. For the splash, you can fine tune the exact location used to display progress text and a progress bar while the application is downloaded to the client PC by the Launcher CLI. Paths are interpreted relative to the root folder of the Application.
6. Only relevant for SERVER applications: Process control parameters allow to fine tune how SERVER type Applications are started and kept alive by BDeploy. For details, see the list of processControl attributes.
7. A startup probe can specify an HTTP Endpoint of type PROBE_STARTUP which is queried by BDeploy if specified until the endpoint returns a status code >= 200 and < 400. Once this happens, the startup probe is considered to be successful and the Process state advances from starting to running. The exact response reported by the Process is available from the Process details panels Process Probes section.
8. A liveness probe can specify an HTTP Endpoint of type PROBE_ALIVE along with an initial delay in seconds and an interval in which the probe is queried. BDeploy starts querying liveness probes only after the application entered running state. This happens either automatically when the process is started (if no startup probe is configured), or once the existing startup probe succeeded. The liveness probe is queried every periodSeconds seconds, and the application is considered to be alive if the endpoint returns a status code >= 200 and < 400. If the probe fails, the Process status is updated to indicate the problem. The exact response reported by the Process is available from the Process details panels Process Probes section.
9. Allowed configuration directories preset - only valid for CLIENT applications. These relative sub-directories of the configuration files directory tree will be made available to this application when run on a client PC. This can later also be configured per process using the Allowable Configuration Directories configuration.
10. The start command of the Application. Contains the path to the executable to launch, as well as all known and supported parameters. For details, see the full list of parameter attributes. To apply e.g. instance-specific values, Variable Expansion is a powerful tool. It can be used for the launcherPath and each parameter's defaultValue. In the Web UI it can be used for the parameter values.
11. Variable Expansion can also be used to expand to Instance Variables in default values. These instance variables are required to exist once the application is configured in an instance. They can either be pre-provided using Instance Templates or need to be manually created when required.
12. A conditional parameter is a parameter with a condition on it. The condition always refers to another parameter of the same application. The parameter with the condition set will only be visible and configurable if the condition on the referenced parameter is met.
13. A product can provide parameter templates which can be re-used by referencing their ID inline in applications parameter definitions. All parameter definitions in the template will be inlined at the place the template is referenced.
14. The optional stop command can be specified to provide a mechanism for a clean application shutdown once BDeploy tries to stop a process. This command may use Variable Expansion to access parameter values of the startCommand (e.g. configured 'stop port', etc.). It is not configurable through the Web UI though. All parameter values will have their (expanded) default values set when the command is run. If no stopCommand is specified, BDeploy will try to gracefully quit the process (i.e. SIGTERM). Both with and without stopCommand, BDeploy resorts to a SIGKILL after the gracePeriod has expired.
15. Optional definition of provided endpoints. Currently only HTTP endpoints are supported. These endpoints can be configured on the application later, including additional information like authentication, certificates, etc. BDeploy can later on call these endpoints when instructed to do so by a third-party application.
16. The ID of the endpoint can be used to call the endpoint remotely by tunneling through potentially multiple levels of BDeploy servers.
17. Variable Expansion can be used on most of the endpoint properties.
18. The type of the endpoint can be used to control how the endpoint is handled by BDeploy.
19. Optional runtime dependencies. These dependencies are included in the Product when building it. Dependencies are fetched from Software Repositories. launcherPath and parameter defaultValue (and of course the final configuration values) can access paths within each of the dependencies by using the {{M:adoptium/jre}} Variable Expansion, e.g. launcherPath: {{M:adoptium/jre}}/bin/java. Note that the declared dependency does not need to specify an operating system, but must specify a version. This will be resolved by BDeploy to either an exact match if available, or a operating system specific match, e.g. adoptium/jre/linux:1.8.0_202-b08 on LINUX. When referencing the dependency in a Variable Expansion, neither an operating system nor a version is required - in fact it must not be specified.

/path/to/java/bin/java -Dmy.prop=value -jar application.jar

startCommand:
  launcherPath: "{{M:openjdk/jre:1.8.0_u202-b08}}/bin/java{{WINDOWS:w.exe}}"
  parameters:
    - id: "my.prop"
      name: "My Property"
      parameter: "-Dmy.prop"
      mandatory: true
    - id: "my.jar"
      name: "Application JAR"
      parameter: "-jar"
      defaultValue: "application.jar"
      valueAsSeparateArg: true
      mandatory: true
      fixed: true <1>

condition:
  parameter: "my.param.2"
  must: EQUAL
  value: "Value 1"

condition:
  expression: "{{V:my.param.2}}"
  must: EQUAL
  value: "Value 1"

The product-info.yaml file describes which Applications are part of the final Product, as well as some additional Product metadata.

name: My Product <1>
product: com.example/product <2>
vendor: My Company <3>

applications:
  - my-app1 <4>
  - my-app2

configTemplates: my-config <5>
pluginFolder: my-plugins <6>

applicationTemplates:
  - 'my-templates/app-template.yaml' <7>
instanceTemplates:
  - 'my-templates/template.yaml' <8>

parameterTemplates:
  - 'my-templates/param-template.yaml' <9>
instanceVariableTemplates:
  - 'my-templates/variable-template.yaml' <10>
instanceVariableDefinitions:
  - 'my-definitions/instance-variable-definitions.yaml' <11>

versionFile: my-versions.yaml <12>

1. A human readable name of the Product for display purposes in the Web UI.
2. A unique ID of the Product which is used to base Instances of. This should not change, as changing the Product ID of an existing Instance is not supported.
3. The vendor of the product. Displayed in the Web UI and used when installing client applications.
4. The list of Applications which are part of the Product. These IDs can be anything, they just have to match the IDs used in the product-version.yaml referenced below.
5. Optional: A relative path to a directory containing configuration file templates, which will be used as the default set of configuration files when creating an Instance from the resulting Product.
6. Optional: A relative path to a directory containing one or more plugin JAR files. These plugins are loaded by the server on demand and provided for use when configuring applications which use this very product version.
7. A reference to an application template YAML file which defines an application-template.yaml.
8. A reference to an instance template YAML file which defines an instance-template.yaml.
9. A reference to a parameter template YAML file which defines a parameter-template.yaml.
10. A reference to an instance variable template YAML file which defines an instance-variable-template.yaml.
11. A reference to an instance variable definitions YAML file which defines an instance-variable-definitions.yaml
12. The product-version.yaml which associates the Application IDs (used above) with actual paths to Applications on the file system.

The product-version.yaml file associates Application IDs used in the product-info.yaml with actual locations on the local disc. This is used to find and import each included Application when importing the Product.

The reason why this file is separate from the product-info.yaml is because its content (e.g. version) is specific to a single product Build . Therefore the product-version.yaml ideally is created during the build process of the product by the build system of your choice. This is different to the app-info.yaml files and the product-info.yaml file as they are written manually.

version: "2.1.0.201906141135" <1>
appInfo:
  my-app1: <2>
    WINDOWS: "build/windows/app-info.yaml" <3>
    LINUX: "build/linux/app-info.yaml"
  my-app2:
    WINDOWS: "scripts/app2/app-info.yaml" <4>
    LINUX: "scripts/app2/app-info.yaml"

1. A unique Tag to identify the product version. There is no requirement for any version-like syntax here, it can be basically anything. It should just be unique per Product Version.
2. The Application ID must match the one used in product-info.yaml.
3. You may have different binaries for a single application depending on the target operating system. It is not required to provide every application for every operating system. You can just leave out operating systems you don't care about.
4. You can also use the exact same Application directory and app-info.yaml to satisfy multiple operating system targets for one Application.

This file defines a single Application Template. A product-info.yaml can reference multiple templates, from which the user can choose.

id: server-with-sleep <1>
application: server-app
name: "Server With Sleep (Oracle)" <2>
processName: "Server With Sleep" <2>
description: "Server application which sleeps before exiting"
preferredProcessControlGroup: "First Group" <3>

applyOn: <4>
  - LINUX

templateVariables: <5>
  - id: sleep-timeout
    name: "Sleep Timeout"
    description: "The amount of time the server application should sleep"
    defaultValue: 60
    suggestedValues:
    - '60'
    - '120'

processControl: <6>
  startType: MANUAL_CONFIRM
  keepAlive: false
  noOfRetries: 3
  gracePeriod: 30000
  attachStdin: true

startParameters: <7>
- id: param.sleep
  value: "{{T:sleep-timeout}}"

1. An Application Template must have an ID. This can be used to reference it from an Instance Template.
2. name is the value user sees when they choose the template in UI. processName is the name of the resulting process configuration.
3. The preferred process control group is used to determine which process control group to use when applying the application template. This is only used if a Process Control Group with this name exists in the instance configuration. Process Control Groups can be pre-configured in an instance-template.yaml.
4. A list of operating systems that this application may run on. If the node is running on an operating system that is not contained in the list, then the process will not be imported whenever an instance template references this application. If no list is present, then all operating systems are considered valid.
5. A template can define (and use) template variables which are mandatory input by the user when using the template. A template variable can be referenced in parameter value definitions using the {{T:varname}} syntax. If the parameter value is numeric, you can also use simple arithmetic operations on the template variable like {{T:varname:+10}} which will add 10 to the numeric value of the template variable.
6. A template can define arbitrary process control parameters to further control the default process control settings.
7. Start command parameters are referenced by their ID, defined in app-info.yaml. If a value is given, this value is applied. If not, the default value is used. If a parameter is optional, it will be added to the configuration if it is referenced in the template, regardless of whether a value is given or not.

id: fixed-sleep
name: "Server With 10 Seconds Sleep"
template: server-with-sleep <1>

fixedVariables: <2>
  - id: sleep-timeout
    value: 10

1. The template attribute specifies another application template (which must be registered in the product) to extend. All properties of that other template are merged into this application template. Properties of this template take precedence in case of a conflict.
2. fixedVariables, as also described for instance-template.yaml, allow to override the value of a specific template variable in this and the base template. Values queried from the user when applying this template will be ignored for any variable which has an overridden, fixed value.

Fixed variables allow overriding template variable input from the user to a fixed value.

The list of startParameters provides control over the parameters in the resulting process. This is different from the parameter definition in app-info.yaml as this list only provides information about presence and value of parameters when applying this template.

This file defines a single Instance Template. A product-info.yaml can reference multiple templates, from which the user can choose.

name: Default Configuration <1>
description: "Creates an instance with the default server and client configuration"

templateVariables: <2>
  - id: sleep-timeout
    name: "Sleep Timeout"
    description: "The amount of time the server application should sleep"
    defaultValue: 60

instanceVariables: <3>
  - id: var.id
    value: "MyValue"
    description: "The description of my instance variable"
    type: PASSWORD
  - template: var.template <4>

instanceVariableDefaults: <5>
  - id: var.id
    value: "A value other than above"

instanceVariableValues: <6>
  - id: def.id
    value: "A value that will update instance variable created from def.id definition"
  - id: other.def.id
    value: "{{T:sleep-timeout}}"

processControlGroups: <7>
  - name: "First Group"
    startType: "PARALLEL"
    startWait: "WAIT"
    stopType: "SEQUENTIAL"

groups: <8>
- name: "Server Apps"
  description: "All server applications"

  applications:
  - application: server-app
    name: "Server No Sleep"
    description: "Server application which immediately exits"
  - template: server-with-sleep <9>
    fixedVariables: <10>
      - id: sleep-timeout
        value: 10
  - application: server-app <11>
    name: "Server With Sleep"
    description: "Server application which sleeps before exiting"
    applyOn: <12>
      - LINUX
    processControl:
      startType: MANUAL_CONFIRM
    startParameters: <13>
    - id: param.sleep
      value: "{{T:sleep-timeout}}"
    applyTo: <14>
    - LINUX
- name: "Client Apps"
  type: CLIENT <15>
  description: "All client applications"

  applications:
  - application: client-app
    description: "A default client application."

1. Each Instance Template has a name and a description, which are shown on the Instance Template Wizard.
2. A template can define (and use) template variables which are mandatory input by the user when using the template. A template variable can be referenced in parameter value definitions using the {{T:varname}} syntax. If the parameter value is numeric, you can also use simple arithmetic operations on the template variable like {{T:varname:+10}} which will add 10 to the numeric value of the template variable.
3. Instance Variables can be defined in an instance template. Those definitions will be applied to a new instance when this template is used. Link Expressions can then be used to expand to the Instance Variables values in parameters, configuration files, etc.
4. Instance Variables can also be defined in an instance-variable-template.yaml file externally, and referenced via its ID.
5. instanceVariableDefaults allows to override the value of a previous Instance Variables definition in the same template. This is most useful when applying instance-variable-template.yaml files using the template syntax in instanceVariables. The instance variable template can be shared more easily if instance templates have means of providing distinct values per instance template.
6. instanceVariableValues allows to override the value of an instance variable created from instance-variable-definitions.yaml
7. Process Control Groups can be pre-configured for an instance template. If an application template later on wishes to be put into a certain Process Control Group, the group is created based on the template provided in the instance template. Note that the defaults for a Process Control Group in a template are slightly different from the implicit 'Default' Process Control Group in BDeploy. The defaults are: startType: PARALLEL, startWait: WAIT, stopType: PARALLEL.
8. A template defines one or more groups of applications to configure. Each group can be assigned to a physical node available on the target system. Groups can be skipped by not assigning them to a node, so they provide a mechanism to provide logical groups of processes (as result of configuring the applications) that belong together and might be optional. It is up to the user whether a group is mapped to a node, or not. Multiple groups can be mapped to the same physical node.
9. Instance Templates can reference Application Templates by their id. The Instance Templates can further refine an Application Template by setting any of the valid application fields in addition to the template reference.
10. When referencing an application template, it is possible to define overrides for the template variables ({{X:...}}) used in the template. Use provided values will not be taken into account for this variable when applying the template, instead the fixed value will be used.
11. A template group contains one or more applications to configure, where each application can consist of process control configuration and parameter definitions for the start command of the resulting process - exactly the same fields are valid as for Application Templates - except for the id which is not required.
12. A list of operating systems where this application will be applied. If the node is running on an operating system that is not contained in the list, then the application will not be imported. If no list is present, then all operating systems are considered valid.
13. Start command parameters are referenced by their ID, defined in app-info.yaml. If a value is given, this value is applied. If not, the default value is used. If a parameter is optional, it will be added to the configuration if it is referenced in the template, regardless of whether a value is given or not.
14. Using applyTo, an application can be restricted to be applied only to certain nodes, running a specified operating system. A list of supported operating systems can be specified. If this is not specified, the application is assumed to be capable of being applied to nodes running any of all supported operating systems.
15. A template group can have either type SERVER (default) or CLIENT. A group may only contain applications of a compatible type, i.e. only SERVER applications in SERVER type group. When applying the group to a node, applications will be instantiated to processes according to their supported OS and the nodes physical OS. If a SERVER application does not support the target nodes OS, it is ignored.

An instance template will be presented to the user when visiting an Empty Instance.

groups is a list of template groups. This groups together a set of Application Templates or inline template definitions. Each group has a set of own attributes, as well as a list of templates:

A parameter-template.yaml allows products to define re-usable blocks of parameters associated to a unique ID. These can then be applied in app-info.yaml files. For the user of BDeploy, those parameters will appear as if they were defined directly in the app-info.yaml of the application.

id: param.template <1>

parameters: <2>
  - id: tpl-param
    name: "Template Parameter"
    defaultValue: "x"
    longDescription: "A parameter defined in a template"

1. The ID can be used to reference the template afterwards from an app-info.yaml.
2. The parameters can contain an arbitrary amount of parameter definitions, which follow exactly the same schema as supported parameters attributes in app-info.yaml.

An instance-variable-template.yaml works the same as a parameter-template.yaml in that it provides common definitions for instance variables, which can be re-used in instance-template.yaml files. Those definitions are inlined early on, so variables from instance-variable-template.yaml files can do exactly the same things as instanceVariables in a instance-template.yaml.

id: var.template <1>

instanceVariables: <2>
  - id: "my-instance-var"
    description: "My Instance Variable"
    value: "My Value!"
    type: STRING

1. The ID can be used to reference the template afterwards from an instance-template.yaml.
2. An arbitrary amount of instance variable templates. The schema is the same as supported instanceVariables Attributes in instance-template.yaml

An instance-variable-definitions.yaml provides definitions for instance variables, based on which instance variables will be created. The definition values can be overriden using instanceVariableValues in an instance-template.yaml.

definitions: <1>
  - id: "my-instance-variable-definition"
    name: 'My Instance Variable Definition'
    longDescription: 'The description for instance variable definition'
    type: 'STRING'
    defaultValue: 'someDefaultValue'
    groupName: 'Instance Variable Definitions Group'

1. File consists of a single list of definitions containing an arbitrary amount of instance variable definitions.

Instance variable definitions support a subset of supported parameters attributes

A (freestanding) system-template.yaml allows you to specify a broader scoped template than a (product-bound) instance-template.yaml. A system-template.yaml can reference multiple products, and Instance Templates therin to create systems containing of many instances from different products.

name: Test System
description: 'A test system with both demo and chat product'

systemVariables: <1>
  - id: test.system.var
    description: 'A test system variable'
    value: testValue

templateVariables: <2>
  - id: node-base-name
    name: "The node base name"
    defaultValue: "Node"

instances:
  - name: 'Demo Instance' <3>
    description: "The Test System's Demo Instance"
    productId: 'io.bdeploy/demo'
    productVersionRegex: "2\\..*"
    templateName: 'Default Configuration'
  - name: 'Chat Instance'
    description: "The Test System's first Chat Instance"
    productId: 'io.bdeploy/chat-app'
    fixedVariables: <4>
      - id: app-name
        value: "{{T:node-base-name}}"
    templateName: 'Default Configuration'
    defaultMappings: <5>
      - group: 'Chat App'
        node: '{{T:cell-base-name}}'

1. The single core artifact created on BDeploy using a System Template is - of course - a System. It is possible to define an arbitrary amount of System Variables using the template.
2. Template variables in System Templates work similar to template variables in instance-template.yaml. They can be used within the system-template.yaml in instance names, fixedVariables and defaultMappings.
3. A simple instance reference must consist of a name, a productId and a templateName, meaning "create an instance with name name, from the product productId using the template templateName".
4. fixedVariables allows you to specify a "fixed" value for template variables used in the referenced Instance Template. This will skip querying the user for a value for that variable, and instead use this fixed value.
5. defaultMappings can be used to pre-assign Instance Template groups to available nodes. If a node with the specified name is not available during application of the System Template, no node will be preselected. To specify the Client Application node, you can either specify 'Client Applications' or the internal name '__ClientApplications'.

Each element provides a description of an instance to be created from a specific product and a specific instance template.

The product-validation.yaml file contains references to all files that should be sent to the server when performing a product pre-validation. This validation can be used to verify that the product and all its applications contain valid BDeploy YAML.

The content of this file is very straight forward:

product: product-info.yaml

applications:
  my-application: app1/src/main/dist/app-info.yaml
  other-application: app2/src/main/dist/app-info.yaml

This file can be passed to the remote-product-validation CLI command, as well as to the BDeployValidationTask Gradle task.

Now that you have a well-defined Product with one or more Applications, you will want to build/package that Product to be usable with BDeploy.

The well-defined Product directory including Applications can be zipped and imported directly from the web interface.

The following conditions must be fulfilled for a successful import:

• ZIP files must be self-contained, e.g. only relative paths are allowed and no leaving of the zipped structure via ".." paths.
• YAML files must follow standard naming (product-info.yaml).

Once you have a product-info.yaml with it's product-version.yaml and all the app-info.yaml files in their respective Application directories, you can use the CLI to import the product as a single piece.

• Use bdeploy product to import the product by specifying a local BHive and the product-info.yaml to import from.
• Use bhive push to push the resulting Product Manifest from the local BHive to an Instance Group on a remote BDeploy server.

BDeploy provides a Gradle plugin. This plugin can be used to build a product out of your application.

Given a sample Java application which has been created from the default gradle template using gradle init, these are the changes you need to build a BDeploy product for this single application. For this demo, the application is named test.

plugins {
  ...
  id 'io.bdeploy.gradle.plugin' version '3.1.1-1' <1>
}

version = "1.0.0-SNAPSHOT" <2>

ext { <3>
  buildDate = new Date().format('yyyyMMddHHmmss')
  buildVersion = project.version.replaceAll('SNAPSHOT', buildDate)
}

task validateProduct(type: io.bdeploy.gradle.BDeployValidationTask, dependsOn: installDist) { <4>
  validationServer {
    useLogin = true
  }

  validationYaml = file('bdeploy/product-validation.yaml')
}


task buildProduct(type: io.bdeploy.gradle.BDeployProductTask, dependsOn: installDist) { <5>
  repositoryServer {
    useLogin = true
  }

  product {
    version = project.ext.buildVersion
    productInfo = file('bdeploy/product-info.yaml')

    applications {
      test {
        yaml = new File(installDist.destinationDir, 'app-info.yaml')
      }
    }

    labels.put('buildDate', project.ext.buildDate)
  }
}

task zipProduct(type: io.bdeploy.gradle.BDeployZipTask, dependsOn: buildProduct) { <6>
  of buildProduct
  output = new File(buildDir, "product-" + project.ext.buildVersion + ".zip");
}


task pushProduct(type: io.bdeploy.gradle.BDeployPushTask, dependsOn: buildProduct) { <7>
  of buildProduct

  target.servers {
    myServer { <8>
      useLogin = true
      instanceGroup = project.getProperty('instanceGroup')
    }
  }
}

...

1. Applies the plugin BDeploy gradle plugin.
2. Sets the project version. Gradle does not strictly require a version, and uses 'unspecified' as default. BDeploy requires some sort of version, and setting it for the whole project is good practice.
3. Calculate a build date, which will be substituted instead of the SNAPSHOT in the version. This is optional, you could just plainly use the version set. The actual buildVersion used later when building the product is derived from the project version and the buildDate.
4. The BDeployValidationTask can be used to validate product information before actually building the product. The product-validation.yaml file must contain a reference to the product-info.yaml used, as well as references to all app-info.yaml files.
5. This task will actually build the product with the configured version. The actual data about the product is loaded from bdeploy/product-info.yaml, which we will create in a second. Note that this task depends on installDist, which will unpack the binary distribution of the application in this project into a folder, so BDeploy can import the individual files. Depending on the type of application and the way it is built, there might be different ways to achieve this.
   The repositoryServer will be queried for additionally specified runtimeDependencies at build time. Those dependencies will be downloaded and embedded into the final product.
6. If buildProduct built a product, this task will package it as a ZIP file. Note that a ZIP will always contain all of the product, whereas pushProduct can push only required deltas which are not present on the target server.
7. The pushProduct task can push required deltas to one or more configured target servers. The server configuration is the same as for all other ..Server blocks (see note below). In addition the target instanceGroup must be specified for pushing.
8. Multiple target servers can be specified in the target.servers section. The plugin will push to each of them.

Next we need the required descriptors for the product and the application. For this sample, the information will be the bare minimum, please see app-info.yaml and product-info.yaml for all supported content.

Lets start off with the app-info.yaml, which describes the test application.

name: Test Application

supportedOperatingSystems: <1>
  - LINUX
  - WINDOWS

startCommand:
  launcherPath: "{{M:SELF}}/bin/test{{WINDOWS:.bat}}" <2>

1. By default, the BDeploy plugin will make this application available for all the supported platforms specified in app-info.yaml. If required (usually it is not) you can configure a different set of Operating Systems to build for in the test application configuration in build.gradle by adding a set of operating system literals (e.g. 'WINDOWS', 'LINUX') to the os list of the application.
2. This demo app-info.yaml only defines the path to the launcher, which for this demo project (named test) is bin/test on LINUX, and bin/test.bat on WINDOWS.

Finally, we need a product-info.yaml describing the product itself. We'll put this file into a bdeploy subfolder. This is not required, it can reside anywhere in the project. You just need to adapt the path to it in the build.gradle.

name: Test Product
product: io.bdeploy/test <1>
vendor: BDeploy Team

applications:
  - test <2>

versionFile: product-version.yaml <3>

1. This is the unique ID of the product. This is basically a 'primary key' and should not change over time.
2. The product-info.yaml needs to list included applications. These applications also need to be available from the product-version.yaml.
3. The versionFile parameter must be set. If the relative path given here does not exist, the BDeploy Gradle plugin will generate this file for you, using the given version and applications. Otherwise you can provide this file and have more manual control over applications. In case the plugin generates the file for you, it will be deleted right after the build.

That's all that is required to build a product. You can now run ./gradlew zipProduct on the CLI to try it out. The result will be a build/product-1.0.0-XXX.zip where XXX is the buildDate we set previously. The content of the ZIP file is a BHive, which is the internal data format used by BDeploy. You can upload this product to any BDeploy server using its Web UI.

BDeploy provides integration into Eclipse TEA. Using this integration, you can easily export Eclipse RCP based products as Applications and bundle them into a custom Product.

Once you have required files, select TEA > TEA Build Library > Build BDeploy Product.... You will be prompted which Product to build and where to put the resulting product. You can choose to create a self-contained ZIP, or to push deltas to a selected server.

You can configure multiple servers by using the [ Add ], [ Delete ] and [ Edit ] buttons.

Enter a description and a URL. You will then be able to use the [ Login ] button to create a token for the server.

Now you can use the [ Load Groups ] to fetch a list of existing instance groups from the server to choose from. Finally, use the verify button to check whether the entered information is correct.

When confirming the build dialog, on first run you will be prompted to login to the Software Repositories BDeploy server configured in the TEA BDeploy preferences.

Since product builds are stored in the workspace, you can choose to re-push a previous build of the product (to the same or another server). Select TEA > TEA Build Library > Push BDeploy Product... to do so. You will be presented a list of available local product versions and the configured BDeploy servers.

This file is required and lists the product-build.yaml files which are available to the integration.

products:
  "Product One": "prod-1-build.yaml"
  "Product Two": "prod-2-build.yaml"

The path to the products.yaml has to be configured in the Eclipse TEA preferences.

The preferences also allow to configure a BDeploy server whos Software Repositories are used during resolution of Runtime Dependencies. You will be asked to log into this server once when starting a product build.

This file references a product-info.yaml file and describes how to build the actual applications referenced in the product-info.yaml.

productInfoYaml: my-prod-info.yaml

applications:
  - name: my-app1
    type: RCP_PRODUCT
    includeOs: [WINDOWS, LINUX]
    application:
      product: App1ProdBuild

  - name: my-app2
    type: RCP_PRODUCT
    includeOs: [WINDOWS, LINUX]
    application:
      product: App2ProdBuild

The value for applications.application.product is Eclipse TEA specific and references the Eclipse TEA product alias property.