Commit 2ffb929d authored by Truc Nguyen's avatar Truc Nguyen Committed by JeremJR

tr(structure): rework doc structure for release 2.0 (#41)

* tr(structure): rework doc structure for release 2.0
* feat(tutorials): add tutorial to build livingapp (livingapp_build.md)
parent d4af8277
# AWS prerequisites
This tutorial describes how to configure Amazon Web Services (AWS) for BCD.
These configuration steps are required to allow BCD to programmatically manage your AWS instances and to be able to connect to your Bonita stack.
## Sign Up for AWS
If you do not have an Amazon Web Services (AWS) account yet, first sign up as described in this AWS user guide: [Sign Up for AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#sign-up-for-aws).
If you do not have an Amazon Web Services account yet, first sign up as described in this AWS user guide: [Sign Up for AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#sign-up-for-aws).
## AWS Setup for BCD
In order to use Amazon EC2 instances, some configuration steps need to be performed as a prerequisite.
The following steps are the basic requirements to set up AWS credentials for Ansible automation.
Further configuration instructions for **AWS SIngle Sign-On** can be found [on this page](aws_sso.md).
Further configuration instructions for **AWS single sign-on** can be found [on this page](aws_sso.md).
1. [Create an IAM Policy](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) to grant full access to Amazon EC2 on a specific region (eg. us-west-2)
- **Policy name**: EC2FullAccess_us-west-2
......@@ -109,7 +113,9 @@ Further configuration instructions for **AWS SIngle Sign-On** can be found [on t
]
}
```
Pay attention that for security reasons, pushing AWS user credentials to EC2 instances, as done with BCD 1.0.x, are no longer supported.
::: warning
:fa-exclamation-triangle: Pay attention that for security reasons, pushing AWS user credentials to EC2 instances (as done with BCD 1.0.x) is no longer supported.
:::
1. [Create an IAM Role for an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)
- Select EC2 to "Allows EC2 instances to call AWS services on your behalf."
- Select the IAM Policy created previously (ClusterBCD_us-west-2)
......@@ -138,7 +144,7 @@ Therefore a [default VPC and default subnets](http://docs.aws.amazon.com/AmazonV
- Download the `.pem` private key file
- Ensure private key file permissions: `$ chmod 400 <keyfile_basename>.pem`
Bonita Provisioning solution uses official Ubuntu cloud images as EC2 AMI (Amazon Machine Images).
BCD is compatible with official Ubuntu cloud images as EC2 AMI (Amazon Machine Images).
Use the [Amazon EC2 AMI Locator](https://cloud-images.ubuntu.com/locator/ec2/) tools to identify IDs of such images.
......
# AWS Single Sign-On
# AWS single sign-on
AWS allows to integrate [numerous Third-Party SAML Solution Providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml_3rd-party.html).
AWS allows to integrate [numerous Third-Party SAML Solution Providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml_3rd-party.html) to implement single sign-on.
If you implement this kind of authentication, when you start the BCD Controller container it will no longer be necessary to mount the `boto` file.
......@@ -13,7 +13,8 @@ $ docker run --rm -t -i --name bcd-controller \
Indeed you will use `~/.aws` directory instead.
## Single Sign-On to AWS Using G Suite
Single Sign-On to AWS Using G Suite <!--{.h2}-->
In this step we will provide you an example using G Suite from Google.
......@@ -23,7 +24,7 @@ The BCD Controller already embeds [aws-google-auth](https://github.com/cevoaustr
You will need to know Google's assigned Identity Provider ID (idp-id) and the ID assigned to the SAML service provider (sp-id).
`idp-id` can be found on Google Admin `Security > Set up single sign-on (SSO)` page in the SSO url provided. For instance: `https://accounts.google.com/o/saml2/idp?idpid=123456789012`
`sp-id` can be found into the URL of your browser when viewing Google Admin `Apps > SAML Apps > Amazon Web Services` page. For instance: `#AppDetails:service=123456789012`
`sp-id` can be found into the URL of your browser when viewing Google Admin `Apps > SAML Apps > Amazon Web Services` page. For instance: `#AppDetails:service=123456789012`
After launching the BCD Controller you will have to authenticate yourself as below:
```
......
# BCD command-line interface
On this page you will find detailed information about the BCD CLI with usage examples and reference.
## Requirements
* First, the `bcd` command requires that the **`BCD_HOME`** environment variable is set.
By default `BCD_HOME` is set to `/home/bonita/bonita-continuous-delivery` in the controller container.
* Next, the `bcd` command takes a mandatory option called `scenario` through the `-s / --scenario` command line option.
This option expects an existing relative or absolute path to a [BCD YAML scenario](scenarios.md) file.
The BCD scenario path can also be specified through the **`BCD_SCENARIO`** environment variable, hence allowing to skip the `-s / --scenario` command line option.
* Finally, the BCD CLI expects to find Bonita version-specific dependencies in the **`$BCD_HOME/dependencies`** directory. This directory must contain:
- `bonita-subscription_*.tar.gz` - (Mandatory) The Bonita Docker image archive
- `bonita-la-builder-*-exec.jar` - (Mandatory) The Bonita Living Application Builder library
- `bonita-sp-*-maven-repository.zip` - (Optional) The Bonita Maven repository zip if required by your Living Application workspace.
## Usage examples
Running the `create` subcommand of the `stack` command with scenario command-line option:
```
$ bcd -s scenarios/uswest2_cluster.yml stack create
```
Running the `deploy` subcommand of the `stack` command with scenario command-line option and overridden `mail_notification` variable:
```
$ bcd -s scenarios/vagrant_single.yml -e mail_notification=no -y stack deploy
```
Running the `destroy` subcommand of the `stack` command with `BCD_SCENARIO` environment variable and subcommand `--dry-run` option:
```
$ export BCD_SCENARIO=scenarios/uswest2_performance.yml
$ bcd stack destroy --dry-run
```
Running the `build` subcommand of the `livingapp` command with `BCD_SCENARIO` environment variable and subcommand `-p` and `-e` options:
```
$ export BCD_SCENARIO=scenarios/euwest1_performance.yml
$ bcd livingapp build -p path/to/livingapp-repo -e Qualification
```
## Multi command chaining
The BCD CLI allows to invoke more than one command in one go. This is useful to chain commands as a pipeline.
If one command fails then `bcd` stops executing any subsequent command it may have.
**Examples**:
Running `create` then `deploy` subcommands of the `stack` command:
```
$ bcd -s scenarios/uswest2_cluster.yml -y stack create deploy
```
Running `build` then `deploy` subcommands of the `livingapp` command:
```
$ bcd -s scenarios/vagrant_single.yml --yes \
livingapp build -p path/to/livingapp-repo -e Qualification deploy
```
## Command-line reference
This section describes the comprehensive usage information for the `bcd` command.
You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND] --help` - where SUBCOMMAND is in `[livingapp, stack]` - from the command line.
<div class="section" id="bcd">
<span class="h2">bcd</span>
<p>Bonita Continuous Delivery CLI.</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND <span class="o">[</span>ARGS<span class="o">]</span>...
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-v">
<code class="descname">-v</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--verbose</code><code class="descclassname"></code></dt>
<dd><p>Enable Ansible verbose mode</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-y">
<code class="descname">-y</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--yes</code><code class="descclassname"></code></dt>
<dd><p>Execute action without confirmation prompt</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-nocolor">
<code class="descname">--nocolor</code><code class="descclassname"></code></dt>
<dd><p>Turn output colorization off</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-s">
<code class="descname">-s</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--scenario</code><code class="descclassname"> &lt;scenario&gt;</code></dt>
<dd><p>YAML scenario file path - Optional if <cite>BCD_SCENARIO</cite> environment variable is defined.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-e">
<code class="descname">-e</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--extra-vars</code><code class="descclassname"> &lt;extra_vars&gt;</code></dt>
<dd><p>Extra vars for Ansible (multiple) - Variables are passed using the key=value syntax.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
<div class="section" id="bcd-livingapp">
<span class="h3">livingapp</span>
<p>Manage Bonita Living Application</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND1 <span class="o">[</span>ARGS<span class="o">]</span>... <span class="o">[</span>COMMAND2 <span class="o">[</span>ARGS<span class="o">]</span>...<span class="o">]</span>...
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
<div class="section" id="bcd-livingapp-build">
<span class="h4">build</span>
<p>Build Bonita Living Application</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp build <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-build-p">
<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--path</code><code class="descclassname"> &lt;path&gt;</code></dt>
<dd><p>Bonita Living Application workspace path</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-build-e">
<code class="descname">-e</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--environment</code><code class="descclassname"> &lt;environment&gt;</code></dt>
<dd><p>Name of the process configuration environment as defined in Bonita Studio</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-build-x">
<code class="descname">-X</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug</code><code class="descclassname"></code></dt>
<dd><p>Enable debug mode</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-build-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
<div class="section" id="bcd-livingapp-deploy">
<span class="h4">deploy</span>
<p>Deploy Bonita Living Application</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp deploy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-deploy-p">
<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--path</code><code class="descclassname"> &lt;path&gt;</code></dt>
<dd><p>Bonita Living Application file path</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-deploy-x">
<code class="descname">-X</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug</code><code class="descclassname"></code></dt>
<dd><p>Enable debug mode</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-deploy-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
</div>
<div class="section" id="bcd-stack">
<span class="h3">stack</span>
<p>Manage Bonita stack (infrastructure)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND1 <span class="o">[</span>ARGS<span class="o">]</span>... <span class="o">[</span>COMMAND2 <span class="o">[</span>ARGS<span class="o">]</span>...<span class="o">]</span>...
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-stack-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
<div class="section" id="bcd-stack-create">
<span class="h4">create</span>
<p>Create AWS instances</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack create <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-stack-create-d">
<code class="descname">-d</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dry-run</code><code class="descclassname"></code></dt>
<dd><p>Show an execution plan only</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-stack-create-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
<div class="section" id="bcd-stack-deploy">
<span class="h4">deploy</span>
<p>Deploy Bonita stack (creates Docker containers)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack deploy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-stack-deploy-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
<div class="section" id="bcd-stack-destroy">
<span class="h4">destroy</span>
<p>Destroy AWS machines (EC2 instances)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack destroy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-stack-destroy-d">
<code class="descname">-d</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dry-run</code><code class="descclassname"></code></dt>
<dd><p>Show an execution plan only</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-stack-destroy-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
<div class="section" id="bcd-stack-status">
<span class="h4">status</span>
<p>Show the platform status</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack status <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-stack-status-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
<div class="section" id="bcd-stack-undeploy">
<span class="h4">undeploy</span>
<p>Undeploy Bonita stack (removes Docker containers)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack undeploy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-stack-undeploy-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
</div>
</div>
# BCD controller Docker image
The BCD controller image provides a ready-to-use environment to launch Bonita Continuous Delivery CLI and Ansible playbooks.
## Installation
A pre-built BCD controller image is provided with BCD deliverable as a `bcd-controller_<version>.tar.gz` archive. It is located in the `bonita-continuous-delivery_<version>/docker` directory.
Load this image into Docker engine as follows:
```
$ cd bonita-continuous-delivery_<version>/docker
$ gunzip -c bcd-controller_<version>.tar.gz | docker load
Loaded image: bonitasoft/bcd-controller:<version>
Loaded image: bonitasoft/bcd-controller:latest
```
## Usage
To enter the BCD controller environment, a Docker container has to be started on your control workstation using the BCD controller image.
Besides the following files have to be bind mounted from the control workstation to make them available to the BCD controller container:
- (Mandatory) **`/local/path/to/bonita-continuous-delivery_<version>`** (mounted as `/home/bonita/bonita-continuous-delivery`) - This directory provides BCD Ansible playbooks and is known as the `BCD_HOME` directory.
- (Mandatory) **`ssh_private_key`** (mounted as `/home/bonita/.ssh/ssh_private_key`) - The `ssh_private_key` file is the SSH private key used to connect to your target machines. For AWS, this is the private part of your [EC2 key pair](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html). This file should only be accessible from your user (`chmod 600 ~/.ssh/ssh_private_key`).
- (Optional) **`.boto`** (mounted as `/home/bonita/.boto`) - The [`.boto`](https://boto.readthedocs.io/en/latest/boto_config_tut.html) file contains AWS credentials used to make programmatic calls to AWS. Indeed dynamic Amazon EC2 inventory management for Ansible runs on top of [Boto](https://aws.amazon.com/sdk-for-python/). The content of a `.boto` file is as follows:
```ini
[Credentials]
aws_access_key_id = <YOUR_AWS_ACCESS_KEY>
aws_secret_access_key = <YOUR_AWS_SECRET_ACCESS_KEY>
```
::: info
However AWS credentials can be provided in other ways, for instance with [AWS single sign-on](aws_sso.md).
:::
Once the required files are prepared, the BCD controller container can be started in different ways described hereafter.
### Starting a BCD controller with `docker run`
The first method to start a BCD Controller Docker container on the control workstation is to use the `docker run` command.
**Example**:
```
$ docker run --rm -t -i --name bcd-controller \
-v <local_path_to_.boto>:/home/bonita/.boto \
-v <local_path_to_bonita-continuous-delivery_folder>:/home/bonita/bonita-continuous-delivery \
-v <local_path_to_ssh_private_key>:/home/bonita/.ssh/<ssh_private_key> \
bonitasoft/bcd-controller /bin/bash
```
### Starting a BCD controller with `docker-compose run`
The BCD controller container can also be created and started using [Docker Compose](https://docs.docker.com/compose/). This method enables to configure bind mount volumes in a `docker-compose.yml` file instead of through command-line options.
**Example:**
Here is a `docker-compose.yml` file example that you can create in your `BCD_HOME` directory.
```yaml
version: "3.2"
services:
bcd:
image: bonitasoft/bcd-controller
hostname: bcd-controller
stdin_open: true
tty: true
command: /bin/bash
volumes:
- .:/home/bonita/bonita-continuous-delivery
- <local_path_to_.boto>:/home/bonita/.boto
- <local_path_to_ssh_private_key>:/home/bonita/.ssh/<ssh_private_key>
```
Then start the BCD controller container interactively with:
```
$ docker-compose run --rm bcd
```
# Bonita Continuous Delivery CLI
This is a command-line tool for Bonita Continuous Delivery.
## Install
The CLI is provided as a Python package. Install the package locally as follows:
```
$ cd cli
$ pip install --user .
```
This will make the `bcd` command available under `$HOME/.local/bin`.
Basically make sure to add `$HOME/.local/bin` to your `PATH` environment variable in order to make your environment aware of the `bcd` command.
## Usage
The `bcd` command takes a mandatory option called `scenario` through the `-s / --scenario` command line option.
Then the `bcd` command provides the following subcommands in order to drive Bonita Continuous Delivery module:
```
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
-e, --extra-vars TEXT Extra vars for Ansible (multiple) - Variables are
passed using the key=value syntax.
-h, --help Show this help message
Commands:
livingapp Manage Bonita Living Application
stack Manage Bonita stack (infrastructure)
```
### Examples
```
$ bcd -s scenarios/uswest2_cluster.yml stack create
$ bcd -s scenarios/vagrant_single.yml -e mail_notification=no -y stack deploy
$ bcd -s scenarios/uswest2_performance.yml stack destroy --dry-run
```
### Multi command chaining
The BCD CLI allows to invoke more than one command in one go. This is useful to chain commands as a pipeline. If one command fails then `bcd` stops executing any subsequent command it may have.
For example:
```
$ bcd -s scenarios/uswest2_cluster.yml -y stack create deploy
```
......@@ -53,7 +53,7 @@ Hence the Bonita Docker image startup sequence can be described as follows:
::: info
**Warning**: all custom scripts are re-executed each time the Bonita Docker container is restarted.
If you want your script to be executed only once, you need to handle the conditional execution in your custom script itself.
If you want your script to be executed only once, you need to handle the conditional execution in your custom script itself.
For example:
```bash
#!/bin/bash
......@@ -82,12 +82,12 @@ More precisely scripts are executed in the order returned by this command: `ls -
### 1. config-workers.sh
The `config-workers.sh` script is provided as part of BCD's core scripts.
The `config-workers.sh` script is provided as part of BCD's core scripts.
In particular it shows how to further configure the server using [Bonita Platform setup tool](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/BonitaBPM_platform_setup).
### 2. config-cluster.sh.j2
The `config-cluster.sh.j2` script template is provided as part of BCD's core scripts.
The `config-cluster.sh.j2` script template is provided as part of BCD's core scripts.
In particular it shows how to conditionally configure a cluster deployment on AWS using BCD variables and [Jinja2 templating engine](http://docs.ansible.com/ansible/latest/playbooks_templating.html).
### 3. register-event-handler.sh
......@@ -96,8 +96,8 @@ This sample script deploys and registers a Bonita engine Event handler as descri
Assuming the following files:
- `roles/bonita/files/custom-init.d/event-handler-example-1.0.0-SNAPSHOT.jar` (event handler JAR file)
- `roles/bonita/files/custom-init.d/bonita-tenant-sp-custom.xml` (tenant configuration file where the event handler is registered)
* `roles/bonita/files/custom-init.d/event-handler-example-1.0.0-SNAPSHOT.jar` (event handler JAR file)
* `roles/bonita/files/custom-init.d/bonita-tenant-sp-custom.xml` (tenant configuration file where the event handler is registered)
Here's a sample `register-event-handler.sh` script:
......@@ -191,7 +191,7 @@ touch ${indicator_path}
```
#### tomcat-users.xml.j2
#### tomcat-users.xml.j2
```xml
<?xml version="1.0" encoding="UTF-8"?>
......
# BCD controller Docker image
This Docker image provides a ready-to-use environment to launch Bonita Continuous Delivery CLI and Ansible playbooks.
## Install the image
A pre-built BCD controller image is provided with BCD deliverable as a `bcd-controller_<version>.tar.gz` archive. It is located in the `bonita-continuous-delivery_<version>/docker` directory.
Load this image into Docker engine as follows:
```
$ cd bonita-continuous-delivery_<version>/docker
$ gunzip -c bcd-controller_<version>.tar.gz | docker load
Loaded image: bonitasoft/bcd-controller:<version>
Loaded image: bonitasoft/bcd-controller:latest
```
## Use the image
### Configure AWS credentials
Dynamic Amazon EC2 inventory management for Ansible runs on top of [Boto](https://aws.amazon.com/sdk-for-python/).
Boto's configuration requires the following `.boto` file to exist in the Docker container's `/home/bonita` directory.
```
[Credentials]
aws_access_key_id = <YOUR_AWS_ACCESS_KEY>
aws_secret_access_key = <YOUR_AWS_SECRET_ACCESS_KEY>
```
### Start a container
```
$ docker run --rm -t -i --name bcd-controller \
-v <local_path_to_.boto>:/home/bonita/.boto \
-v <local_path_to_bonita-continuous-delivery_folder>:/home/bonita/bonita-continuous-delivery \
-v <local_path_to_ssh_private_key>:/home/bonita/.ssh/<ssh_private_key> \
bonitasoft/bcd-controller /bin/bash
$ cd /home/bonita/bonita-continuous-delivery
```
# How to configure REST API authorization
The Bonita container is launched with REST_API_DYN_AUTH_CHECKS flag set to true by default.
The Bonita container is launched with REST_API_DYN_AUTH_CHECKS flag set to true by default.
It means that all [dynamic permissions checks](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/rest-api-authorization#toc2) are activated.
In the sections below we will manipluate configuration into templates and not at a specific tenant. Indeed the default tenant (1) will be created during the first startup of bonita.
......
md/images/bcd_logo.png

7.62 KB | W: | H:

md/images/bcd_logo.png

22.5 KB | W: | H:

md/images/bcd_logo.png
md/images/bcd_logo.png
md/images/bcd_logo.png
md/images/bcd_logo.png
  • 2-up
  • Swipe
  • Onion skin
# Bonita Continuous Delivery Add-on
![Bonita Continuous Delivery Add-on](images/bcd.png)
This add-on provides a solution to use _Continuous Delivery_ practice for your Bonita Living Application development and deployment.
It is composed of two main parts:
* First a solution for Bonita stack provisioning on Cloud or on-premise.
* Second a framework for continuous integration of Living Application. _This CI framework will be delivered in future versions of the add-on._
This documentation focus on the first part: the solution and tooling for provisioning of a Bonita stack.
The tool is composed of a set of scripts to deploy a full Bonita stack automatically (database and Bonita Tomcat application server).
This toolkit is compatible with Amazon EC2 cloud platform (AWS), on premises servers and local virtual machines via [Vagrant](https://www.vagrantup.com/).
These scripts are powered by [Ansible](http://www.ansible.com). Short note from Wikipedia:
::: info
Ansible is a free software platform for configuring and managing computers. It combines multi-node software deployment, ad hoc task execution, and configuration management. It manages nodes over SSH or PowerShell and requires Python (2.4 or later) to be installed on them. Modules work over JSON and standard output and can be written in any programming language. The system uses YAML to express reusable descriptions of systems.
Welcome to **Bonita Continuous Delivery** documentation website!
:::
The Bonita Continuous Delivery (BCD) tooling is provided through a Docker container called _BCD Controller_. In this controller you’ll find all useful tooling to manage your provisioning of Bonita platform and more. This controller should be installed on your local machine.
![Bonita Provisioning](images/bonita_platform_stack.png)
* A “Host” can be an EC2 instance or a dedicated server.
* Files organization on the local machine:
* ~/.boto = should contains all credential to your AWS account (if any)
* ~/bonita-continuous-delivery = used as a work directory for the scripts.
* ~/.ssh/private_key = used to allow access to hosts
## AWS Prerequisites