Getting started

The BCD add-on is provided as a bonita-continuous-delivery_3.6.2.zip archive.

This page describes how to use this archive to start your journey with Bonita Continuous Delivery.

Installation guide

In order to ease your environment setup, we provide a Docker image called BCD Controller image which contains all required dependencies and tools for BCD.
Then a BCD Controller container has to be started on the control host, ie. the host from which Bonita Continuous Delivery commands are launched.

Common installation steps

Follow these installation steps on your control host.

Make sure Docker is installed as described in the Install Docker documentation.
Extract the bonita-continuous-delivery_3.6.2.zip archive:
```
$ unzip bonita-continuous-delivery_3.6.2.zip
```
This step creates a bonita-continuous-delivery_3.6.2 directory which contains Bonita Continuous Delivery Ansible playbooks and roles.

For windows users install in user folder (C:\Users\XXX) (If not, Docker won’t have the right to copy the volumes)
Pull the quay.io/bonitasoft/bcd-controller:3.6.2 Docker image from secured registry.
The username and the password should have been provided by your sales representative.
```
$ docker login quay.io
Username: bonitasoft+john_doe_at_acme_com
Password:
Login Succeeded
$ docker pull quay.io/bonitasoft/bcd-controller:3.6.2
[...]
Status: Downloaded newer image for quay.io/bonitasoft/bcd-controller:3.6.2
$ docker logout quay.io
```
The quay.io/bonitasoft/bcd-controller:3.6.2 Docker image is now available on the control host.
Make sure BCD dependencies are present.
BCD expects Bonita version-specific dependencies to be present in the bonita-continuous-delivery_3.6.2/dependencies directory. BCD dependencies are provided separately as a quay.io/bonitasoft/bcd-dependencies:<bonita_version> Docker data image.
Basically, the /dependencies volume provided by the quay.io/bonitasoft/bcd-dependencies Docker image must be mounted or copied into the dependencies directory. For instance, here is how to create a Docker named volume with BCD dependencies from the data image:
```
$ docker login quay.io
Username: bonitasoft+john_doe_at_acme_com
Password:
Login Succeeded
$ docker run --rm -v bcd-dependencies-<bonita_version>:/dependencies quay.io/bonitasoft/bcd-dependencies:<bonita_version>
$ docker logout quay.io
```
For linux user make sure your user id and group id is 1000 or refer to the Running BCD controller with user ID different from 1000 paragraph in BCD Controller image

The bcd-dependencies-<bonita_version> Docker named volume is now available and can be mounted with your BCD Controller.

Start a BCD Controller Docker container on the control host:

$ docker run --rm -ti --hostname bcd-controller --name bcd-controller \
    -v <host_path_to_bonita-continuous-delivery_directory>:/home/bonita/bonita-continuous-delivery \
    -v bcd-dependencies-<bonita_version>:/home/bonita/bonita-continuous-delivery/dependencies/<bonita_version> \
    quay.io/bonitasoft/bcd-controller:3.6.2 /bin/bash

This command bind mounts the bonita-continuous-delivery directory and the bcd-dependencies-<bonita_version> volume on the control host into the BCD controller container.

You may also start a BCD Controller container using Docker Compose as described in the BCD Controller image detailed documentation.

Complete installation example

Here is a complete example of how to install the BCD Controller Docker image.

Assuming you have a bonita-continuous-delivery_3.6.2.zip archive in your $HOME directory:

$ cd $HOME
$ unzip bonita-continuous-delivery_3.6.2.zip
[...]

$ docker login quay.io
Username: bonitasoft+john_doe_at_acme_com
Password:
Login Succeeded
$ docker pull quay.io/bonitasoft/bcd-controller:3.6.2
[...]
Status: Downloaded newer image for quay.io/bonitasoft/bcd-controller:3.6.2

$ cd $HOME/bonita-continuous-delivery_3.6.2/dependencies

$ docker run --rm -v bcd-dependencies-7.12.2:/dependencies quay.io/bonitasoft/bcd-dependencies:7.12.2
[...]

$ docker logout quay.io

Finally, here is a sample command to start a BCD controller container:

$ docker run --rm -ti --hostname bcd-controller --name bcd-controller \
        -v ~/bonita-continuous-delivery_3.6.0:/home/bonita/bonita-continuous-delivery \
        -v bcd-dependencies-7.14.0:/home/bonita/bonita-continuous-delivery/dependencies/7.14.0 \
        bonitasoft/bcd-controller:3.6.2 /bin/bash
bonita@bcd-controller:~$
bonita@bcd-controller:~$ cd bonita-continuous-delivery
bonita@bcd-controller:~/bonita-continuous-delivery$

Using Bonita Continuous Delivery add-on

At this stage of the Getting started guide, you should have a BCD controller container up and running.

Command Line Interface

From your BCD controller container, you can now run the bcd command to manage your Bonita Living Applications.

You can call bcd with the --help option to get available options and commands as follows:

bonita@bcd-controller:~/bonita-continuous-delivery$ bcd --help
Usage: bcd [OPTIONS] COMMAND [ARGS]...

  Bonita Continuous Delivery CLI.

Options:
  -v, --verbose          Enable Ansible verbose mode
  -y, --yes              Execute action without confirmation prompt
  --nocolor              Turn output colorization off
  -s, --scenario PATH    YAML scenario file path - Optional if `BCD_SCENARIO`
                         environment variable is defined.
  -e, --extra-vars TEXT  Extra vars for Ansible (multiple) - Variables are
                         passed using the key=value syntax.
  -h, --help             Show this help message
  --version              Show the version and exit.

Commands:
  livingapp  Manage Bonita Living Application
  version    Show BCD version information

Read the BCD Command-line interface page for further information about the BCD CLI usage.

Scenarios

BCD requires a YAML configuration file called Scenario which describes the Bonita parameters to build and deploy your living apps.

Example scenario files are provided in the scenarios directory, including:

build_and_deploy.yml.EXAMPLE - a scenario for living applications management

Use this example to customize your scenario and save it with a .yml file extension.

Read the BCD Scenario reference page for a comprehensive description of scenario variables.