Commit f955ed16 authored by Truc Nguyen's avatar Truc Nguyen Committed by JeremJR

split Provisioning and BuildAndDeploy steps in getting started guide (#70)

parent 450f659a
......@@ -6,8 +6,8 @@ If you implement this kind of authentication, when you start the BCD Controller
```
$ docker run --rm -t -i --name bcd-controller \
-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> \
-v <host_path_to_bonita-continuous-delivery_folder>:/home/bonita/bonita-continuous-delivery \
-v <host_path_to_ssh_private_key>:/home/bonita/.ssh/<ssh_private_key> \
bonitasoft/bcd-controller /bin/bash
```
......
......@@ -22,9 +22,13 @@ Loaded image: bonitasoft/bcd-controller:latest
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:
- **`/host/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.
- <div class="list-group-item list-group-item-warning">This file is required for <strong>Provisioning</strong>. It is not required for Living App management.</div>
**`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`).
- <div class="list-group-item list-group-item-warning">AWS credentials are required for <strong>Provisioning on AWS</strong>. It is not required for Living App management.</div>
**`.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>
......@@ -45,9 +49,9 @@ The first method to start a BCD Controller Docker container on the control works
```
$ 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> \
-v <host_path_to_.boto>:/home/bonita/.boto \
-v <host_path_to_bonita-continuous-delivery_folder>:/home/bonita/bonita-continuous-delivery \
-v <host_path_to_ssh_private_key>:/home/bonita/.ssh/<ssh_private_key> \
bonitasoft/bcd-controller /bin/bash
```
......@@ -71,10 +75,11 @@ services:
stdin_open: true
tty: true
command: /bin/bash
working_dir: /home/bonita/bonita-continuous-delivery
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>
- <host_path_to_.boto>:/home/bonita/.boto
- <host_path_to_ssh_private_key>:/home/bonita/.ssh/<ssh_private_key>
```
Then start the BCD controller container interactively with:
......
# Bonita Continuous Delivery Quick Start
# Getting started
The BCD add-on is provided as a `bonita-continuous-delivery_<version>.zip` archive.
This page describes how to use this archive to quickly start using Bonita Continuous Delivery solution.
This page describes how to use this archive to start your journey with Bonita Continuous Delivery.
## Before you begin
### Licensing prerequisites
To use BCD you must have an active Bonitasoft Subscription and a dedicated access to Bonitasoft license service. Indeed BCD requires such access in order to dynamically retrieve Bonita licenses while deploying your platform.
Contact your sales representative for more information.
### AWS Prerequisites
If you consider deploying to Amazon Web Services (AWS) platform, first read the [AWS prerequisites tutorial](aws_prerequisites.md) which describes how to configure AWS for BCD.
## Preparing the control workstation
### Step-by-step installation
## Installation guide
In order to ease your environment setup, we provide a Docker image called **[BCD Controller](bcd_controller.md)** image which contains all required dependencies and tools for the control workstation (ie. the host from which Bonita Continuous Delivery commands are launched).
### Common installation steps
Follow these installation steps on your control workstation.
1. Make sure Docker is installed as described in the [Install Docker](https://docs.docker.com/engine/installation/) documentation.
......@@ -42,20 +31,7 @@ Follow these installation steps on your control workstation.
Loaded image: bonitasoft/bcd-controller:<version>
Loaded image: bonitasoft/bcd-controller:latest
The `bonitasoft/bcd-controller` Docker image is now available. To use the image, it is recommended to prepare the following local files which will be shared as Docker volumes in the next step:
* **`/local/path/to/bonita-continuous-delivery_<version>`** (mounted as `/home/bonita/bonita-continuous-delivery`) - The provided `bonita-continuous-delivery` directory contains Ansible playbooks for Bonita Continuous Delivery.
* <div class="list-group-item list-group-item-warning">This file is required for <strong>Provisioning</strong>. It is not required for Living App management.</div>
**`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`).
* <div class="list-group-item list-group-item-warning">This file is required for <strong>Provisioning on AWS</strong>. It is not required for Living App management.</div>
**`.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. The content of a `.boto` file is as follows:
[Credentials]
aws_access_key_id = <YOUR_AWS_ACCESS_KEY>
aws_secret_access_key = <YOUR_AWS_SECRET_ACCESS_KEY>
The `bonitasoft/bcd-controller` Docker image is now available on the control workstation.
4. Make sure BCD dependencies are present.
BCD expects Bonita version-specific dependencies to be present in the `bonita-continuous-delivery_<version>/dependencies` directory. BCD dependencies are provided separately as a `bonita-continuous-delivery-dependencies_<bonita_version>.zip` archive.
Basically, the following artifacts must be extracted from the `bonita-continuous-delivery-dependencies_<bonita_version>.zip` archive into the `dependencies` directory:
......@@ -65,12 +41,48 @@ Follow these installation steps on your control workstation.
5. Start a BCD Controller Docker container on the control workstation:
$ docker run --rm -ti --hostname bcd-controller --name bcd-controller \
-v <local_path_to_.boto_file>:/home/bonita/.boto \
-v <local_path_to_bonita-continuous-delivery_directory>:/home/bonita/bonita-continuous-delivery \
-v <local_path_to_ssh_private_key_file>:/home/bonita/.ssh/<ssh_private_key> \
-v <host_path_to_bonita-continuous-delivery_directory>:/home/bonita/bonita-continuous-delivery \
bonitasoft/bcd-controller /bin/bash
### Complete installation example
This command bind mounts the _bonita-continuous-delivery_ directory on the control workstation into the BCD controller container.
### Additional steps for Provisioning
::: info
The following installation steps are required when using BCD for **Provisioning Bonita stacks**. They are not required for Living Application Management.
:::
#### Licensing prerequisites
While provisioning Bonita stacks, BCD automatically retrieves and installs Bonita licenses for the Bonita platform. Therefore, you must have an active Bonitasoft Subscription and a dedicated access to Bonitasoft license service in order to use BCD for Provisioning.
Contact your sales representative for more information.
#### AWS Prerequisites
If you consider deploying to Amazon Web Services (AWS) platform, first read the [AWS prerequisites tutorial](aws_prerequisites.md) which describes how to configure AWS for BCD.
BCD can create and delete [AWS EC2 instances](https://aws.amazon.com/ec2/) automatically by making programmatic calls to AWS. In order to use this feature, you must provide AWS credentials, for example through a [`.boto`](https://boto.readthedocs.io/en/latest/boto_config_tut.html) file. The content of a `.boto` file is as follows:
[Credentials]
aws_access_key_id = <YOUR_AWS_ACCESS_KEY>
aws_secret_access_key = <YOUR_AWS_SECRET_ACCESS_KEY>
Then the `.boto` file has to be mounted from the control workstation into the BCD controller while starting the container. Add the following option to the `docker run` command:
-v <host_path_to_.boto_file>:/home/bonita/.boto
#### SSH key file
BCD uses SSH to communicate with target machines. Therefore the BCD controller must have access to the related SSH private key file. 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 must only be accessible from your user** (`chmod 600 <host_path_to_ssh_private_key_file>`).
Then the SSH key file has to be mounted from the control workstation into the BCD controller while starting the container. Add the following option to the `docker run` command:
-v <host_path_to_ssh_private_key_file>:/home/bonita/.ssh/<ssh_private_key>
## Complete installation example
Here is a complete example of how to install the BCD Controller Docker image.
......@@ -120,7 +132,7 @@ Finally here is a sample command to start a BCD controller container:
## Using Bonita Continuous Delivery add-on
::: warning
At this stage of the _Quick start_ guide, you should have a BCD controller container up and running.
At this stage of the _Getting started_ guide, you should have a BCD controller container up and running.
:::
### Command Line Interface
......
......@@ -35,10 +35,10 @@ It is composed of two parts:
<div class="panel panel-default">
<div class="panel-heading">Getting started</div>
<div class="panel-body">
<div style="padding: 15px; padding-bottom: 0px;">Follow this guide with step-by-step instructions to quickly start using Bonita Continuous Delivery solution.</div>
<div style="padding: 15px; padding-bottom: 0px;">Follow this guide with step-by-step instructions to start using Bonita Continuous Delivery solution.</div>
<div class="menu-block-wrapper">
* [:fa-angle-double-right: Getting started with BCD](quickstart.md)
* [:fa-angle-double-right: Getting started with BCD](getting_started.md)
<!--{ul:.menu .nav}-->
</div>
</div>
......
* [Release notes](release_notes.md)
* [Quick start guide](quickstart.md)
* [Getting started](getting_started.md)
* [BCD services and scenarios](_bcd_services_and_scenarios.md)
* [Controller Docker image](bcd_controller.md)
* [Command-line interface](bcd_cli.md)
......
......@@ -84,9 +84,9 @@ If you want to persist the log, you can add a ***volume*** in when you run `dock
```
$ 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> \
-v <local_path_to_your_ansible_log>:/var/log/ansible.log \
-v <host_path_to_.boto>:/home/bonita/.boto \
-v <host_path_to_bonita-continuous-delivery_folder>:/home/bonita/bonita-continuous-delivery \
-v <host_path_to_ssh_private_key>:/home/bonita/.ssh/<ssh_private_key> \
-v <host_path_to_your_ansible_log>:/var/log/ansible.log \
bonitasoft/bcd-controller /bin/bash
```
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment