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 physical node used by BDeploy. In a multi-node setup one minion takes the role of a master. All others act as headless nodes 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 --add=MyServer --remote=https://host:port/api
bdeploy remote-master --update=<path-to-update.zip> --useLogin=MyServer

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

Existing nodes 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 nodes as well when applying it to the master.

Master

Modes of Operation

BDeploy may be set up in different modes, making a few different overall usage scenarios possible:

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

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

  • NODE mode: A node which can be attached to either a STANDALONE or MANAGED server as additional target location 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 Linux) 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 access token to a file if given with --tokenFile. This tokens main purpose is automation (scripting) and testing. The token is a system token which is not associated with any actual user. This token is important when initializing a root for a NODE, as it will be required when attaching the NODE to a STANDALONE or MANAGED master. On the master you can generate a token for any user from the BDeploy UI anytime later on.

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 NODE - see Node).

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 start command.

Be aware that the user running the start command later on must be the owner of the root directory. Otherwise BDeploy will run into problems when accessing files. If you configure BDeploy as a service make sure to either run the service as the same user who initialized the root directory, or pass ownership of the root directory to the user running the service before starting it.

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>

Node

Nodes 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 node as well where applications can be deployed to.

Initializing

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

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

Again, the init command will output the system access token for this node (if --tokenFile is not used). You need it to register the node with the master, so keep it around or use --tokenFile=node-token.txt to store the token into a file.

Launch

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

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

Registration

To register a node with the master use this command on the master root:

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

The node is now registered as 'node-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 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 | --node      Start a master or node (only controls the name of the service.)
<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. We strongly recommend to use a non-priviledged user to run the BDeploy service.

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

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 BDeploys services are running on the according physical 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:

┌────────────────────────────────────────────────────────────────────────────────────────────┐
│ Minions on https://localhost:7701/api                                                      │
├──────────────────────┬──────────┬───────────────────────────┬────────────┬─────────────────┤
│ Name                 │ Status   │ Start                     │ OS         │ Version         │
├──────────────────────┼──────────┼───────────────────────────┼────────────┼─────────────────┤
│ master               │ ONLINE   │ 19/10/21, 11:36 AM        │ WINDOWS    │ 4.0.0           │
│ node                 │ OFFLINE  │ -                         │ WINDOWS    │ 4.0.0           │
└──────────────────────┴──────────┴───────────────────────────┴────────────┴─────────────────┘

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. The active login can be set using bdeploy login --use=<loginName> (to set the default permanently) or individually/temporary per command using the --useLogin=<loginName> option.

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, either through global or scoped permission.

The main menu - which is always present on the left side of the screen - can be expanded using the hamburger button. This will provide a more readable version of the main menu. The content of the main menu depends on the current application context. This means that items will be added whenever more context is available, e.g. when clicking on an instance group, and removed when leaving this context.

BDeploy Main Menu

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

BDeploy User Settings
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.

Common UI Elements

BDeploy tries to follow a few quite simple patterns regarding UI/UX. The common parts of the UI which is the same for nearly all pages is described in this section.

The search bar at the top of the screen can be used to search in the current page. It will filter all tables and lists in the current page, regardless of where the table is located.

Search Bar

The search bar might be disabled in case there is no element on the screen currently which can be filtered.

Disabled Search Bar

Panel

The panel is the area on the left side of the screen which typically contains content related to the content in the main area. This panel is invisible by default, and slides into view when the according content is available. This is typically triggered by clicking an entry in a table or a toolbar button. An example for a panel is the Create Instance Group panel, which will also be one of the first panels you’ll see in the application.

Panel

Table vs. Card View

A lot of tables throughout the BDeploy UI offer the possibility to display them as cards instead of as a list. This is done by clicking the corresponding button in the toolbar of each dialog.

Table Mode
Card Mode

Grouping

Most tables offer the possibility to group the entries by a certain criteria. The criteria may be predefined or freely configurable, depending on the type of data in the table. Grouping can be changed using the Data Grouping toolbar button.

Data Grouping

Groups are represented as collapsable sections in the table. Multiple levels of grouping are supported in table mode. Press the + button to add an additional level of grouping and choose a criteria to group. Pressing the - button will remove the last level of grouping.

The Save as local preset button will save the current data grouping settings as preset in the browser storage. This will be the default grouping settings whenever you open the same page again.

Grouping works differently in Card Mode. Only one level of grouping is supported in card mode, and groups are displayed as tabs instead of sections.

This not actually a visible element of the BDeploy UI, but a feature you can use when sharing links with colleagues. All locations in BDeploy are deep-link capable, meaning you can copy the current URL from the browser and send it to somebody else. When opened, the other Browser will see exactly the same page as you do, including the currently open panel.

Instance Group

An Instance Group acts as logical container for 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 group has been created.

Empty Instance Group Overview

Use the + button in the toolbar to create a new Instance Group.

Create Instance Group
The name of an instance group cannot be changed, and is used internally as a name in the file system on the server. Be careful 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 Dialog

All Instance Groups that are visible to the user (as per the assigned permissions) are shown in the Instance Groups dialog.

Demo Instance Group

Instance Group Access

A new Instance Group is initially only visible to users with global read permission (or higher). You can assign permissions to users either globally, or per Instance Group. To assign local permissions, click the Instance Group to get to its instance overview and then click the Group Settings toolbar button. The Group Settings panel is shown.

Instance Group Settings

Click the Instance Group Permissions button to navigate to the permission panel.

Instance Group Permissions

To assign a local permission to a given user, click the Modify button in the according table row. A dialog will pop up asking for the permission to assign. Choose an apropriate one and click OK.

Instance Group Permission Assignment

The local permission will be shown next to the global permission. The highest available permission level is taken into account for any permission checks.

Instance Group Local Permission

The user table is grouped by permission assignment, either global, local or unassigned.

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

Empty Instance Browser

Since an Instance requires a Product, an empty Instance Group will initially display a shortcut to the products page. If there is at least one Product available already, the shortcut changes to the help you to create a new instance.

Empty Instance Browser with Product available

Manage 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 to experiment with for each release, see https://github.com/bdeployteam/bdeploy/releases
Empty Products Page

On the Products page, click the Upload Product button to upload new Products.

Upload Product

Click browse and choose a Product ZIP file to upload, or simply drop on on the highlighted drop zone. The Product will be uploaded immediately.

Upload Product (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 in use by an Instance version. There rest of the panel provides additional information about the Product.

Product Details Panel

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

Create a new Instance

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

Click an Instance to proceed to the Instance Dashboard.

Instance Browser

Instance Dashboard

The Instance Dashboard is the central location for managing an instance. It provides an overview about all configured Processes and on which nodes they are running. Each Process is represented by an entry on the according node.

If the instance has no active version yet, the dashboard is empty and shows a shortcut to the Instance Configuration instead.

Instances in BDeploy need to be configured, installed and activated. Once configured, the instance can be installed and activated either directly from the dashboard or by using the Instance History page.

Empty Instance Dashboard

Once the instance has been configured, installed and activated, the dashboard shows an overview of all available nodes, their respective state (CPU Usage, Load Average where available) and the Processes configured on them.

Instance Dashboard

Instance Configuration

The first step is to select the desired and required nodes used in the instance. The master node is enabled by default, the virtual Client Applications node is always present if client applications exist in the product. Additional nodes can be selected from the Instance Settings's Manage Nodes section.

Manage Nodes

Next up, you can assign processes to nodes by selecting applications from the node's Add Application…​ toolbar button.

Add Processes

The panel will display all applications along with their process templates if available. You can click the Add button to add a new, unconfigured process to the node. Using the Add template button, you can add a new process from a template, which typically includes a complete configuration of the selected application, see Application Templates for more information.

In any case, the process will appear in the selected node. You can use drag & drop to re-order processes within a node. This has currently mostly cosmetic impact, but can be important in a single scenario: when stopping processes, BDeploy will stop them in reverse order as configured on the node. It will stop one process after another, starting from the bottom of the list.

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

When changing configuration of processes, you will note a colored border next to new or modified processes, which indicate the current state the process is in. A newly added process receives a green border, a modified process receives a border in the current themes accent color, a process which has validation issues receives a border in the current themes warning color. Additionally, validation issues are displayed above any node.

Configuration Validation

Local Changes

BDeploy keeps track of any changes performed on any of the Instance Configuration pages panels. These changes can be viewed by pressing the Local Changes toolbar button.

Local Changes

You can Undo and Redo changes. Even dismissable messages (on product update) can be brought back by Undo and Redo. To view the current changes compared to the state you started from, use the Compare Local with Base button.

Local Changes

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 on the Process Setting panel. Click a process to access its settings panel.

Process Settings

From there, use the Configure Parameters…​ button to access the parameter configuration.

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, which can be expanded by clicking them.

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

Hovering the mouse over a parameter will show a small popup that contains a thorough description of the selected parameter. This also works in the command line preview section, as well as in any compare views throughout BDeploy.

Validation issues are displayed per group in the respective title and next to the affected parameter.

You can use the Search Bar to search for and filter parameters even though they are not shown as table. Groups will be hidden from the page unless a parameter matches - this includes optional (not yet configured) parameters.
Copy & Paste

You can copy a process configuration by accessing its process settings panel. Use the Copy to Clipboard button to copy the configuration to the clipboard. You can paste the configuration by accessing the Add Application…​ button of the desired node. Use the Paste button to paste the configuration from the clipboard.

Process Settings
You need to grant BDeploy access to the PCs Clipboard for the Paste button to appear in the node's application panel.
Optional Parameters

Optional parameters can be selected for each group using the Select Parameters…​ button present on the header of each parameter group.

Optional Parameters

Add an optional parameter by clicking the Add button in front of it. You can also remove an optional parameter by clicking the Remove button in front of it.

Custom Parameters

Custom parameters can be maintained in a dedicated parameter group which is always present. Because all parameters must have a determined sequence, custom parameters must define a predecessor parameter after which they are put on the command line. If no predecessor is defined, the parameter will end up first on the command line.

Click the Add button in the Custom Parameters group to add a new custom parameter.

Add 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 globe icon in the parameter configuration panel.

Conditional Parameters

Conditional parameters are parameters which are only configurable if a specific dependent parameter exists or 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 expanding the Command Line Preview section. 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 place. It can be opened by clicking on the Configuration Files button in the Instance Settings panel. The initial set of configuration files is derived from the default set delivered with the product, see product-info.yaml.

Instance Configuration Files

The configuration files of an Instance can be compared with the original configuration file templates of the Product at any time, an according up to date hint is shown next to each configuration file if applicable. The Compare with product template button starts the comparison. Files which are present in the product but not in the instance configuration are marked, same is true the other way round.

New configuration files can be be created using the + button. Prompt for a file name and an optional initial content to upload. When dropping a file onto the drop zone, the filename is updated automatically to match the dropped file.

The Edit button on each file can be used to edt the content of the file using an online rich editor.

Edit Instance Configuration Files

Online editing is only possible for text files. Binary files like ZIP, PDF, etc. can not be edited online. Instead, you can download and later on replace them.

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, much the same as any other change in the Instance Configuration.

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 Instance Configuration pages toolbar.

Update Notification

Clicking on the notification opens the product version sidebar. The same sidebar can also be opened opened by clicking on the Update Product Version button in the Instance Settings panel.

Change Current 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. Changing the product version will trigger an automated migration. This migration will also validate changes. It gives hints about potentially relevant (but not blocking) changes, and additionally validation issues in case the migration could not be performed fully automatically. You then have the chance to fix issues manually before saving the resulting instance version.

Product Update Hints
Changing the product version will never change the Configuration Files of the Instance. In case configuration file templates change from one product version to the other, an update hint will be shown. You can then manully update configuration files as needed, see chapter Configuration Files.

Banner Message

A banner message can be created for an Instance, which is displayed very clearly at the top of the overview dialog. You can choose from a series of predefined colors, so that depending on the urgency or content of the message a suitable color can be selected.

Instance Banner Configuration

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 and can be configured without saving the Instance Configuration.

Instance Banner Configuration

The banner is shown in the Instance Overview (as tooltip on the instance), in the Instance Dashboard and in the Instance Configuration pages.

Import/Export

Instance versions can be exported and downloaded from the Instance History. This will download this specific instance version’s raw data as a ZIP. The ZIP can be re-imported using the Instance Settings panel to create a new instance version which has that exported instances content.

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 when manipulating the ZIP files content manually.

Application Templates

A product may contain Application Templates. These are pre-defined configurations for applications, resulting in a more complete process configuration when added to the target node.

We saw earlier how to add applications using templates. Depending on the selected template, you may be prompted to enter the required template variable values.

Add Process Template

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.

Instance Templates

A product can define and include Instance Templates. These templates can be applied on an instance (e.g. after creating a new instance). They can define processes just like Application Templates, in fact they typically 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 Templates
Instance Templates can also be applied to instances which already have configured processes.

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 virtual Client Applications node. Selecting (skip) as target node will skip the processes in this group.

Instance Templates Node Assignment

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, you will receive an according message.

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

Next you will be presented with the template variables which need to be provided.

Instance Templates Variable Assignment

Clicking Confirm 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. Applying templates can be undone by clicking Undo like any other change.

Applied Instance Templates

Network Ports

The Manage Network Ports panel can be reached from the Instance Settings panel. This panel provides a concise overview of all ports (CLIENT_PORT, SERVER_PORT and URL parameters) used in the Instance.

The Shift Ports action allows to bulk edit selected 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.

A Deployment can be performed on the current instance version or on a historic instance version. All instance versions can be deployed using the Instance History page - select a version and use the according actions. For the most common case of deplying the current instance version, the deployment is performed by clicking the Install and Activate buttons on the Instance Dashboard after configuring an instance.

Installation

All available instance versions can be installed via the action Install on the Instance History page or the Instance Dashboard. 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.

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. The kind of pooling used can be configured in app-info.yaml by the product vendor.

Multiple instance versions can be installed simultanously. This allows very quick switching beteen them, for instance in case of a failed upgrade to immediately switch back to the previous software version.

Activation

Exactly 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 but not active cannot be started. Only processes from the active version can be started. The Instance Dashboard allows control of the active versions processes.

Marking a desired version as active does not require to stop all running processes. An outdated hint is displayed on the Instance Dashboard 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 active instance version, the process control of each Process can be displayed by clicking on it in the Instance Dashboard. The upper part of the Process Control panel shows the current status. Below this, the control elements for starting, stopping or restarting the process can be found.

Process Control Panel

In addition to the actions for individual processes, the Instance Dashboard offers bulk control actions from its toolbar, which allow to control all processes of start type INSTANCE at once.

Process Status

The process status is visualized using an icon for each process. Hover over the icon to get details about the current status.

Icon Description
ManualDoc ProcessStopped

Process is stopped.

ManualDoc ProcessRunning

Process is running.

ManualDoc ProcessStopPlanned

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

ManualDoc ProcessCrashed

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

ManualDoc ProcessCrashedPermanent

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 active. This happens when deploying a new version while Processes are still running.

Outdated Process

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 active 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. Additionally the start type of the Process must set to INSTANCE. This can be done in the parameter configuration of the Process.

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 but without waiting for any condition after launching the command. 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 only 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 Process state.

Crashed Server Process (temporarily)

The process control will give up restarting a process after a configurable number of unsuccessful restart attempts. Such a situation is visualized in Process state. 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

Process Port Status

The applications server ports (if any are defined) and their state on the target node can be viewed by clicking on the Process Port Status below the process controls. Each parameter of type SERVER_PORT is displayed here, with its description and configured value. Each port has a status. This status determines whether the port has the expected state on the server. This means that the port is closed if the process is not running, and vice versa. BDeploy cannot check whether the port was opened by the correct application.

Native Processes

Clicking on the Native Processes below the process control will open a panel showing all operating system processes that associated with this Process.

Data Files

The Data Files page lists all files that are stored in the data directory of each node. Files can be downloaded or opened directly in the the UI where possible. The table is by default sorted by the last modification timestamp. Thus the newest files displayed first.

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

Clicking a file will view the file, the Follow toggle allows to grab new output as it is written on the server.

View Data File

Data Files can also be manually added and edited online. Use the Add File button, and the Edit button per file to do so.

Edit Data File

Instance History

Whenever saving the Instance Configuration, BDeploy creates a new instance version. Each historic version is avilable from the Instance History. You can view all those changes, who made them and when they were made here.

There are three types of history entries: Creation, Deployment 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. You can enable them using the toolbar buttons.
If you haven’t made any changes, only one entry will be shown: Version 1: Created. This is the initial (empty) instance version.
Instance history

To see details for a certain history entry, click it. This will open the details panel. This panel offers different kinds of information and actions depending on the type of history entry.

Creation events are special in that they represent a specific instance version, and allow you to install, activate and compare them to other instance versions. Given the proper permissions, you can also delete them - which will remove this specific version completely from the server, no restoring possible.

Instance versions can also be exported from the details. The export produces a ZIP file which contains all data that represents an instance version. This can be used to create a new instance version on a different instance from the current configuration of this instance by importing the ZIP in the Instance Configuration of the other instance.

History Entry

You can compare either to the current version, the active version or any chosen version available from the history.

Compare Versions

Creation Events

Each change that leads to a new instance version is a creation event. This typically is saving the Instance Configuration.

Deployment Events

Deployment events are: INSTALLED,ACTIVATED,DEACTIVATED,UNINSTALLED.

Deployment events will show up once you enabled them using the toolbar. Deployment events allow tracking of who deployed what and when.

Runtime Events

Runtime Events

Runtime events are: STARTED, STOPPED, CRASHED, RESTARTED, CRASHED PERMANENTLY.

Runtime events will show up once you enabled them using the toolbar. Runtime events can be used to track process state history. You will be able to see who started/stopped processes and when. Events not induced by a user action are shown using BDeploy System as user, e.g. when a proces is restarted after a crash.

The Process ID and Exit Code will also show up given that the information was available at the moment the event happened. This can be influenced for instance by a restart of BDeploy itself, in which case limited information about running processes is available.
Runtime 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 desired Instance Group. Clicking on the Client Applications button in the main navigation menu opens the overview page.

Client Applications

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 updating the default grouping of the Client Applications page.

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 Shortcut that is stored on the Desktop or in the Start Menu.

Windows

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

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

When automating the installation it might be required to wait until the actual installation is finished. To do that using the PowerShell the Start-Process cmdlet can be used:

Start -FilePath "./Installer.exe" -ArgumentList "/Unattended" -Wait
For All Users

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

Installation for All users requires a terminal with elevated privileges (Run as Administrator). Just running the command as local administrator is not sufficient.

Start -FilePath "./Installer.exe" -ArgumentList "/ForAllUsers" -Verb RunAs
Start -FilePath "./Installer.exe" -ArgumentList "/Unattended","/ForAllUsers" -Wait -Verb RunAs
The Start cmdlet with the -Verb RunAs switch triggers a UAC prompt so that the installer is running with elevated privileges.
Additional configuration might be required depending on the installation location. See Multi-User Installations for more information.

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. Those commands are part of the launcher distributable.

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.

Application Browser

The Launcher (BDeploy.exe) can also be launched directly without any arguments. In this case a dialog is shown that lists all locally installed applications.

Client Application Browser

The Customize & Launch context menu entry allows the user to to modify the command line argumements that is used to start the application. A new dialog is opened that lists the existing command line arguments as currently defined by the active instance version.

Additional arguments can be added or existing ones can be modified or deleted as desired. This option is especially useful for testing. Arguments can be modified locally without the need to change the global Instance Configuration. The modified arguments are not saved and they need to be re-done the next time the application is launched.

Additional Command Line Arguments

When launching an application using a .bdeploy file then additional command line arguments can be defined which are passed to the target application.

./myApp.bdeploy -- "arg1=value1" "arg2=value2"

All arguments after the -- switch are passed to the launched application. They are added AFTER all existing arguments that are currently defined in the active instance version. Individual arguments need to be separated using a single space. Quotation marks are required when the argument or its value contains spaces.

A shortcut can be saved that includes the customized parameters. Doing that it is possible to save the customized arguments so that they do not need to be entered all the time. Executing the shortcut then launches the application with the customized arguments.

Multi-User Installations

Larger organizations typically do not want to deploy client applications on each client computer manually. 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 installation. 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. In this scenarion install has to be performed on the CENTRAL server.

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 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 Add Instance Group button, there is a Link 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 distiguish CENTRAL and MANAGED servers by the according banner in the expanded main menu in the Web UI.

On the CENTRAL server, choose Managed Servers on the main menu after selecting an Instance Group you want to attach. This will take you to the Managed Servers page for that Instance Group. Initially, this page will be empty.

Managed Servers Page on Central

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

Link Managed Server Panel

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 Link Instance Group button on the main Instance Group page (which is the initial start page of the Web UI). This will open the Link Instance Group panel.

Link Instance Group

The MANAGED server provides the card to drag to the counterpiece on the CENTRAL server. Drag it over to fill out information on the CENTRAL server automatically.

Alternatively, use the Manual and Offline Linking panel to download the information in an encrypted form. This can be uploaded on the CENTRAL by dropping the file on the very same drop-zone.

Once the information is dropped on the according drop zone on the CENTRAL server, it will fill out the information. Adapt the URL if required and fill in a human readable description of the MANAGED server. The URL should be reachable from the CENTRAL server and accomodate for any hostname mapping required (NAT, VPN, DNS, …​).

Filled out Link panel

Clicking Save 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, the panels close on both servers. The attached server appears on the CENTRAL, and the attached Instance Group appears on the MANAGED server. In case attaching is not possible automatically, you will be provided with the possibility to download synchronization information from the CENTRAL server. You can drop this in the Manual and Offline Linking panel on the MANAGED server to complete linking without actual contact to the server.

Servers which do not have an actual connection to each other, but are linked manually, will not be able to synchronize instance information. The link is purely informational, to hint that the server exists. More possibilities for synchronization may be added in the future.
Link Success (Central)

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 on the according server or directly from the Instance Overview and Instance Dashboard/Instance Configuration pages.

The Synchronize only exists on the CENTRAL server.
Instance Browser (Central)
Instance Dashboard (Central)
Instance Configuration (Central)
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 config --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 and configure an Instance using 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 from the CENTRAL server.

You can find the Product Synchronization panel on the Products page on the CENTRAL server inside a given Instance Group. The additional Synchronize Product Versions button is only available on the CENTRAL server.

Synchronize Product Versions

Clicking it will open the Product Synchronization panel. First you need to choose a direction of transfer. Either transfer products to or from the CENTRAL server. After selecting a direction, you will have to choose the MANAGED server to transfer from or to.

Choose Server

Clicking a server will fetch available products from that server. The list will contain product versions which are not yet present on the target server. Check all you want to transfer and click Transfer.

Choose Product Versions

The panel will initialize the transfer of the product version(s) in the background. You can keep track of transfers using the global activity report available from the main menu. Once a product version is transferred, it will appear in the list of available products on the target server.

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 Panel:

  1. Start from the Instance Group Overview page, which is the first page right after logging in.

  2. Click on the desired Instance Group.

  3. Click in the desired Instance.

  4. Click on the Instance Configuration button in the main menu.

  5. Click on the Process you wish to configure.

  6. Click on Configure Parameters…​ in the process edit panel.

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

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

  9. You can undo/redo changes to multiple processes and/or instance configurations. You can also view any local changes using the Local Changes button.

  10. Repeat the steps 5-8 with every Process that should be adopted.

  11. 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. Saving Instance Configuration will automatically redirect you to the Instance Dashboard. You can also access the dashboard from the Instance Overview page by clicking an Instance.

  2. If the current Instance Version is not the currently active one, a banner will show a hint and the required buttons to install and activate the current version.

    1. Access to older Instance Versions is provided from the Instance History button in the main menu.

  3. Click on install and wait for the operation to complete.

  4. Click on activate, this operation is typically very fast.

  5. A hint (OUTDATED) will be displayed if a Process is running in an older version, for instance the version which was active until moments ago.

  6. Stop the process you want to update by clicking on the Process. Click on the Stop button.

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

  8. Repeat the steps 5-6 with each process that should be running from the new, now active version.

  9. The hint (OUTDATED) disappears once all processes are running in the active version.

  10. It can be desirable and OK to not restart certain processes, and leave them in the OUTDATED state. This highly depends on the software being deployed.

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 in the Instance Dashboard.

  1. The individual process status is displayed with the according process - in the table row, or on the card, depending on the view mode.

  2. The indivifual process status is displayed in even more detail when clicking a process in the Process Details Panel.

  3. The overall Node state is displayed above the individual process list, and is also visible in collapsed mode. This overall status displayes whether the current state is the expected state for a running instance. More explicitly this means if there is a green checkmark, all processes of start type INSTANCE are running.

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 Products page of the Instance Group:

  1. Click on the desired Instance Group

  2. Click on Products button in the main menu.

  3. Click on the Upload Product button in the toolbar.

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

  5. The product is uploaded, processed and will appear in the list of available products once successfully imported.

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 Configuration dialog:

  1. Navigate back to the Instance Overview dialog by clicking the Instances button in the main menu.

  2. Open the desired Instance by clicking it.

  3. Each node displays the currently used product version. In case an update is available, a hint is shown in form of a small icon.

  4. Clicking on this hint opens the Instance Configuration page along with the Update Product panel.

    1. You can also navigate to the Instance Configuration page by clicking the Instance Configuration button in the main menu. This page shows a more prominent hint about the new Product Version.

  5. Click on the Update button of the desired product version

  6. The update to the new Product Version is performed and validated on the server. It is - however - not saved, so you can undo/redo, perform changes - just like with any other configuration change.

  7. Update hints may be shown in a separate section which can be dismissed. Those are purely informative things which point to actions performed during the update which may or may not have an impact on the software.

  8. Validation Issues may be shown in a separate section if they occur due to the update. This can be a wide variety of things - all of them require manual intervention before you are able to save the Instance Configuration.

  9. Adopt the configuration of the Processes as required

  10. 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 - clicking Save will bring you to the Instance Dashboard from where this can be performed directly.. 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.

In addition to arbitrary software, Software Repositories can also host Products, just like Instance Groups. The purpose of this feature is to provide a shared place which can be used to provide Products to multiple Instance Groups.

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.

An Application should not modify files in its own installation directory (although it can do it). BDeploy tries to aggressively pool applications per version to reduce the footprint on the disc. If this does not work for your application, use the pooling configuration to specify different behaviour.
runtimeDependencies of Applications are always considered GLOBAL poolable.
Client applications are always considered for GLOBAL pooling by the client launcher.

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)
pooling: GLOBAL (3)

supportedOperatingSystems: (4)
  - LINUX
  - WINDOWS

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

processControl: (6)
  gracePeriod: 3000
  supportedStartTypes:
   - INSTANCE
  supportsKeepAlive: true
  noOfRetries: 5

startCommand: (7)
  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: (8)
        parameter: "my.param.2"
        must: EQUAL
        value: "Value 1"

stopCommand: (9)
  ...

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

runtimeDependencies: (13)
  - "adoptium/jre:1.8.0_202-b08"
1 A human readable name of the Application. Will be displayed in the Configure Application pane, and is also used as default name for any process instantiated from this Application.
2 The type of the application, may be SERVER or CLIENT. SERVER applications can be deployed to Nodes (including the master) and there be started as server processes. CLIENT applications in comparison cannot be deployed on a Node, but run on a client PC instead.
3 The supported pooling type for server applications. Supported values are GLOBAL, LOCAL and NONE. GLOBAL means that the application is fully poolable and may be installed once (per application version) and used by multiple instance versions of multiple instances. LOCAL means that there is limited pooling support, and the application may only be re-used inside a single instance (by multiple instance versions of that instance, e.g. when changin only configuration). NONE means that there is no pooling support and the application will be installed fresh per instance version, even if just configuration values changed. This gives some control on how to deploy applications which write data into their installation directory at runtime - which should be avoided of course for better pool-ability. This setting is currently ignored by the client application launcher. Client applications are always globally pooled.
4 List of supported operating systems. This list is solely used to verify during import of the Product, that the Application actually supports the operating system under which it is listed in the product-version.yaml.
5 Only relevant for CLIENT applications: The branding attribute controls the appearance of CLIENT type Applications when downloaded by the user. It can be used to specify an icon (used to decorate desktop links created by the client installer), and a splash screen. For the splash, you can fine tune the exact location used to display progress text and a progress bar while the application is downloaded to the client PC by the Launcher CLI. Paths are interpreted relative to the root folder of the Application.
6 Only relevant for SERVER applications: Process control parameters allow to fine tune how SERVER type Applications are started and kept alive by BDeploy. For details, see the list of processControl attributes.
7 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.
8 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.
9 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.
10 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.
11 The ID of the endpoint can be used to call the endpoint remotely by tunneling through potentially multiple levels of BDeploy servers.
12 Variable Expansion can be used on most of the endpoint properties.
13 Optional runtime dependencies. These dependencies are included in the Product when building it. Dependencies are fetched from Software Repositories. launcherPath and parameter defaultValue (and of course the final configuration values) can access paths within each of the dependencies by using the {{M:adoptium/jre}} Variable Expansion, e.g. launcherPath: {{M:adoptium/jre}}/bin/java. Note that the declared dependency does not need to specify an operating system, but must specify a version. This will be resolved by BDeploy to either an exact match if available, or a operating system specific match, e.g. adoptium/jre/linux:1.8.0_202-b08 on LINUX. When referencing the dependency in a Variable Expansion, neither an operating system nor a version is required - in fact it must not be specified.
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('yyyyMMddHHmmss')
  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('instanceGroup')
      }
    }
  }
}

...
1 Applies the plugin BDeploy gradle plugin.
2 Sets the project version. Gradle does not strictly require a version, and uses 'unspecified' as default. BDeploy requires some sort of version, and setting it for the whole project is good practice.
3 Calculate a build date, which will be substituted instead of the SNAPSHOT in the version. This is optional, you could just 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-info.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 specified in app-info.yaml. If required (usually it is not) you can configure a different set of Operating Systems to build for in the test application configuration in build.gradle by adding a set of operating system literals (e.g. 'WINDOWS', 'LINUX') to the os list of the application.
2 This demo app-info.yaml only defines the path to the launcher, which for this demo project (named test) is bin/test on LINUX, and bin/test.bat on WINDOWS.

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

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. You can get a token by using the Create Token…​ action on the user menu in BDeploy. Make sure to create a full token pack for this tool to work.
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:adoptium/jre8}}

Expands to the absolute path where the the manifest named 'adoptium/jre8' is installed on the server. The exact version is specified through a runtime dependency in the app-info.yaml.

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

Alternatively the Web UI provides a mechanism to upload arbitrary software to Software Repositories.

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

Software Repositories are a storage location for any external software required by products. In addition, BDeploy products can be stored and managed in Software Repositories, from where they can be transferred (imported) to Instance Groups. 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 Software button in the toolbar. Then click on browse or drop files. You can upload zip packages.

After uploading arbitraty content, you need to specify the name of the software, the version and the supported operating systems. If you already have a package in a BHive format or a package including a product descriptor containing all of this metadata, the available information will be used automatically.

External Software Upload

After all requested information is entered, click Import to finally import the files to the Software Repository.

External Software Import

If the upload was succesful, the software for each operating system will show up.

The available software packages and products 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 (exception: CLIENT permission users). WRITE permissions are required to manage the software packages in the repository. To be able to upload software, a user therefore requires ADMIN or WRITE permissions either globally, or assigned in the Software Repository Permissions panel.

Software Repository Permissions

The Software Repository Permissions panel works very similar to the Instance Group Permissions.

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.

The administration dialogs are grouped into a Configuration section and a Housekeeping and Maintenance section.

Settings

In the Settings area some global settings can be made.

General
BDeploy Settings

Gravatar support can be enabled here. If disabled, a generic icon is used for all useres. Otherwise, BDeploy shows the Globally Recognized Avatar (or a substitute image) wherever a user icon is displayed in a dialog. Visit gravatar.com for more information.

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

At least one login method must be configured. Disable local accounts only if it is ensured that at least one administrator account exists via external authentication!
LDAP Auth.

On the LDAP Auth tab, you can configure a list of LDAP servers which are queried when authenticating a user. Use drag and drop to to specify the sort order in which the LDAP servers are queried for users that log on.

BDeploy LDAP Servers
Technical experts can use the Check action to test a single LDAP server entry: BDeploy tries to establish a connection to the configured server. Some logging information, esp. Java Exceptions are shown in a popup window. Simmilarly, the Test Auth. action can be used to trace the entire authentication of a user.

BDeploy uses simple bind to authenticate users. First, a simple bind is made with the configured 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 Account User Field matches the user name to be authenticated. 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 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).

Description

Free text to describe the entry

User

The user which is used to query other users on the LDAP server (aka bind user)

Password

The password for the 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 Account User Field for the given user. This means that a pattern (field1=value1)(field2=value2) will result in a query like (&(field1=value1)(field2=value2)(sAMAccountName=<GIVEN USER>)).

Account User Field

Specifies the field which must match the login name when querying for the user.

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

Account 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].

Follow Referrals

Specifies whether the authentication process should follow referrals or not.

Global Attributes

In the Global Attributes tab, globally available attributes for Instance Groups can be maintained. Global attributes can be used to maintain additional information for Instance Groups, which is then used as an additional grouping or sorting criteria.

BDeploy Global Attributes
Plugins

The Plugins tab can be used to manage the plugins known by BDeploy. Plugins that are currently loaded can be stopped here. Via the Upload Plugin action global plugins can be uploaded. Global plugins can also be deleted from the system here.

BDeploy Plugins Maintenance

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 Create User button to create a local user.

BDeploy User Accounts

Once a User is available, you can click it to open User Details panel where detail information is shown on top as well as the list of permissions.

To protect against accidental lockout from the system, the currently logged in user cannot be changed, disabled or deleted.

The Deactivate Account resp. Activate Account allows to deactivate/activate the selected user.

BDeploy User Accounts

The Assign Permission opens a popup for adding a permission entry. Global permissions as well as scoped permissions on Instance Groups can be maintained here.

BDeploy User Accounts
Permission Meaning

CLIENT

The CLIENT permission can be granted to allow access only to the client applications of Instance Groups. Users with global CLIENT permission can see the client applications of all Instance Groups.

READ

Only those Instance Groups for which a user has READ permission are displayed. Users with global READ permission can see all Instance Groups. The READ permission contains the CLIENT permission. The 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 Edit User opens a popup for editing the main user properties and also for changing the password.

BDeploy User Accounts

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.

All Nodes

Delete Manifests that are not known by the master

All Nodes

Keep two BDeploy Launcher versions, delete all older versions.

All Nodes

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 button to perform cleanup calculation. The result will be actions to be performed on Instance Groups or Nodes (including the Master). If no action is calculated at all, a corresponding message is displayed.

BDeploy Cleanup Actions

Press the Perform button to actually perform the calculated actions. The button Abort Cleanup resets the dialog without further 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 BHive page from the Administration menu is an internal tool for administrative purposes. It allows access to the internals of the BDeploy storage.

The table shows all 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.

Clicking a BHive opens the panel with maintenance actions

The details tab allows access to the Audit Logs and the content that is stored in a BHive. It also gives access to the repair and prune operations (see CLI) from the web interface.

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.

Logging

The logging page allows to view and download 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.

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

BDeploy System Software

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

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

init

Initializes a root directory for running a server with the start command. The init command can be instructed to initialize the directory to run a master or a headless node when running the start command.

config

Allows changes to the basic configuration like hostname, port or mode. 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, this tool can update it. Please refer to Migrating between Modes in case you need to change the minion mode.

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.

node

Manage nodes in attached to the master configuration in the given root directory. The given root must be an initialized (init) root directory using a master mode.

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

start

Runs the BDeploy minion in the mode determined by the given root directory. Requires a root directory initialized with the init command.

A master is always a node as well. The master just has the additional capability to control other nodes, and provides the configuration Web UI.
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 node), 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. hostname:7701/api.

BDEPLOY_ROOT

The root directory to use for init and start (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 node 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 node in the system. As long as this node 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 information 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/#/instances/dashboard/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 dashboard, click the server application you want to tunnel to. The process control panel for that application opens up, and you will see the applications ` Process ID` displayed.

Last thing to manually lookup is the endpoint id. Endpoints can be accessed on the instance configuration page by clicking on to application you want to tunnel to and then clicking on Configure Endpoints

Application Edit Panel

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.

Application 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 second API. The returned JSON will include the application uuid hosting the endpoint along with the actual specific configuration of that endpoint (including its id).