Logo

Introduction

BDeploy is a fast, reliable and configurable deployment solution for any type of application. It features an easy to use and flexible user interface on top of a distributed storage.

Key Features

Angular UI

The Angular-based Web UI provides all means for easy configuration and deployment of your products and applications.

Powerful Storage

The storage backend provides data de-duplication in a high performance, distributed, delta-based storage network.

Performance

BDeploy uses a delta-transfer mechanics to provide minimal updates throughout a whole network of nodes participating in deployments.

Visit the official homepage https://bdeploy.io to get the latest release as well as more information about all features that make BDeploy unique.

Terms

BDeploy has a some important terms and concepts which should be known before diving into details of the application itself. These terms will be used all over the documentation to cross-reference other parts of the application.

Term Meaning

Instance Group

An Instance Group is the main top-level element used in BDeploy. It provides a grouping of Instances (as the name suggests).

Product

A piece of software that can be deployed with BDeploy. A product is a bundle of Applications along with some meta-information.

Application

A part of a Product that can be started and stopped separately. Applications either run as Process on a server machine or as Client Application on a desktop computer.

Client Application

An Application that can be distributed on desktop computers.

Instance

An Instance is the actual deployment configuration of a Product. In one instance, the Applications of a Product can be distributed as Processes on one or more Nodes.

The Product (and it’s Applications) describes the possible configuration values (e.g. configuration files, command line parameters, etc.) - the Instance provides actual values for these.

Instance Version

An Instance Version describes the configuration state of an Instance at a given time. Each change that is done by the user results in a new instance version. Versions are immutable and cannot be changed. Each new change results in a new version of an Instance.

Process

A server Application that is configured to be started on one of the server Nodes of an Instance.

Build

A Build represents the immutable collection of all runtime artifacts (binary files, configuration files, templates etc.) of a Product. As a Build is immutable, the build tool (Maven, Gradle, Eclipse) creates a new one on every execution.

Product Version

A Product Version represents a Build that is marked with a Tag.

Tag

A Tag identifies a Product Version. The structure of a tag is defined by the Product itself. The only obligation is, that a tag has to be unique for different Builds of the same Product.

Node

A server machine (virtual machine or bare metal) that is used in an Instance to run the configured Processes on it. BDeploy supports Windows and Linux nodes, even mixed in one instance.

Minion

Agent process provided by BDeploy that has to run on every Node used by BDeploy. In a multi-node setup one minion takes the role of a master. All other nodes act as slaves which are managed by the master.

Deployment

The whole process of making one Instance Version up and running. This includes the major process steps: Installation, Activation, Process Control.

Installation

The process of transferring the configured Processes of an Instance Version to all Nodes of that Instance. The Installation makes this Instance Version available for its Activation.

Activation

The Activation marks an previously Installed Instance Version as the one to be started by the Process Control. Only one instance version can be active for one instance at the same time.

Process Control

The Process Control is responsible for starting, keep-alive and stopping the Processes of the active Instance Version.

Installation

This chapter guides you through the installation of BDeploy. At the end you will have the backend and the frontend up and running so that you can start deploying your applications.

The source distribution of BDeploy contains a demo server that can be started with ./gradlew runDemoServer. The example data is reinitialized with each server start.

Download

The latest and greatest BDeploy version can be downloaded on the official Github page: https://github.com/bdeployteam/bdeploy/releases

Extract the BDeploy binaries from the distribution ZIP. There is no requirement regarding the location of the binaries. The target of the unpack will contain a bin/bdeploy or bin/bdeploy.bat depending on whether the distribution is built for linux (e.g. bdeploy-linux64-x.x.x.zip) or windows (e.g. bdeploy-win64-x.x.x.zip).

For easier handling, make sure the unzipped 'bin' folder is on the PATH. The rest of the manual assumes you have done this, otherwise simply prefix all commands with the correct path to the binaries.

Update of existing Installations

In case you already have an existing installation of BDeploy, you can easily update this installation. An update can be performed in two different ways: through the command line (even remotely) or through the Web UI.

For more information about the Web UI, please see BDeploy Update.

To remotely update an existing server, use a command similar to the following:

bdeploy login --login --name=MyServer --remote=https://host:port/api
bdeploy remote-master --update=<path-to-update.zip> --useLogin=MyServer

Updating a local server is through the command line is done in the same way.

Existing slaves don’t need a separate update. They need to be online when applying the update to the master. The update is applied to all online slaves as well when applying it to the master.

Master

Modes of Operation

BDeploy may be set up in different modes, makeing a few different overal usage scenarios possible:

  • STANDALONE mode: A standalone BDeploy master which is responsible for itself, its slaves, and every application deployed theron.

  • MANAGED mode: A BDeploy master which is controlled by a CENTRAL BDeploy master. The MANAGED master can still be used nearly the same as the STANDALONE master, with very few restrictions. A MANAGED master can additionally be controlled indirectly through the attached CENTRAL master

  • CENTRAL mode: Allows a central BDeploy master to control/manage multiple MANAGED masters. The CENTRAL master itself has no local deployment capabilities, but just the ability to control other masters. Other than that, from a users perspective, the server handles mostly like a STANDALONE or MANAGED master directly.

  • SLAVE mode: A slave which can be attached to either a STANDALONE or MANAGED server as additional node to run applications on.

STANDALONE Deployment Scenario

Compared to the rather straight forward standalone scenario above, a CENTRAL and MANAGED server setup, allows for more flixibility, manageable through a single Web UI:

CENTRAL/MANAGED Deployment Scenario
You can still manage every MANAGED server directly through its own Web UI. Creation of new Instance Groups is restricted to the CENTRAL Web UI though.

BDeploy's CENTRAL mode is built in a way that attached MANAGED servers can have an alternate URL, allowing it to manage servers which are known under a different name in the local network (e.g. VPN/NAT, alternate DNS, etc.).

Initialization

To start using BDeploy you will at least need a single master. The master needs to be initialized before it can be started.

The root directory contains all the runtime data. Best to select an empty directory in the data area of your system (e.g. /var/bdeploy on Unix) that is intended exclusively for this purpose. Keep the root directory separate from the BDeploy binary installation. Make sure that there is enough space available.

bdeploy init --root=/path/to/storage --hostname=<hostname> --mode=STANDALONE --port=7701 --initUser=username --initPassword=usersPassword

The init command will create the initial administrator user from the --initUser and --initPassword parameters. This user has full administrative privileges. You can use the bdeploy login command to authorize all other CLI commands for your user.

Don’t use the depicted user and password, these are just samples.

The init command will write an administrator access token to a file if given with --tokenFile. This tokens main purpose is automation (scripting) and testing.

The --mode parameter of the init command is used to determine the future purpose of the BDeploy root. The mode can be STANDALONE, MANAGED, CENTRAL (or SLAVE - see Slave).

It is not recommended (but possible) to change the mode of an initialized root later, so take care to use the correct mode for the intended use.

The result of the init command is a root directory which can be used by the master or slave commands.

Launch

After the initialization - which needs to be done only once - the master can be started with the following command:

bdeploy master --root=/path/to/storage

This will start the master server which also hosts the web UI: https://localhost:7701

The server is using a self-signed certificate by default. Thus you need to instruct your browser to accept it. See Custom Certificate for instructions on how to provide a better certificate.

User

Only authenticated users have access to the web UI. The initial user has been created by the init command. Use this user to log in to the Web UI, and create additional users (or provide external authentication mechanisms) from the User Accounts administration page.

Custom Certificate

By default BDeploy uses a self signed certificate for both TLS (HTTPS) traffic encryption as well as token issuing. Tokens can be issued on the command line and from the User menu in the Web UI. These tokens are used to authenticate and authorize any actions performed remotely (command line, third party software, Web UI, etc.).

By changing the certificate BDeploy uses, all existing tokens will lose their validity.

You can use the certificate tool to switch to another ceritificate:

bdeploy certificate --update=<path-to-pem> --root=<path-to-root>

Slave

Slaves are optional and only required in case that the application that you want to deploy should run on different servers but be managed from a certain master. By default a master is itself a slave as well where applications can be deployed to.

Initializing

Slaves must be initialized on the according machines (or on the same machine using non-default ports; the default port is 7701). The command is the same as the one used to initialize the master. Pass (for example) --port=7702 to change the default port to some other value to avoid conflicts. Running multiple bdeploy minions on the same machine is supported for testing, but not recommended for productive setups (as the master can be deployed to directly anyway - no need for an explicit slave).

bdeploy init --root=/path/to/slave/storage --hostname=<hostname> --tokenFile=token.txt --port=7702

Again, the init command will output the root access token for this slave. You need it to register the slave with the master, so keep it around or use --tokenFile=slave.txt to store the token into a file.

Launch

After the initialization - which needs to be done only once - the slave can be started with the following command:

bdeploy slave --root=/path/to/storage

Registration

To register a slave with the master use this command on the master’s root:

bdeploy slave --add=slave-name --root=/path/to/master/storage --remote=https://slave-host:7702/api --tokenFile=slave.txt
Both the https (beware the s) and the /api suffix are required!

The slave is now registered as 'slave-name'. This is the name which is reported when querying nodes from the master. This is also the name displayed when configuring applications to run on certain nodes later on.

Service

Linux Service (SYSTEMD)

The bdeploy-linux64-x.x.x.zip package contains a template file from which a systemd service can be created. It is located in the etc directory and named bdeploy-minion.service.

The template itself contains instructions on how to create a valid service from it.

You can copy the service template to a different filename while installing into the systemd service directory. The filename will later on be the service name. This allows to install multiple bdeploy master/slave services on a single machine.

To get systemd to recognize the service(s) after copying the service file(s) use the systemctl daemon-reload command (as root). Once installed, you can control the service using systemctl.

Windows Service

The bdeploy-win64-x.x.x.zip package contains a batch script to create a new Windows service. The script is located in the etc directory and is named bdeploy-service-install.bat

The script must be called with administrative privileges and it expects the following arguments:

--master | --slave     Start a master or slave node
<Path-to-minion>       Absolute path of the bdeploy executable
<Path-to-store-files>  Absolute path of the data directory

By default the service runs as Local System but you can and should change that afterwards by using the services.msc application. Simply configure the desired account in the Log On tab of the services management console.

Once installed, you can start the service using services.msc or by calling net start BDeployMaster | BDeploySlave.

Use the Event Viewer (Windows Logs→System) to get more information when the service fails to start.
Application logs (stdout, stderror) are written to a log file that is stored in <path-to-store-files>\log\service.log
The service parameters are stored in the Windows registry: HKLM\SYSTEM\CurrentControlSet\Services\BDeployMaster
You need to adopt the batch script when you want to create multiple services on the same machine. Simply adopt the MINION_SERVICE_PREFIX to use another prefix for the service.

Verify Setup

Make sure that all master and slave services are running on the according nodes by starting the created services or by starting them manually. To verify that the setup is OK, run on the master:

bdeploy login --add=MyServer --remote=https://localhost:7701/api
bdeploy remote-master --minions

This will provide output like this:

NAME                 STATUS                       START OS         VERSION
master               ONLINE            1/21/19, 4:43 PM LINUX      1.0.0.e32e
slave                OFFLINE

If any of the nodes is marked offline, the according minion on the respective node is not reachable from the master node.

bdeploy login will prompt for user and password, create a local session, and use that session on subsequent commands. This login session will keep validity until removed using e.g. bdeploy login --remove=MyServer.

Getting Started

This chapter provides an overview of all parts of the BDeploy user interface.

Login

Each user needs to authenticate with a username and password in order to get access to all parts of the system. An anonymous access is not available.

BDeploy Login

After a successful login the main page is shown with all Instance Groups that the user is permitted to see.

Clicking on the hamburger menu in the top-left corner provides access to the various other parts of the system.

BDeploy Main Menu

Clicking on the user menu in the top-right corner provides access to various user related actions and information.

BDeploy User Menu
Users which are authenticated against an external system (e.g. LDAP) are not able to edit their user information (including password) through the user menu. Updates have to be performed on the controlling system (e.g. LDAP server) in this case.

Instance Group

An Instance Group acts as logical container for actual Instances. It typically contains several Instances for different purposes (productive, test, development). Adding them to the same group provides a better overview which of them are belonging together. An empty page is displayed if no instance has been created.

Empty Instance Group Overview

Use the + button to create a new Instance Group.

Create Instance Group
The name of an instance group cannot be changed. Be carful when choosing the name.

The Automatic Cleanup option helps to reduce the amount of consumed hard disk space. During the lifetime of an Instance Group, probably many new versions of a Product are deployed. To avoid that the hard disk is filled up with Product Versions that are not used anymore, there is an option to activate an automatic cleanup job. If the option Automatic Cleanup is enabled, old Product Versions that are no longer in use by Instances of this Instance Group are deleted automatically. To avoid that a Product vanishes completely, the very latest Product Version always remains.

Instance Group Access

A new Instance Group is initially only visible to users with global read permission (or higher).

Global Instance Group Permissions

Use the + button to add a user to the list. The input field suggests matching users from the list of all users.

Grant Read Access to an Instance Group

Adding a user grants read access to the Instance Group. The bin icon in the last column removes the user from the list. Users with global read permission cannot be removed.

Grant Read Access to an Instance Group

Write access and administration permissions for an Instance Group can be granted and revoked using the checkbox in the respective column.

Instance Group Dialog

All Instance Groups that are visible to the user are shown in the Instance Groups dialog. This page shows a list of recently used Instance Groups in the first row. It will always contain the most recently used Instance Groups for the logged in user. This allows allows a quick return to previously/frequently visited Instance Groups.

Demo Instance Group
Of course you can also bookmark the location of an Instance Group in your browser.

Initial Steps

Click on an Instance Group to open the Instance Browser of this group. Here you can see all Instances grouped by their purpose (can be DEVELOPMENT, TEST, PRODUCTIVE)

Empty Instance Browser

Since an Instance requires a Product, an empty Instance Group will display a shortcut to the Manage Products dialog. If there is at least one Instance already, the shortcut disappears. The Context Menu  Products menu opens the Manage Products dialog, too.

Manage Products

Click the + button to upload new Products. Products can be obtained by building a Product or by downloading an existing version from another Instance Group on the same or another BDeploy server, using the Download button on the Product details panel.

On the BDeploy Releases page you will find some sample products for each release, see https://github.com/bdeployteam/bdeploy/releases
Empty Products Page
Upload Product(s)
Upload Product(s) (success)

Once a Product is available, you can click it to open the Product details panel. This panel allows you to Download a Product version as ZIP, or Delete individual versions of the Product as long as it is not currently required by an Instance version. The Info popup provides a list of all tags on that Product version.

Products Page
Product Details

Create New Instances

To create a new Instance, click the + button at the bottom of the page. After giving the new Instance a name, purpose and description, the most important thing is to select the Product you want to deploy. Additionally, The initial Product Version has to be chosen. It can be changed later at anytime (up- and downgrade).

It is a common requirement that certain Processes of an Instance should be automatically started whenever the BDeploy server itself is started. To accomplish that, the Automatic Startup flag of the Instance must be set.

The Instance determines whether it is included in the automatic cleanup job. If the option Automatic Uninstallation is enabled, the cleanup job will uninstall all Instance Versions that are older than the activated and the previously activated Instance Version. Due to this automatic uninstallation some of the old Product Versions might become unused. If the option Automatic Cleanup is activated on the instance group, these unused Product Versions are deleted too (see Instance Group).

Create a new Instance

Click an Instance to proceed to the Instance Overview.

Instance Browser

Instance Overview

The Instance Overview is the central dialog for configuring and managing instances. It provides an overview about all configured Applications and on which nodes they are running. Each Application is represented by a Process Card. Colored markings on the card indicate whether a process still lacks mandatory configurations or whether there are still unsaved changes.

The first step is to select the desired applications from the Configure Applications panel distribute them to the Nodes in the Instance using drag and drop. The panel is called up via the pull-down menu of the dialog. The applications that are shown in this panel are defined by the Product.

Instance Menu

The Configure Applications panel contains all server applications and all client applications of the product. Server applications can be dragged to Server Nodes (e.g. master), client applications can only be dragged to the (virtual) Client Applications Node. Clients that are available for more than one operating system expand to single cards per operating system on the Client Node.

The Client Application Node is not available if the product does not contain any client applications.

Process Settings

A Process is started by executing the Start command that is defined by the Application. The parameters that are passed to the Process are configured in the Process Settings dialog. This dialog can be accessed via the pull-down menu on the respective Process Card.

Drag & Drop Applications

The available parameters, their type and whether or not they are mandatory or optional are defined by the Application. The dialog groups the available parameters into categories, between which you can jump back and forth via Previous and Next.

Process Parameter Configuration
The Application defines in which order the parameters are passed to the Process this order cannot be changed for predefined parameters.

Behind each parameter there is a small popup that can contain a short description, a Default Value and a button for resetting the parameter to the Default Value.

Validation Issues are displayed per group in the respective title. Only complete configurations can be accepted.

You can use the Search Bar in the Parameter Settings header to search for and filter parameters. When searching only matching parameters are shown, groups without matches are hidden, and the Manage Optional Parameters button will receive a badge indicating the number of matching unconfigured parameters.

The context menu on an application card allows you to copy an application definition. This can be pasted on any node of the correct type using the context menu on the according node when in Configure Applications mode.

Paste Application
Optional Parameters

Optional Parameters can be selected for each group using the Manage Optional Parameters dialog (available only if Optional Parameters are available) and then configured like other parameters.

Manage Optional Parameter(s)
Configuring Optional Parameter(s)
Custom Parameters

Custom Parameters can be maintained in the last parameter group. Because all Parameters must have a determined sequence, Custom Parameters must define a predecessor parameter after which they are put on the command line.

Create Custom Parameter
Configure Custom Parameter
Global Parameters

Global Parameters are valid for all Processes of an Instance. They are also configured in the Process, but changes are copied to all other processes that also use this parameter. Global Parameters are matched by their parameter UID, and marked with a small globe in the Process Configuration dialog.

Conditional Parameters

Conditional Parameters are parameters which are only configurable if a specific dependent parameter has a certain value. These parameters are hidden until the dependent parameter meets the conditions requirements.

Variables

BDeploy provides a mechanism for defining that a parameter should hold a dynamically computed value instead of a fixed one. The general syntax for variables is {{TYPE:VARNAME:SUBVAR}}. With that mechanism it is possible to define that a certain parameter holds different values for different operating systems or to refer to parameters defined in a different process. See Variable Expansion for more details.

Command Line Preview

A preview of the command that is executed to launch this process can be viewed by clicking on the Show Command Line Preview button that is displayed at the right side of the Parameter Settings header. The preview is especially useful in case of custom parameters to ensure that they are added as expected in the correct order.

Preview Command Line with Custom Parameter

Configuration Files

The Configuration Files of all Processes of an Instance are maintained together in one dialog. It can be opened by clicking on the Configuration Files button in the pull-down menu of the Instance. The initial set of Configuration Files is derived from the default set delivered with the product, see product-info.yaml.

Configuration File Browser

New configuration files can be be created using the + button. This will open the integrated editor. Additionally to that existing files can be uploaded using the provided Upload button.

File types

The type of a configuration file is automatically detected and visualized in the dialog. The following table shows the supported file types and how they are treated:

Type Online Editing Variable Expansion Encoding Samples
BDeploy CfgFiles Text

Text

Can be edited online using the integrated editor.

Variables used in the file content are replaced. See Variable Expansion for more details.

Files are always written using UTF-8 encoding.

txt, log, xml, csv

BDeploy CfgFiles Binary

Binary

Cannot be edited online.

Not available.

Files are written as they are without any modifications.

zip, pdf

Editor

The integrated editor provides syntax highlighting and rudimentary syntax checking for some basic file types (yaml, json, xml). Displayed problems are only to be seen as help and never interfere with the process, e.g. by preventing the saving of a file. Only files of type Text can be edited with the provided editor. Binary files can only be changed by uploading a new file with the same name.

Create New Configuration File
Modified Configuration Files
Changes done in configuration files must be Saved and they result in a new Instance Version that must be Installed and Activated so that the changes have an impact.

Change Product Version

Instances are based on a Product Version. While the Product of the Instance cannot be changed afterwards, the Version can be chosen from the available Product Versions (upgrade to a newer version / downgrade to an older version).

If there’s a newer Product Version available (newer than the one that is configured for the latest Instance Version), a notification is shown in the notification area.

Notification about new Product Version

Clicking on the notification opens the Product Version sidebar. The same sidebar can also be opened opened by clicking on the Change Product Version button in the pull-down menu of the Instance. If the menu entry is disabled verify that the latest Instance Version is selected.

Change Current Product Version

The Info Popup provides a list of all Labels on that Product version.

Changing the version can be done by clicking on the Upgrade or Downgrade button displayed at the right side of the product version card. Selecting another product version will automatically close the Product Version sidebar. The Instance Version sidebar is displayed and a new locally modified version has been created.

Successful Product Tag Change
All Applications are marked as modified as they are now based on a different Product Version.

Changing the Product Version can result in validation issues and automated adjustment of parameters. Product Versions can contain different Applications, so that with the change of the Product Version e.g. a previously configured Application must be deleted because it has been removed from the product. If parameters definitions are changed, validation errors may occur which must be corrected before saving (e.g. new mandatory parameters, parameters no longer supported, etc.). These errors will cause a visual indicator on affected applications, as well as a textual description of the problem in the notifications area.

Validation Issues After Product Version Change

Banner Message

A banner message can be created for an Instance, which is displayed very clearly at the top of the overview dialog. The foreground and background colors are freely definable, so that depending on the urgency or content of the message a suitable color, possibly a clear signal color, can be selected. Banner messages are maintained on instance level and are not versioned, i.e. they are independent of instance versions. Therefore they outlast configuration changes of an instance.

Import/Export

Instance versions can be exported and downloaded from the Instance Version card’s context menu. This will download this specific instance version’s raw data as a ZIP. This ZIP will contain the complete instance configuration as well as all configuration files currently stored with the instance.

The content of the ZIP can be edited offline, and re-imported using the Instance's (not Instance Version) context menu to create a new Instance Version. The file structure inside the ZIP must be exactly the same as when exporting.

This mechanism allows access to the most internal data structures of BDeploy. Great care has to be taken to not damage any of the data on import.

Application Templates

A product may contain Application Templates. These are pre-defined configurations for applications, resulting in a more complete process configuration when dragged to the target node. If an application has an attached Application Template, it’s application card will contain a drop down (Choose Application Template), which - when clicked - will show all available templates to choose from.

Application Template Drop Down

After choosing a template, dragging the card to the target node as usual will create the process configuration from this template instead of starting from scratch. In case the template requires user input (i.e. it defines mandatory template variables), the user is prompted to fill them out before the process is created.

Application Template Variables

Finally, the process configuration is created from the application template using the given variable values.

You will notice that the name of the process now matches the name of the template, not the name of the underlying application.
Application Template Process

Instance Templates

A product can define and include Instance Templates. These templates can be applied on an empty instance (e.g. after creating one). They can define processes just like Application Templates, in fact they can even include existing Application Templates.

The advantage of an Instance Template is that it can contain more knowledge of how processes need to be set up to work together, wheras Application Templates define configuration for a single application.

Instance Template on empty instance

The Instance Template link is only available if the product contains templates to start from. Clicking it will open up the Instance Template wizard.

Instance Template Dialog Group Selection

Selecting a template (here: Default Configuration) will show a list of groups defined in the template. These groups can be assigned to compatible nodes - groups containing server applications to server nodes, and groups containing client applications to the special Client Applications node. Selecting None as target node will skip the processes in this group. Click the (i) info icon to display details about a group, including all processes configured in the template group.

When creating configurations on a SERVER node, applications will be added matching the nodes OS. If a server application is included in a group which is not available for the target OS, it is ignored.

When creating configurations for a CLIENT group, applications are added to the Client Applications virtual node, one for each OS supported by the application.

Clicking Next will show a list of template variables to fill out. Template variables can be used by templates to query required user input, so all template variables are mandatory.

Instance Template Dialog Variables

Clicking Next and then Close once the template has been applied will create the processes defined in the template. The configuration will not be saved automatically, to allow further tuning of the configuration before doing so.

Instance Template Dialog Variables

Configure Ports

The Configure Ports page can be reached from the Instance context menu. This page provides a concise overview of all ports (CLIENT_PORT and SERVER_PORT parameters) used in the Instance.

You can edit port assignments directly from this dialog. The Shift Ports action allows to bulk edit port parameters and shift them upwards or downwards by a given offset.

The Export CSV action allows to export a CSV list of all ports configured in the system. This can be used to pass on information to external partners, for instance for further firewall configuration, etc.

Deployment

The process of making one Instance Version up and running is called Deployment. This includes the steps Installation, Activation and Process Control

Installation

All available Instance Versions can be installed via the action Install. Clicking on that button will transfer all files that the application requires to the configured target nodes. More specific that means the applications are extracted from the internal storage that BDeploy is using and written to the hard disk.

Instance Version Context Menu

Installed versions occupy additional disk space on the target node. Applications are installed in a shared Pool directory on the target node. Thus multiple different Processes referring to the same Application are written only once to the hard disk. This minimizes the required disk space and leads to faster Installation times as only the first Process needs to be be written to the hard disk.

Installed Instance Version

Whether a version is already installed is indicated by an icon on the Version Card to the left of the Product Version. Versions that are no longer needed can be uninstalled using the Uninstall action. Uninstalling deletes the files written to the file system during installation. The version remains available and can be reinstalled at any time.

Activation

One of the installed Instance Versions can be marked as active with the action Activate. The Process Control always refers to the active version. Versions that are just installed cannot be started. Only Processes from the Active version can be started.

Activated Instance Version

Marking a desired version as active does not require to stop all running Processes. A warning message is displayed when processes from non-active versions are still running. They can be manually stopped if desired and then started from the currently active version.

Process Control

For the activated Instance Version, the Process Control of this Process can be displayed by clicking on a Process Card. The upper part of the Process Control Sidebar shows the current Process Status. Below this, the control elements for starting, stopping or restarting the process can be found.

Running Server Process

In addition to the actions for individual processes, the pull-down menu of the dialog contains the actions for starting, stopping or restarting the entire Instance, i.e. all Processes configured with start type INSTANCE.

Process Status

The process status is visualized with an icon in the bottom right corner of each Process Card and on the Process Control Sidebar. The Instance Version card displays the cumulated status of all Processes running in this version. A Process can have one of the following states:

Icon Description

Process is stopped.

BDeploy Process Status Running

Process is running.

BDeploy Process Status Running Stop Planned

Process is running but stopping has been requested by the user.

BDeploy Process Status Running Version

Process is running in another version.

BDeploy Process Status Crashed Temporary

Process crashed unexpectedly. Process Control scheduled an automatic restart. No interaction required.

BDeploy Process Status Crashed

Process crashed unexpectedly. Process Control gave up restarting as the last 5 attempts failed. Manual interaction required.

The life cycle of a process is visualized in the following state graph:

Process State Graph

Process Outdated

An warning message - Outdated - is displayed whenever one or more Processes are running in a version that is currently not Activated. This happens when Deploying a new version while Processes are still running.

BDeploy Process Out Of Sync

In principle this is nothing to worry about. It is just a remainder that the configuration has changed. The Processes will remain running in their current version until they are actively restarted. The message cannot be confirmed / closed as it automatically disappear once all Processes are running in the Activated version.

Process Start Type

The Start Type of a Process can be configured in the Process Configuration dialog. The available options are depending on the Application. That means the publisher of an Application defines which Start Types are supported. The following types are available:

Name Description

MANUAL

Process must be started manually. No automatic startup will be done.

MANUAL_CONFIRM

Process must be started manually and an additional confirmation is required.

INSTANCE

Process will be started automatically if the Automatic Startup flag of the Instance is set.

It is a common requirement that certain Processes of an Instance should be automatically started whenever the BDeploy server itself is started. To accomplish that, the Automatic Startup flag of the Instance must be set. This can be done in the Instance Configuration dialog. Additionally the Start Type of the Process must set to Instance. This can be done in the Process Configuration dialog.

Processes that are executing actions that cannot be reverted or that are potentially dangerous in productive environments (dropping a database, deleting files) should be configured with the start type MANUAL_CONFIRM. Doing that results in an additional popup dialog that enforces the user to enter the name of the Process before it is started. The idea is, that the user takes an additional moment to ensure that he is really starting the desired Process.

Manual Confirmation On Startup

Startup and Shutdown Order

The Process Control starts the processes in the order as they are defined in the Process Configuration dialog. That means the order can be influenced by dragging applications around. When Start Instance is invoked then all processes with startup type Instance are started in the defined order. When Stop Instance is invoked then all running processes are stopped sequentially. The order is reversed during the stop operation. That means the last process is stopped first and the first process is stopped at last. The next process is stopped when the previous is terminated.

Keep Alive

If the Keep Alive flag for a Process is configured then the Process Control restarts it when it crashes unexpectedly. The first restart attempt is immediately executed after the process terminates. Subsequent attempts are delayed. That means the Process Control waits a given time period until the next start attempt is executed. Such a situation is visualized in the UI with a red-warning icon where normally the green heart is displayed.

Crashed Server Process (temporarily)

The Process Control will give up restarting a process after a total of 5 unsuccessful restart attempts. Such a situation is visualized in the UI with a red error icon. This icon means that the user has to manually check why it is failing and restart it if desired.

Crashed Server Process (permanently)

View stdout / stderr

Clicking on the terminal icon displayed below the process control actions will open a live stream of the stdout as well as stderr stream of the running Process. This allows a quick health check to ensure that everything is as expected.

Show and Follow Process Output

Server Ports

The applications server ports (if any are defined) and their state on the target minion can be viewed by clicking on the plug icon below the process controls. Each parameter of type SERVER_PORT is displayed here, with its description and configured value. The state is either a warning icon (port not open) or a green check ico (port is open). "Open" just means that the port is used on the target system currently. BDeploy cannot check whether the port was opened by the correct application.

Server Ports per Node

The same list of SERVER_PORT parameters can be found on a node as well. This will allow to view all port states for all applications configured to that node.

Process listing

Clicking on the gear icon below the process control will open a popup showing all operating system processes that have been started by this Process.

List of Operating System Processes

Data Files

The Data Files dialog lists all files that are stored in the data directory of each minion. Files can be downloaded or opened directly in the the UI. The table is by default sorted by the last modification timestamp. Thus the newest files displayed first. The dialog utilizes pagination and only the top 10 files are shown. This can be changed using the toolbar below the table.

Data File Browser
The delete button can be used to delete a file. This requires administrative permissions on the server or the instance group.

When opened in place, the Follow toggle allows to grab new output as it is written on the server.

Show Data File

Instance History

After a while, you will probably end up with a lot of changes and new versions. You can view all those changes, who made them and when they were made on the Instance History Page. To open the history, go to the Instance overview, click on the menu on the right and click on Instance History.

A timeline with events on each side is shown. There are three types of events Configuration, Deployments and Runtime events. Each event has a title the corresponding version, as well as the time the event happened.

Deployments and Runtime events are not displayed by default.
If you haven’t made any changes, only one card will be shown: Version 1: Created.

Once you scroll to the bottom, a loading spinner will show up and more events get loaded. You can scroll on until you reach the first event.

Instance history

To see the user responsible for change, open a card by clicking on it.

Open card
To close all opened cards, click on the rightmost button of the toolbar on the top. If you want only one card open at once, click on the button to the left of it. With that on, once you open a new card, all other cards will be closed.

Configuration Events

Each change that leads to a new Instance Version is a deployment event. Samples: Adding a new application, chaning the value of a parameter or changing the product version …​

The body of the card list all changes of the corresponding version to the previous version.

Deployment Events

Deployments events are: INSTALL,ACTIVATE,DEACTIVATE,UNINSTALL.

Deployments will show up once you enabled them. Each card consists of a title containing the deployment type and the corresponding version, as well as the time the event happened.

The body of a Deployment card shows the user responsible for the deployment.

Runtime Events

Runtime events are: START, STOP, CRASH, RESTART, PERMANENT CRASH.

Runtime events will show up once you enabled them. Each card consists of a title containing the runtime event and the corresponding application, as well as the time the event happened.

The body of a Runtime card lists the User responsible for the event as well as the node and version of the application. If the not the user but the process or BDeploy triggered the Runtime event, BDeploy System is shown as user.

The Process ID will also show up given that it was present at the moment the event happened.
Runtime events

Searching

You can search for specific events with the search-bar on the top.

After you entered your search term and hit enter or pressed the search button on the right, all cards of which the title, user or PID contain your term, will show up.

To show everything again, empty the search bar first and then hit enter or press the search button.

Comparing two versions

You can compare any two versions to view all changes made between those versions. Select two versions by clicking on the button with two arrows. The versions will show up under Compare Versions in the toolbar on the top. To compare them now, click on the arrow inbetween.

A dialog listing all changes will show up.

Compare versions

Filtering events

To select which events are shown, click on the filter button on the left of Compare Versions in the toolbar on top and enable/disable the shown events.

Filter events

Client Applications

A dedicated overview page shows all configured Client Applications of an entire Instance Group. This page can be opened by navigating to the Instance Browser of the desired Instance Group. Clicking on the Context Menu  Client Applications menu opens the overview page.

Application Download Page

The page will offer the appropriate Client Application based on the operating system that the user is currently using. Switching the OS can be done by clicking the desired operating system in the top right corner.

Launcher

Client Application are started through a special Launcher that needs to be installed on all client computers. The launcher is responsible for keeping the application up-to-date and to pass the configured parameters to the application.

Installer

An Installer is provided for each Client Application to make the installation as easy as possible. The installer does not have any prerequisites and can be downloaded and executed by any user.

The Installer checks if the latest version of the Launcher is already installed. If not then the Launcher is downloaded and stored on the client computer. The user can then start a Client Application with the branded Link that is stored on the Desktop or in the Start Menu.

Windows

By default the Launcher is installed for the Current User in the %LOCALAPPDATA%\BDeploy folder (C:/Users/<user>/AppData/Local/BDeploy). The location can be adopted by setting the BDEPLOY_HOME environment variable before launching the installer. No administrative privileges are required for this installation type.

The Launcher can also be installed for All users by starting the installer with the /ForAllUsers flag. The default location in that case is %ProgramFiles%/BDeploy (C:/Program Files/BDeploy). The location can be adopted by setting the BDEPLOY_HOME environment variable before launching the installer. Ensure that all users have access to the customized location. Otherwise they cannot launch the application.

./Installer.exe /ForAllUsers
Installation for All users requires administrative privileges. Additional configuration might be required depending on the installation location. See Multi-User Installations for more information.
Unattended Mode

The Installer can also be started in an unattended mode with the /Unattended flag so that no UI is shown.

./Installer.exe /Unattended
./Installer.exe /Unattended /ForAllUsers

Linux

The Installer stores the Launcher and all Client Applications in $HOME/.bdeploy. This location can be changed by setting the environment variable BDEPLOY_HOME.

Click & Start

Click & Start enables the launching of Client Application by simply clicking a link in the web browser. In this case the applications are not integrated into the operating system (Start Menu, Desktop Shortcut). A prerequisite is that the Click & Start Launcher is deployed on the client computer. This can be done by using the Click & Start Installer available in the top-right corner of the Client Applications page. The installer will download the Click & Start Launcher and associate it with .bdeploy files.

The Launcher can also be manually deployed using the provided ZIP file. After downloading and unpacking the Launcher must be associated with .bdeploy files using the FileAssoc.exe on Windows or file-assoc.sh on Linux contained in the launcher.

Clicking on a Click & Start link in the Browser will download a .bdeploy file that can be directly executed. A more elegant way is to configure the Browser to directly open the .bdeploy file type. Firefox as well as Chrome allows to configure this after the file has been downloaded.

Multi-User Installations

Larger organizations typically do not want to deploy client applications on each client computer. They prefer to install the client software on a central server and publish the software via Citrix or similar technologies so that all users have access to one shared instance. This has the advantage that the administrators are in control of the installation and can centralize the update handling. BDeploy supports such an installation szenario.

There are two different locations that are important in the context of deploying applications in a multi-user setup:

  • Installation Area - The location where the launcher as well as all applications are installed. This location is typically protected by file system privileges so that an Administrator has full permissions and all other users have read permissions. This location is defined by the environment variable BDEPLOY_HOME.

  • User Area - The per-user are where the launcher as well as each launched application is permitted to write files. This location is mandatory in case that the Installation Area is read-only. This location is defined by the environment variable BDEPLOY_USER_AREA.

Configuration

When the Installation Area is read-only the environment variable BDEPLOY_USER_AREA must be set for each user and must point to a directory that is writable for the user that wants to launch an application.

Installing new software

New software is typically installed by the Administrator that has full permissions in the Installation Area. The administrator is either using the provided Installer or a Click & Start file in order to install the new application. After that step the application is available and can be launched by each new user by using the CLick & Start file.

Updating software

Whenever a new Product version is Activated on the server the administrator needs to launch the application once to deploy the new update. Not doing that will lead to an error that each user receives when trying to launch the application. The Launcher always checks for updates and tries to install them. Using an outdated application is not permitted and thus users will not be able to launch the application any more.

Required Software Update
Configuration changes in a client application - like adding, removing or changing a parameter - do not require Administrator attention since the installation itself is not affected. The change is automatically applied on the next start of the application.
Changing the product version or changing the launcher version on the server require a manual interaction of the Administrator otherwise NO user can use the client application anymore.

Central/Managed Specific Configuration

The Central/Managed Mode requires some configuration to attach CENTRAL and MANAGED servers.

On the CENTRAL server side:

  • Each Instance Group has a list of MANAGED servers attached to it.

  • Each Instance is associated with exactly one of those MANAGED servers.

  • Synchonization to the CENTRAL servers data store is done on demand (through a button in the Web UI). When synchonizing from a MANAGED to a CENTRAL server, only configuration data is synchronized. Actual product and application data is only synchronized when explicitly requested through the Product Synchronization page on the CENTRAL server.

  • It is possible to create a new Instance Version on the CENTRAL server from a Product Version which has been pushed only to the CENTRAL server (but not to the MANAGED). In this case, the required product data is sent to the MANAGED server once Install is performed on this Instance Version.

On The MANAGED server side:

  • Creation and editing of Instance Group (title, description, logo, etc.) is not possible locally. This has to happen on the CENTRAL server, as information must match.

  • Creation and editing of Instances (applications, parameters, etc.) is possible just the same as with a STANDALONE server. New data will be synchronized to the CENTRAL server the next time the CENTRAL server requests such a synchronization.

BDeploy is built for restrictive networks. The assumption is that the CENTRAL server can contact all its MANAGED servers, but never the other way around.

Attaching an Instance Group to a Central Server

You will notice that a MANAGED server will greet slightly different on the welcome page. Instead of a create instance group button, there is an attach instance group button, and the text reads accordingly.

Managed Server Welcome Page

Attaching an Instance Group is a two way operation.

  • The MANAGED server needs to share some details about itself with the CENTRAL server. This happens either via drag & drop of an element from the MANAGED servers Web UI to the CENTRAL servers Web UI, or manually by downloading the MANAGED servers information and dropping that file to the CENTRAL servers Web UI.

  • On the CENTRAL server, you will choose the Instance Group which should be attached. The Instance Group must exist on the CENTRAL server. If the MANAGED server happens to have an Instance Group of the same name already (i.e. if the MANAGED server was migrated from STANDALONE), this is perfectly fine - Instances in this Instance Group will not be lost, they will be attached to the CENTRAL server instead.

  • The CENTRAL server will try to contact the MANAGED server. You can provide an alternate URL to accomodate for hostname differences (different DNS, NAT, VPN, etc.) before it does so.

  • Once contacted, the CENTRAL server will push the Instance Group meta-data to the MANAGED server, as the information on the CENTRAL is the single source of Instance Group configuration.

  • Finally, the CENTRAL server will fetch all potentially existing Instance information from the MANAGED server. This is only relevant if the MANAGED server was migrated from STANDALONE mode before.

To attach in Instance Group, you need both Web UIs of CENTRAL and MANAGED server. Make sure you have both available and open in browsers next to each other (on the same machine, so drag & drop will work).

You can easily distiguish CENTRAL and MANAGED servers by the according banner in the upper right corner of the Web UI.

On the CENTRAL server, choose Context Menu  Managed Servers on the Instance Group you want to attach. This will take you to the Managed Servers page for this Instance Group. Initially, this page will be empty.

Managed Servers Page on Central

Click the Attach Managed Server button to initiate attaching a MANAGED server to this Instance Group.

Attach Managed Server Wizard

After the introductionary text, you will be prompted to drop MANAGED server information on a drop-zone. You can find the counterpiece on the MANAGED server. To initiate attaching on the MANAGED server, click the Attach Instance Group button on the main Instance Group page (which is the initial start page of the Web UI). This will launch the Attach to Central Server wizard.

Attach to Central Server

The next step in the wizard on the MANAGED server will provide the dragable card which needs to be dragged to the CENTRAL servers drop zone. Meanwhile, the MANAGED server will wait for an incoming connection from the CENTRAL server, once the information has been digested properly.

Attach to Central Server
Alternatively (e.g. if you cannot open both Web UIs on the same machine) you can click Continue Manually to download the information as a file. This file can be copied to a machine where access to the CENTRAL server is possible. There you can drop the file to the drop-zone, instead of the dragable card.

Once the information is dropped on the according drop zone on the CENTRAL server, it will confirm a successful read of the information. Click Next.

Successful read of Managed Server Information

On the next step, you have the chance to provide an alternative URL as well as a description of the MANAGED server. The alternate URL should be reachable from the CENTRAL server and accomodate for any hostname mapping required (NAT, VPN, DNS, …​).

Additional Managed Server Information

Clicking Next will initiate the actual attachment process. The CENTRAL server will contact the MANAGED server using the provided URL. It will then perform the initial synchronization of data. Once this is done, you will see a success notice which you can dismiss using the Done button.

Additional Managed Server Information

You will be taken back to the Managed Servers page, which shows the newly attached MANAGED server and its state.

Additional Managed Server Information

Instance Synchronization

Once a MANAGED server is attached to the CENTRAL server, Instance data can be synchronized from the MANAGED server on demand by the CENTRAL server. This can happen either from the Managed Servers page you saw before, by pressing Synchronize, or directly from the Instance. It is possible to synchronize both from the Instance Browser and from the Instance Overview page by pressing on the name of the MANAGED server. This element only exists on the CENTRAL server.

Synchronize Managed Server
It is not required to synchronize the other way (CENTRAL to MANAGED) as this happens implicitly when performing changes to an Instance. Changes are actually performed always on the controlling master, which is always the MANAGED server.

Migrating between Modes

There is a limited possibility to change the purpose of an already intialized BDeploy server root directory. It is only possible to migrate from STANDALONE to MANAGED and vice versa, as data is mostly compatible. A command line tooling exists for this purpose.

bdeploy set-mode --root=<root-directory> --mode=MANAGED

The value for mode may be MANAGED or STANDALONE. The actual migration of data may be performed later on when first accessing them. For instance, when clicking an Instance Group, you might be prompted that an Instance Group requires to be attached to a CENTRAL server in MANAGED mode, and the Attach to Central Server wizard is launched.

BDeploy server root directories are assumed to be of mode STANDALONE if they have been initilized with a BDeploy version prior to 1.4.0.

Product Synchronization

When working with CENTRAL and MANAGED servers, products can be uploaded to either of the servers. However, a product version must be available on the server which is used to update an Instance to that version.

The recommended way of working is to exclusively use the CENTRAL server for all tasks, e.g. pushing new product versions, changing configuration, etc. When installing an Instance version to the target server, the required product data is automatically transferred as part of the process.

Sometimes it might still be necessary to transfer product versions from one server to another. For instance, a product version was directly pushed to MANAGED server A, but is required as well on MANAGED server B. In this case you can use the Product Synchronization wizard to copy product versions from one server to another.

You can find the wizard on the Manage Products page on the CENTRAL server. The additional Synchronize button is only available on the CENTRAL server.

Synchronize Product Versions Button

Clicking it will launch the synchronization wizard. It allows to choose a source as well as a target server. You can choose both from all available MANAGED servers and the CENTRAL server.

Choose Source and Target

Clicking Next will fetch available products from the source server. Once you choose a product from the drop-down, all available product versions are fetch from both servers. You will be presented a list of versions which are not yet available on the target server.

Choose Product Versions

Clicking the arrow button on a product version, or dragging the version to the target list will mark this version as to-be-synchronized. Once satisfied with the selection, click Next to initiate the transfer of the product versions from source to target.

If both source and target are MANAGED servers, the CENTRAL server will also receive the product version as a side-effect.

The wizard will show progress information while the transfer is active. Once the transfer is done, the wizard will tell accordingly.

Product Transfer Done

Tutorials

This chapter contains a series of tutorials that cover the basics steps that a typical end user should be able to do.

How can I change a process configuration?

Changing the configuration of a Process is done in the Process Configuration Dialog:

  1. Click on the desired Instance Group

  2. Click in the desired Instance

  3. Ensure that the latest version is selected in the Instance Version sidebar.

  4. Open the menu of the desired Process by clicking the three dots in the top right corner of the Process Card

  5. Click on Configure. If View is shown then you are not on the latest Instance Version

  6. Modify the Process as desired: Rename, Change Parameters, Add / Remove Parameters

  7. Click on Apply in the top right corner if you are finished with this Process

  8. A new Locally Modified Instance Version has been created.

  9. Repeat the steps 4-7 with every Process that should be adopted.

  10. Click on Save in the top right corner.

The changes are now saved but they are not yet active. The new version must now be Deployed and all Processes must be restarted so that the changes have an effect.

  1. Open the menu of the desired Instance Version by clicking the three dots on the Instance Version Card

  2. Click on Install and wait for the operation to complete.

  3. Click on Activate

  4. A hint (Outdated) will be displayed if a Process is running in an older version.

  5. Stop the process by clicking on the Process Card. Click on the Stop button.

  6. Start the processes by click on the Start button.

  7. Repeat the steps 5-6 with each process that should be running

  8. The hint (Outdated) disappears once all processes are running in the active version.

The configuration changes are now live and all Processes are running again. The Process Settings and the Process Control chapters provide more details about the step outlined in this tutorial.

How can I see what’s up and running?

The status of an Instance is visualized with icons in the Instance Overview page at several places:

Process Card

BDeploy Tutorial Process Card

An icon on card shows the current status. No icon means the process is stopped.

Process Control

BDeploy Tutorial Process Control

The sidebar shows the current process status along with some additional information about the uptime. No icon means the process is stopped.

Instance Version

BDeploy Tutorial Process Versions

An icon on the card shows the cumulated status of all processes of this version. No icon means that nothing is running in this version.

The Process Control chapters provide more details about the individual process states along with a state graph that visualizes the life cycle of a process.

How can I deploy a new product version?

Upgrading the Product Version that is used in an Instance requires two distinct steps:

  1. Uploading the new Product Version

  2. Upgrading the Instance

Upload Product Version

Uploading a new Product Version is done in the Manage Products page:

  1. Click on the desired Instance Group

  2. Click on Context Menu  Products menu of the Instance Browser dialog

  3. A card for each Product is displayed. Clicking on the card shows all available versions

  4. Click on the Upload button in the bottom right corner

  5. Select the ZIP archive containing the new Product Version. This archive is typically created by your Build tool

  6. Click on Upload to transfer the file to the server.

The Product Version is now available and can be used in all Instances of this Instance Group.

Upgrade Instance

Changing the Product Version of an Instance is done in the Instance Overview dialog:

  1. Navigate back to the Instance Browser dialog by clicking on the back button

  2. Open the desired Instance

  3. A hint is displayed that a newer Product Version is available

  4. Clicking on this hint opens the Product Version sidebar

  5. Click on the Upgrade button of the desired version

  6. The sidebar is closed and a new locally modified Instance Version is created

  7. All Applications are marked as modified as they are now based on a different Product Version Hint: Changing the Product Version can result in validation issues if new mandatory parameters are introduced

  8. Adopt the configuration of the Processes as required

  9. Click on Save in the top right corner to save this version

The Instance is now based on the new Product Version. Remember that the new Instance Version must be Installed and Activated so that the changes have an impact. Please read the Process Configuration tutorial about more details how to do that.

Advanced Usage

Advanced Terms

Term Meaning

BHive

The actual storage backend. Provides data de-duplication and delta-based transfers. Synchronizing two BHives will transfer just the files that are not present in the other (potentially remote) hive.

Manifest

A Manifest is a unique Key which identifies a Tree of Files inside a BHive.

Software Repository

A Software Repository is a named BHive which is dedicated to storing Manifests which contain arbitrary deliverables. This is not necessarily a piece of software. It may be any set of files and directories.

When building a Product, it’s declared dependencies are resolved by querying all Software Repositories on the target BDeploy server.

Integration of a new product

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

app-info.yaml

YAML file to describe one single Application. It is required once for every client and server Application of the product.

product-info.yaml

YAML file with meta-data for the whole product.

product-version.yaml

YAML file required for every Product Version.

application-template.yaml

optional YAML file(s) which can be used to define Application Templates

instance-template.yaml

optional YAML file(s) which can be used to define Instance Templates

This chapter will walk you through these artifacs, what they are for and how to define them.

On the BDeploy Releases page you will find some zipped sample products for each release, see https://github.com/bdeployteam/bdeploy/releases

app-info.yaml

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 (whatever kind, 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 should be placed in the root directory of the Application it describes.

name: "My Application" (1)
type: CLIENT (2)

supportedOperatingSystems: (3)
  - LINUX
  - WINDOWS

branding: (4)
  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: (5)
  gracePeriod: 3000
  supportedStartTypes:
   - INSTANCE
  supportsKeepAlive: true
  noOfRetries: 5

startCommand: (6)
  launcherPath: "{{WINDOWS:launch.bat}}{{LINUX:launch.sh}}"
  parameters:
    - uid: "my.param.1"
      name: "My numeric parameter"
      longDescription: "This is a numeric parameter"
      groupName: "My Parameters"
      parameter: "--number"
      defaultValue: "5"
      type: NUMERIC
    - uid: "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"
    - uid: "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: (7)
        parameter: "my.param.2"
        must: EQUAL
        value: "Value 1"

stopCommand: (8)
  ...

endpoints: (9)
  http:
    - id: "my-endpoint" (10)
      path: "path/to/the/endpoint"
      port: "{{V:port-param}}" (11)
      secure: false

runtimeDependencies: (12)
  - "adoptopenjdk/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 master or slave Nodes 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 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.
4 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.
5 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.
6 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.
7 A conditional parameter is a parameter with a condition on it. The condition always refers to another parameter on the same application. The parameter with the condition set will only be visible and configurable if the condition on the referenced parameter is met.
8 The optional stop command can be specified to provide a mechanism for 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.
9 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.
10 The ID of the endpoint can be used to call the endpoint remotely by tunneling through potentially multiple levels of BDeploy servers.
11 Variable Expansion can be used on most of the endpoint properties.
12 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:adoptopenjdk/jre:1.8.0_202-b08}} Variable Expansion, e.g. launcherPath: {{M:adoptopenjdk/jre:1.8.0_202-b08}}/bin/java. Also note that the declared dependency does not specify an operating system. This will be resolved by BDeploy to either an exact match, e.g. adoptopenjdk/jre/linux:1.8.0_202-b08 on LINUX.
Supported processControl attributes
Attribute Description

supportedStartTypes

Can be either MANUAL (Application must be started explicitly through the Web UI or CLI), MANUAL_CONFIRM (Application must be started explicitly through the Web UI and a confirmation has to be entered by the user), or INSTANCE (the Application can be started automatically when the Start Instance command is issued, either manually or during server startup - implies MANUAL).

supportsKeepAlive

Whether this Application may be automatically restarted by BDeploy if it exits.

noOfRetries

The number of time BDeploy will retry starting the Application if it supportsKeepAlive. The counter is reset after the Application is running for a certain amount of time without exiting.

gracePeriod

How long to wait (in milliseconds) for the Application to stop after issuing the stopCommand. After this timeout expired, the process will be killed.

Supported parameters attributes
Parameters appear on the final command line in exact the order as they appear in the app-info.yaml file, regardless of how they are presented in the Web UI, or how they are grouped using the groupName attribute. This allows to build complex command lines with positional parameters through app-info.yaml.
Attribute Default Mandatory Description

uid

yes

A unique ID of the parameter within the whole product which will contain the Application described by this app-info.yaml.

name

yes

A human readable name of the parameter used as label in the configuration UI.

longDescription

no

An optional human readable description of the paramater, which is displayed in an info popover next to the parameter in the Web UI.

groupName

no

An optional group name. The configuration UI may use this information to group parameters with the same groupName together.

suggestedValues

no

An optional list of suggested values for paremters of type STRING (the default). The Web UI will present this list when editing the parameter value.

[CAUTION] Although parameters in the UI are grouped together (and thus might change order), the order in which parameters appear on the final command line is exactly the order in which they are defined in the app-info.yaml file.

parameter

yes

The actual parameter, e.g. --parameter, -Dmy.system.prop, etc.

The value of the parameter is not part of this definition, nor is any potential value separator (e.g. =).

hasValue

true

no

Whether the parameter has a value or not. If the parameter has no value, it is treated as BOOLEAN type parameter (i.e. it is either there (true) or not (false)).

valueAsSeparateArg

false

no

Whether the value of the parameter must be placed as a separate argument on the command line. If not, the value (if hasValue) will be concatenated to the parameter using the valueSeparator.

valueSeparator

=

no

The character (sequence) to use to concatenate the parameter and the actually configured value of it together. Used if not valueAsSeparateArg.

defaultValue

no

A default value for the parameter. The default value may contain variable references according to the Variable Expansion rules.

global

false

no

Whether this parameter is global. This means that inside a single Instance, every process requiring this parameter will receive the same value. The configuration UI will provide input fields for the parameter for every Application which requires the parameter, and propagate value changes to all other Applications requiring it.

mandatory

false

no

Whether the parameter is required. If the parameter is not required, it is by default not put on the command line and must be added manually through a dedicated dialog on the configuration page.

fixed

false

no

Whether the parameter is fixed. This means that the parameter can not be changed by the user.

Consider a command line like this:

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

In this case you will want the user to be able to edit the value of -Dmy.prop parameter, but the user may never be able to edit the -jar application.jar part. A definition for this command line would look like this:

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

The fixed flag will cause the parameter to always use the defined default value and disable editing in the configuration UI.

type

STRING

no

Type of parameter. This defines the type of input field used to edit the parameter. Available are STRING, NUMERIC, BOOLEAN, PASSWORD, CLIENT_PORT, SERVER_PORT

The CLIENT_PORT and SERVER_PORT types are treated like NUMERIC parameters throughout the whole application, with the exception of the dialogs that deal with ports specifically.

condition

no

A conditional parameter is a parameter with a condition on it. The condition always refers to another parameter on the same application. The parameter with the condition set will only be visible and configurable if the condition on the referenced parameter is met.

A condition expression (isolated) looks like this:

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

The condition block understands the following fields:

Name Description

parameter

the referenced parameters UID.

must

The type of condition.

value

The value to match against if required by the condition type.

The must field understands the following condition types:

Name Description

EQUAL

The referenced parameters value must equal the given condition value.

CONTAIN

The referenced parameters value must contain the given condition value.

START_WITH

The referenced parameters value must start with the given condition value.

END_WITH

The referenced parameters value must end with the given condition value.

BE_EMPTY

The referenced parameters value must be empty. In case of BOOLEAN parameters the value must be false.

Leading and trailing whitespaces are ignored for this check.

BE_NON_EMPTY

The referenced parameters value must be any non-empty value. In case of BOOLEAN parameters the value must be true.

Leading and trailing whitespaces are ignored for this check.
Be aware that the condition on a parameter has a higher precedence than mandatory. A mandatory parameter whos condition is not met is still not configurable. As soon as the condition is met, it is automatically added to the configuration using its default value.
If possible, a parameter with a condition should be defined after the parameter referenced in the condition if the referenced parameter is mandatory. This will make a difference when an application configuration is initially created by drag & drop.
Supported endpoints.http attributes
Endpoints definitions are templates which can later on be configured by the user. The only values not editable by the user are id and path.
Attribute Description

id

The unique ID of the endpoint. This ID can be used by an authorized third-pary application to instruct BDeploy to call this endpoint and return the result.

path

The path of the endpoint on the target process. BDeploy uses this and other parameters (port) to construct an URI to the local server.

port

The port this endpoint is hosted on. Variable Expansion can be used, for instance to reference a parameter of the application (using {{V:port-param}} where port-param is the ID of a parameter on the startCommand).

secure

Whether HTTPS should be used when calling the endpoint

trustAll

Whether to trust any certificate when using HTTPS to call the endpoint. Otherwise a custom trustStore must be set if a self-signed certificate is used by the application.

trustStore

Path to a KeyStore in the JKS format, containing certificates to trust. Variable Expansion can be used.

trustStorePass

The passphrase used to load the trustStore. Variable Expansion can be used.

authType

The type of authentication used by BDeploy when calling the endpoint. Can be NONE, BASIC or DIGEST.

authUser

The username to use for BASIC or DIGEST authType. Variable Expansion can be used.

authPass

The password to use for BASIC or DIGEST authType. Variable Expansion can be used.

product-info.yaml

There is no actual requirement for the file to be named product-info.yaml. This is just the default, but you can specify another name on the command line or in build tool integrations.

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

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)
versionFile: my-versions.yaml (9)
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 Optioanl: 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 The product-version.yaml which associates the Application IDs (used above) with actual paths to Applications on the file system.

product-version.yaml

There is no actual requirement for the file to be named product-version.yaml as it is referenced from the product-info.yaml by relative path anyway. This is just the default name.

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 an 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 . Therfore 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.

application-template.yaml

There is no actual requirement for the file to be named application-template.yaml as it is referenced from the product-info.yaml by relative path anyway. Multiple Application Template YAML files can exist and be referenced by product-info.yaml.

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"
description: "Server application which sleeps before exiting"

variables: (2)
  - uid: sleep-timeout
    name: "Sleep Timeout"
    description: "The amount of time the server application should sleep"
    defaultValue: 60
    suggestedValues:
    - '60'
    - '120'

processControl: (3)
  startType: MANUAL_CONFIRM
  keepAlive: false
  noOfRetries: 3
  gracePeriod: 30000
  attachStdin: true

startParameters: (4)
- uid: 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 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 A template can define arbitrary process control parameters to further control the default process control settings.
4 Start command parameters are referenced by their UID, 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.

instance-template.yaml

There is no actual requirement for the file to be named instance-template.yaml as it is referenced from the product-info.yaml by relative path anyway. Multiple Instance Template YAML files can exist and be referenced by product-info.yaml.

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"

variables: (2)
  - uid: sleep-timeout
    name: "Sleep Timeout"
    description: "The amount of time the server application should sleep"
    defaultValue: 60

groups: (3)
- 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 (4)
  - application: server-app (5)
    name: "Server With Sleep"
    description: "Server application which sleeps before exiting"
    processControl:
      startType: MANUAL_CONFIRM
    startParameters: (6)
    - uid: param.sleep
      value: "{{T:sleep-timeout}}"
- name: "Client Apps"
  type: CLIENT (7)
  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 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 phsysical node.
4 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.
5 A template group contains one or more applications to configure, which each 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 Tempaltes - except for the id which is not required.
6 Start command parameters are referenced by their UID, 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.
7 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.

Building a Product

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.

Via ZIP File and Web UI

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).

  • External dependencies must either be included in the ZIP or already be available in the Instance Group. Software Repositories are not (yet) supported.

Via CLI

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.

Via Gradle

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.

Add the below code to your existing build.gradle

build.gradle

plugins {
  ...
  id 'io.bdeploy.gradle.plugin' version '3.1.1-1' (1)
}

version = "1.0.0-SNAPSHOT" (2)

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

task buildProduct(type: io.bdeploy.gradle.BDeployProductTask, dependsOn: installDist) { (4)
  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) { (5)
  of buildProduct
  output = new File(buildDir, "product-" + project.ext.buildVersion + ".zip");
}


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

  target.servers {
    if(project.hasProperty('server')) {
      myServer { (7)
        uri = project.getProperty('server')
        token = project.getProperty('token')
        instanceGroup = project.getProperty('group')
      }
    }
  }
}

...
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 plain use the version set. The actual buildVersion used later when building the product is derived from the project version and the buildDate.
4 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.
5 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.
6 The pushProduct task can push required deltas to one or more configured target servers. When calling this task, you need to set according project properties, e.g. using -Pserver=https://server:7701/api or in ~/.gradle/gradle.properties.
7 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.

This file must be part of the binary distribution of an application and reside in its root directory. To achieve this, the most simple way (using the gradle application plugin) is to put the file in the subdirectory src/main/dist in the project folder.

src/main/dist/app-inf.yaml

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. You can configure a different set of Operating Systems to build for in the test application configuration in build.gradle.
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.

The reason why you want to put this file into a separate folder is because it allows to reference various other files by relative path. Those files (and folders) must the reside next to the product-info.yaml. Over time this can grow, and may clutter your source folders if you do not separate it.

bdeploy/product-info.yaml

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.

The build folder also contains the BHive in unzipped form in the build/productBHive folder. This folder is temporary but will hold all product versions built since the last ./gradlew clean. You can use this BHive for manual pushing.
The pushProduct task will do the same thing (build the product) but then push it to a target server. For this, you need to specify the server, token and instanceGroup project properties to match your setup.
Using ./gradlew clean buildProduct you can build the same product version over and over again. However once pushed to a remote server, the same product version must not be reused. If you try to build and push the same version more than once, the server will silently ignore your attempt to push, as it assumes that it already has all the content (it has a product with this version already, and all artifacts are assumed to be immutable in BDeploy).

Via Eclipse TEA

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.

TEA Integration Product Build

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

TEA BDeploy Server configuration

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

TEA BDeploy Login

Now you can use the Load Groups to fetch a list of existing instance groups from the server to choose from. Finally, use the verity 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.

TEA Integration Product Push
products.yaml
There is no actual requirement for the file to be named products.yaml. This is just the default, but you can specify another name in the Eclipse TEA preferences.

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

TEA Integration Products Preference

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.

product-build.yaml

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.

Variable Expansion

BDeploy provides a mechanism for variable expansion. There is a set of predefined possibilities. Currently, it is not possible to define your own variables, only the predefined set is available. Variable expansion can happen on the following:

  • Launcher path specified in app-info.yaml.

  • Any parameter value. Either user-set value or the defaultValue specified in app-info.yaml.

  • Any configuration file content.

  • Most of the HTTP Endpoints attributes.

Any of the above will be processed as late as possible, i.e. on the target node, right before writing the final content to the target directories.

The general syntax for variables is {{TYPE:VARNAME:SUBVAR}}. There are various types, usually denoted by a single character. The following section gives an overview of types, variables, and possible sub-variables.

M: Manifest Reference

Used whenever it is required to get the absolute installation path to another manifest’s path on the target system. The name of the variable indicates the manifest which should be references. An optional tag - separated with a ':' - can be added to refer to a specific version.

{{M:<Name of Manifest>:<Optional Manifest Tag>}}
Variable Description

{{M:openjdk/jre8}}

Expands to the absolute path where the OpenJDK manifest is installed on the server.

{{M:SELF}}

Expands to the absolute path where the manifest is installed on the server which contains the app-info.yaml for this application. This substitution shortcut is only supported in app-info.yaml files.

P: Deployment Path

Used to expand to one of the special directories that are defined.

{{P:<PATH_ID>}}
Variable Description

{{P:CONFIG}}

Directory where all configuration files are stored.

{{P:BIN}}

Directory where all binaries are are stored.

{{P:RUNTIME}}

Directory with runtime data (e.d. stdout/stderr capture files) is stored.

{{P:DATA}}

Directory shared by multiple deployments of the same instance.

V: Parameter Value

Used to reference a parameter within the same application or withing any other application from the same instance. Typically used when one application publishes a service on a specific port (server) and other applications (clients) should then connect to this port. The configuration of the client applications would then refer to the port of the server application. Thus when changing the port only the configuration of the server application must be adopted.

{{V:<PARAM_ID>}} - Refers to a parameter defined in the same application
{{V:<APP_NAME>:<PARAM_ID>}} - Refers to a parameter defined in the application with the given name
Variable Description

{{V:my.param.uid}}

Takes the value from the my.param.uid parameter defined in the same application.

{{V:MyServer:my.param.uid}}

Takes the value from the parameter my.param.uid that is defined in the MyServer application.

Beware that changing the name of an application will break the parameter reference mechanism. There is no mechanism that automatically adapts the configuration of applications which refer to values of other applications. This must be done manually if required.

I: Instance Value

Used to expand to values related to the instance containing the parameter’s process.

{{I:<VAR>}}
Variable Description

{{I:SYSTEM_PURPOSE}}

The purpose of the instance in upper case letters. (PRODUCTIVE, TEST, DEVELOPMENT)

{{I:UUID}}

UUID of the instance

{{I:NAME}}

Name of the instance

{{I:PRODUCT_ID}}

Name of the 'MANIFEST' keys name of the configured product

{{I:PRODUCT_TAG}}

The tag (i.e. 'version') of the configured product

A: Application Value

Used to expand to values related to the application containing the parameter’s.

{{A:<VAR>}}
Variable Description

{{A:UUID}}

UUID of the application

{{A:NAME}}

Name of the application

H: Minion Properties

Used to expand to properties of the minion where the application is deployed.

{{H:<VAR>}}
Variable Description

{{H:HOSTNAME}}

Expands to the hostname of the target minion where the application is deployed.

Beware that due to the nature of variable expansion (the point in time this happens), HOSTNAME may not be what you expect, especially on global parameters used by multiple processes (it can be a different hostname for each process, if they are configured to different nodes). Even more precaution is required when using HOSTNAME on client applications, as it will expand to the clients hostname.

Operating System

Enables conditional output of text based on the current operating system. The name of the variable refers to the name of the operating system. Using this variable allows the usage of different arguments for different operating systems while still using a single YAML file.

{{OSNAME:<conditional output>}}
Variable Description

{{LINUX:java}}

Expands to java on on Linux

{{WINDOWS:java.exe}}

Expands to java.exe on on Windows

java{{WINDOWS:.exe}}

Expands to java on Linux and java.exe Windows

Environmental Values

Enables access to environmental variables defined in the operating system. The name of the variable refers to the name of the environmental variable.

{{ENV:NAME}}
{{DELAYED:ENV:NAME}}
Variable Description

{{ENV:MY_VARIABLE}}

Expands to the value of the environmental variable when the application is installed on the node or client.

{{DELAYED:ENV:MY_VARIABLE}}

Expands to the value of the environmental variable when the application is launched on the node or client.

Variables are replaced with their actual values when the process is installed on the target minion node. This might not always be desired. Especially for client applications it can be useful to do the actual replacing when the process is launched. This is can be achieved by prefixing the actual variable with the DELAYED prefix. This enables that different users of the client application are getting different parameter values depending on the value of the environmental variable.

Runtime Dependencies

As you saw before (app-info.yaml), Applications can declare dependencies to third-party Manifests. These Manifests are hosted in Software Repositories on the BDeploy Server.

To make them available on the server, you need to:

  • Use bhive import to import the directory containing the third-party software into a local BHive.

  • Use bhive push to push the created Manifest to the Software Repository of your choice.

Manifest Naming

Third party software Manifests can have basically any name. If you want to provide different Manifests per target operating system though, you will have to follow a simple naming rule: append the operating system name to the Manifest name part, e.g.:

  • my/external/software/windows:1.0.0

  • my/external/software/linux:1.0.0

It can then be referenced by an app-info.yaml using the short-hand syntax my/external/software:1.0.0 and BDeploy will choose the correct one depending on the target operating system.

Runtime Dependency Packaging

BDeploy will always make sure that your products are self contained. This means that Runtime Dependencies are packaged with the product data at build time. The result is a product which contains all dependencies. This also means that pushing a product to a target server does not require any prerequisites on that target server.

Included runtime dependencies will not show up on the target server’s Web UI anywhere. Especially there is no Software Repository created automatically for any third-party software. It is simply included in the product.

Software Repositories

The Software Repositories page allows maintenance of external software that a specific product requires. A Software Repository shares its namespace with Instance Groups, which means that the unique name of a Software Repository must not collide with any name of a Software Repository or Instance Group.

Software Repositories

Upload software

To upload external software, open a software repository and click on the upload button on the bottom right.
Then click on browse or drop files. You can only upload zip packages.

After selecting files, specify the shown name of the software, the version and the supported operating systems.
If you already have a package in a hive structure containing all of this metadata, enable hive.

External Software Upload

If the upload was succesful, you can close the upload dialog and the software for each operating system will show up.

Software Repository with External Software

The available software packages can be viewed and downloaded if required.

Software Details

Software Repositories Access

Software Repositories are created and managed by global administrators. A Software Repository is always visible and readable for all users. Write permissions are required to manage the software packages in the repository. To be able to upload software, a user therefore requires global administration or write permissions or must have write permissions assigned directly to the repository.

Global Software Repository Permissions

Use the + button to add a user to the list. The input field suggests matching users from the list of all users.

Grant Write Access to the Software Repository

Adding a user grants write access to the Software Repository. The bin icon in the last column removes the user from the list. Users with global administration or write permission cannot be removed.

Grant Write Access to the Software Repository

Experts

This chapter contains additional information for expert users, administrators of the system as well as those that want to use the CLI for features that the UI does not provide.

Administration

There are several components in the Web UI which allow maintenance of BDeploy. These are not to be used during normal operation by users. They are required during setup and to maintain current software versions of BDeploy itself if not done using the bdeploy remote-master CLI.

General Settings

Gravatar support can be enabled in the general Look & Feel settings.

BDeploy Look & Feel Settings

Authentication

BDeploy supports both built-in and external authentication mechanims. The built-in user authentication can be disabled completely in the settings.

BDeploy Authentication Settings

On the LDAP tab, you can configure a list of LDAP servers which should also be queried when authenticating a user.

BDeploy LDAP Servers

You can use the up and down arrows to control the order in which LDAP servers are queried for users that log on.

BDeploy uses simple bind to authenticate users. First, a simple bind is made with a configured Server User. This user must have permissions to list other users that should be able to log into BDeploy. This bind is used to query for a user where the Result User Field matches the given (at login) user name. This can be any field like user, sAMAccountName, or even mail if you want users to log on using their E-Mail Address. Once the user to log on is found, it’s distinguished name is used to perform another simple bind using the login-provided password. Once this succeeds the user is authenticated and an according record is created in BDeploy. From that point on, permissions can be granted to this user.

BDeploy LDAP Server Configuration
LDAP Server Properties

The following properties can be configured for each LDAP Server:

Property Description

Server URL

The URL of the LDAP server. Both ldaps:// (with a proper certificate on the server) and ldap:// are supported. ldaps:// should be preferred where possible. Self-signed certificates are currently not configurable inside BDeploy (although they can be configure on the operating system).

Server User

The user which is used to query other users on the LDAP server

Server Password

The password for the Server User which is used to query other users on the LDAP server.

Account Base

Root of the LDAP tree containing all user accounts to query. Typically in the form of dc=domain,dc=com.

Account Pattern

A partial LDAP query expression. Multiple filters can be written one after another. The final LDAP query is built by prepending (&, and appending a filter which queries the configures Result User Field for the given user. Thie means that a pattern (field1=value1)(field2=value2) will result in a query like (&(field1=value1)(field2=value2)(sAMAccountName=<GIVEN USER>)).

Result User Field

Specifies the field which must match the given username when querying for the user.

Result Full Name Field

The field which should be used as source for the Full Name of the user, which is used as a display name in User Accounts management.

Result E-Mail Field

The field which should be used as source for the users E-Mail Address. This is used for instance to query Gravatar if Gravatar support has been enabled in the General Settings.

User Accounts

The User Accounts dialog lists all users known in the system, regardless of whether they are local users or LDAP users.

BDeploy User Accounts

Use the + button to create a local user.

BDeploy User Accounts

The pull-down menu at the end of each table entry contains actions for modifying a user. The Edit button opens a popup for editing the display name and the email address of a user.

BDeploy User Accounts

The global permissions can be changed using the Global Permissions button in the pull-down menu.

BDeploy User Accounts
Permission Meaning

READ

Only those Instance Groups for which a user has READ permission are displayed. Users with global READ permission can see all Instance Groups. READ permission allows the user to read the Instance Group without making any modifications.

WRITE

The WRITE permission allows a user to maintain the contents of an Instance Group without modifying the Instance Group itself. The WRITE permission contains the READ permission. Users with global WRITE permission can maintain all Instance Groups.

ADMIN

The ADMIN permission contains the WRITE and READ permission and allows full access to an Instance Group. Users with global ADMIN permission have full access to all Instance Groups and additionally to the BDeploy system configuration.

The Set Active and Set Inactive actions are used to disable an account without deleting it i.e. to activate it again.

BDeploy User Accounts

BDeploy Update

The BDeploy Update page from the Administration menu offers a mechanism to upload new BDeploy software versions, deploy these versions (upgrade and downgrade possible) to the running BDeploy master and attached slaves.

BDeploy System Software

It also offers a way to upload and also to download BDeploy Launcher binaries. These binaries are required when CLIENT Applications are configured. Use the Upload button to upload new BDeploy versions from the binary distributions (ZIP).

The page can also be used to download the binaries of BDeploy (e.g. to setup additional slaves) and the BDeploy Launcher binaries (e.g. for manual setup of the BDeploy Launcher on client PCs, see Client Applications).

Manual Cleanup

You can use the Manual Cleanup page from the Administration menu to trigger a manual cleanup of stuff that is not needed any more. There is no need to trigger this manually as a job is scheduled that performs the exact same operation every night:

Target Description

Instances with Auto Uninstallation enabled

If the option Automatic Uninstallation is enabled on an Instance, Instance Versions that are older than the activated and the previously activated Instance Version are uninstalled automatically.

Instance Groups with Automatic Cleanup enabled

If the option Auto Cleanup is enabled on an Instance Group, old Product Versions that are no longer in use by Instances of this Instance Group are deleted automatically. To avoid that a Product vanishes completely, the very latest Product Version always remains.

Slave

Delete Manifests that are not known by the master

Slave

Keep two BDeploy Launcher versions, delete all older versions.

Slave

Remove unused directories and files in the deployment (including pooled applications), download and temp directory.

The dialog can be used to immediately trigger a cleanup and to reviewing of the actions performed before doing so.

BDeploy Cleanup Page

Press the Calculate Cleanup Actions button to perform cleanup calculation. The result will be groups of actions to be performed on Instance Groups or Slaves. The result contains only Instance Groups and Slaves for which actions are actually calculated, i.e. empty lists are hidden. If no action is calculated at all, a corresponding message is displayed.

BDeploy Cleanup Actions

Press the Execute all Actions button to actually perform the calculated actions.

The dialog automatically resets itself after a certain timeout. This is to prevent execution of too old actions which might no longer be valid.

Hive Browser

The Hive Browser from the Administration menu is an internal tool for administrative purposes. It allows viewing and browsing the internals of the BDeploy storage. The drop-down at the top of the dialog is used to switch between the available hives. The default hive is the internal storage where metadata about users and outer hives are stored. The actual data is stored in the individual hives itself.

It has the power to destroy everything - use with extreme caution.

Hive Audit Logs

The Hive Audit Log browser allows to view all audit logs on any of the BHive managed by the server.

Audit Log

The system Audit Log browser allows to view the master servers main audit log, which includes information about tools run on the root directory, as well as every request made to the APIs.

Metrics

This dialog provides a quick way to investigate potential performance issues in the server itself by providing access to the in-memory metrics kept track by the server for all actions and requests performed.

The SERVER metrics will show various system information about the Java Virtual Machine of the master hosting the Web UI.

Log Level

You can adjust the log level of the Web UI (i.e. logging in the Browser Console) using the drop down at the bottom of the BDeploy main menu. The default value depends on whether the application is started in development (i.e. from VSCode) or production mode.

BDeploy Main Menu

Command Line Interface

BDeploy provides a rich CLI which allows automating most interactions with BDeploy, e.g. for use in build pipelines, etc.

The same binaries used to run a BDeploy server provide a set of commands along with available options. This chapter describes the available commands. The options are well-described when calling the according command with the --help option.

Common Options

Option Description

-q

Quiet - no progess reporting on long running operations.

-v

Verbose - some tools may include additional information.

-vv

Very verbose - enable progress reporting for every tool, show timing summary at the end.

-o FILE

Redirect output to the given FILE.

-op FILE

Redirect progress reporting output to the given FILE.

--csv

Output any data in CSV format.

--json

Output any data in JSON format.

BDeploy CLI

Initialization and local configuration management commands
Command Description

certificate

Manage the server certificate (export the existing, import a new). This is mainly used to import a properly signed certificate to the master, which serves the Web UI using this certificate over HTTPS. BDeploy itself does not require a properly signed certificate for internal operation to guarantee Security.

cleanup

Manage the schedule at which the master performs background cleanup operations on all nodes (including himself).

hostname

Allows 'renaming' of the minion. The init command stores the given hostname, used later on for connections to self and also for variable expansion. If the hostname changed or is no longer valid, the hostname tool can update all relevant data.

init

Initializes a root directory for running a server with either the slave or master commands.

set-mode

Changes the intended purpose of a BDeploy root directory, see Migrating between Modes.

storage

Manages available storage locations. A storage location is a folder where the BDeploy master puts the BHives required to store data for Instance Groups and Software Repositories.

Local session and scripting commands
Command Description

login

Manages local login sessions to remote servers. This command eliminates the need to manage URIs and tokens yourself. Login sessions are managed per user, can be created, switched and removed. Validity of the login session is the same as for the Web UI. Subsequent commands will use the configured remote login session to perform remote communication.

Since login sessions are persistent, it can be easy to confuse which session/server is currently worked with. Always verify that the correct session is actively used by commands when performing modifications on the server, e.g. deleting an Instance.

shell

Provides an interactive shell which can execute tools. The shell can also be fed with a script file which contains a series of commands.

Product management commands
Command Description

product

List or create Products locally. Fetches required dependencies from the given remote BDeploy server. Has the ability to push the resulting Product to the target BDeploy server.

Remote server management commands
Command Description

remote-central

Manage remote configuration related to managed servers on a central server. Also allows to attach managed servers to a central server.

remote-deployment

Manage Instance deployment (install, activate, uninstall, updateTo (product version)) on a remote BDeploy server.

The --updateTo command will only work if the new product version can be updated to without manual changes. If for example a mandatory parameter is added, or a configured application is removed from the product, the update will fail.

remote-group

Manage Instance Groups on a remote BDeploy server.

remote-instance

Query and manage Instances on the remote BDeploy server. Can be used to export (to ZIP) and import (from ZIP) Instances locally.

remote-master

Query and manage system information on a remote BDeploy server. Allows to update both the BDeploy system software as well as the BDeploy launcher binaries.

remote-plugin

Manage plugins available on the remote BDeploy server or install new ones from local jar files.

remote-process

Query and manage application processes managed by BDeploy on a remote BDeploy server.

remote-product

Query and manage products available on the given Instance Group on a remote BDeploy server.

remote-repo

Query and manage Software Repositories on a remote BDeploy server.

remote-user

Manages users on a remote BDeploy server.

Server commands
Command Description

master

Runs the BDeploy minion in master mode. Requires a root directory initialized with the init command.

A master is always a slave as well. The master just has the additional capability to control other slaves, and provides the configuration Web UI.

slave

Runs the BDeploy minion in slave mode. Requires a root directory initialized with the init command.

Also used to register a slave with the master. For this, the slave command is run on the master with the --add option.

Utility commands
Command Description

bhive

Wraps around to the BHive CLI. Can be used to access BHive CLI commands if the BHive stand-alone binaries are not available. Usage: bdeploy bhive <command>

BHive CLI

BHive is the underlying storage used by BDeploy. BDeploy serves BHives for all minions (master and slave), and has additional BHives per Instance Group and Software Repository on the master.

BHive itself is does not know about BDeploy, it is 'just' a dumb storage backend (which is responsible for de-duplicated, distributed, fail-tolerant (failure-recoverable) storage of file contents).

Much like Git, BHive only knows two commands that actually perform remote communication: fetch and push. All other commands are performing their work locally.

Analysis and maintenance commands
Command Description

fsck

Performs a file system check (fsck). This involves resolving all inter-Manifest dependencies, as well as re-hashing all objects in the underlying storage to assert that all objects in the storage are valid.

Also allows to fix found errors (by deletion). After this, missing Manifests must be re-pushed from a BHive which still has the required objects.

manifest

Manage existing Manifests in a given BHive.

prune

Remove unreferenced objects from the given BHive to free up disc space.

token

Allows generation of new access tokens, see Security.

tree

Read and diff Manifests from the given BHive. Allows to compare the contents of Manifests, view differences and the estimated data transfer required to perform a delta 'update' if a potential remote BHive already has one of them.

Filesystem interaction commands
Command Description

export

Reads a Manifest from the given BHive and writes it’s content to a given target folder.

import

Import a given folder into a given BHive and associate the given Manifest key with it.

Remote server interaction commands
Command Description

fetch

Fetches the given Manifests from a given remote BHive.

push

Push the given Manifests to the given remote BHive

Server commands
Command Description

serve

Serves one or more given BHives over the network. The same thing as BDeploy does internally, provided as CLI tool for maintenance reasons.

Launcher CLI

Command Description

launcher

Reads a given .bdeploy file, which describes all required information for the launcher to contact a BDeploy server and download a client application.

uninstaller

Uninstalls a given application and cleans up in the local storage.

Environment Variables

BDeploy and BHive CLIs provide a set of environment variables that allow you to provide environment defaults for certain command line arguments.

Each command will include information for the according environment fallback in it’s help output, for instance:

$ bhive push --help
Help:

Usage: PushTool <args...>
               --token=ARG: Token for the remote access. Can be given alternatively to a keystore.
                            (Environment variable 'BDEPLOY_TOKEN' is used as fallback if not given)
              --remote=ARG: URI of remote BHive. Supports file:, jar:file:, bhive:
                            (Environment variable 'BDEPLOY_REMOTE' is used as fallback if not given)
              ...
Variable Description

BDEPLOY_LOGIN

Specifies the name of a stored login session (bdeploy login) to use. This overrides the currently active login session if there is one.

BDEPLOY_REMOTE

URL to the remote BDeploy server which commands should connect to, e.g. https://hostname:7701/api.

BDEPLOY_ROOT

The root directory to use for init, master and slave (primarily).

BDEPLOY_TOKEN

The actual security token used to access the remote BDeploy server.

BDEPLOY_TOKENFILE

A file containing the security token (as text content) used to access the remote BDeploy server.

BHIVE

Path to the BHive to operate on for local commands (e.g. import, export).

REMOTE_BHIVE

The name of the remote BHive. In case of BDeploy this is usually the name of an Instance Group or Software Repository.

Security

BDeploy uses HTTPS everywhere along with advanced security tokens which allow mutual authentication for every request. Think of it as a combination of JWT and mutual certificate based authentication.

This mechanism is used for every remote communication, especially for every remote communication which would cause a state change in BDeploy. There are some endpoints in the Web UI backend which must be unsecured by design (e.g. the one performing authentication and issuing the security token for all following remote communication).

As a consequence, a security token is required for all CLI commands that communicate with a remote BDeploy server, when registering a slave with a master minion (as they communicate), and for all toolings which communicate otherwise with BDeploy (e.g. build integrations which fetch dependencies and push Products to BDeploy).

Certificates

BDeploy by default generates a self-signed certificate which is used to secure both the internal communication and the Web UI (HTTPS).

It is possible to exchange this certificate with a proper one if the security warning in the Web UI is undesirable.

Exchanging the certificate will currently invalidate all issued security tokens. The ones issued to authenticated users, as well as the ones used to register BDeploy minions with other BDeploy servers.
Current swapping is possible only manually, proper CLI support pending.

Endpoint Proxying

BDeploy supports proxying (tunnelling) to application endpoints as defined in the app-info.yaml.

The application hosting the endpoint to call can be hosted on any slave in the system. As long as this slave is attached to a master you can reach (directly in STANDALONE or MANAGED mode, or indirectly in CENTRAL mode), you can tunnel there using BDeploy.

You will need these to be able to call an Endpoint of a remote application through the BDeploy public API:

  • A BDeploy slim token to be supplied for an authorization header in the form of X-BDeploy-Authorization: Bearer <TOKEN>. You can obtain this token from the Web UI for the logged in user.

  • The id of the instance group hosting the application you want to tunnel to.

  • The uuid of the instance hosting the application you want to tunnel to. You can see this id for instance from the browsers URL when on the instance overview page for the instance in question.

  • The id of the applications endpoint as defined in the app-info.yaml.

  • The uuid of the application which hosts the endpoint identified by the endpoint id above.

A typical proxy call using the public API would look like this, when using cURL:

curl -k -H "Accept: */*" \
    -H "X-BDeploy-Authorization: Bearer <X>" \ (1)
    "https://server/api/public/v1/common/proxy/myEndpoint?BDeploy_group=MyGroup&BDeploy_instance=xxxx-111-xxxx&BDeploy_application=yyyy-111-yyyy" (2) (3) (4) (5) (6)
1 <X> is a bearer token, which can be obtained from the Web UI (User drop-down menu).
2 server is the hostname (and port) of the BDeploy master. This may be either a CENTRAL, MANAGED or STANDALONE server, being in charge (directly or indirectly) of the application to tunnel to.
3 myEndpoint is the id of the endpoint to call as defined in the app-info.yaml of the hosting application.
4 MyGroup is the id of the instance group which hosts the application to tunnel to.
5 xxxx-111-xxxx is the uuid of the instance which hosts the application to tunnel to.
6 yyyy-111-yyyy is the uuid of the application which hosts an endpoint with the given endpoint id.

How to obtain required IDs

There are two ways to obtain required IDs. You can use a pure manual approach and for instance deduce ID’s from URLs and the Web UI itself. Or you can use the public API to query BDeploy for available objects.

http://my-server/#/instance/overview/MyGroup/xxxx-111-xxxx

From the above URL, you can find the instance group id (MyGroup) as well as the instance uuid (xxxx-111-xxxx). When on the instance overview page, click the server application you want to tunnel to. The process control panel for that application opens up, and you will see the applications id displayed right beneath its name.

Last thing to manually lookup is the endpoint id. Endpoints can be accessed in the process' context menu by choosing Context Menu  Endpoints

Process Context Menu

You will be able to read the endpoint id and configure properties of the endpoint on this page. The configuration will be used by BDeploy when instructed remotely to call that endpoint. BDeploy will take care of things like authentication, security, etc. The actual caller will only require access (and permissions) on the master server he is calling into, not to the actual application. Instead, BDeploy itself is configured to be authorized to perform the call.

Process Endpoints Configuration

For automatic lookup, you can use the following BDeploy public API endpoints. Those are provided by the master server, same as the actual proxy endpoint:

# will list instance groups
curl -k -H "Accept: application/json" \
    -H "X-BDeploy-Authorization: Bearer <X>" \ (1)
    "https://server/api/public/v1/instanceGroups"

# will fetch the latest configuration of all instances in an instance group
curl -k -H "Accept: application/json" \
    -H "X-BDeploy-Authorization: Bearer <X>" \
    "https://server/api/public/v1/common/instances?BDeploy_group=MyGroup&latest=true" (2)

# will fetch all endpoints exposed by a certain instance along with the uuids of the applications hosting them.
curl -k -H "Accept: application/json" \
    -H "X-BDeploy-Authorization: Bearer <X>" \
    "https://server/api/public/v1/common/endpoints?BDeploy_group=MyGroup&BDeploy_instance=xxxx-111-xxxx" (2) (3)
1 <X> in all the following cURL calls is the bearer token as obtained from the Web UI.
2 MyGroup is the name of one of the instance groups as obtained by the first API. You can fetch the uuid of each instance from the returned JSON.
3 xxxx-111-xxxx is the instance uuid as obtained by the last API. The returned JSON will include the application uuid hosting the endpoint along with the actual specific configuration of that endpoint (including its id).

FAQ

Q: When uploading an update, why are some servers not updated?

There are a few reasons why an update could not be performed.

First, BDeploy packages are available for multiple operating systems. Since BDeploy fully supports multi-OS setups, you might have uploaded an update package only for one OS, and the servers which did not update correct run another OS. Please make sure to always upload all available OS packages of BDeploy to assure smooth updating.

Second, BDeploy packages might have a minimum required source server version. Since multi-node setups could in theory have heterogenous versions installed, this minimum server version is checked right before applying the update on this particular server, not centrally. This means that a server can refuse installing the update. You will find a hint in the logs of that server. The BDeploy release notes should contain further instructions in this case - most likely instructions to update to another version of BDeploy first.