quickstart.md 5.64 KB
Newer Older
jeremy's avatar
jeremy committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# Bonita Continuous Delivery Quick Start

Bonita Continuous Delivery (BCD) solution is provided as a `bonita-continuous-delivery_<version>.tar.gz` archive.

This page describes how to use this archive to quickly start using Bonita Continuous Delivery solution.


## Prepare your workstation

### Step-by-step installation

In order to ease your environment setup, we provide a [Docker](https://docs.docker.com/) image which contains all required dependencies and tools for the **Control Machine** (ie. the machine from which Bonita Continuous Delivery commands are launched).

Follow these installation steps on your workstation.

1. Make sure Docker is installed as described in the [Install Docker](https://docs.docker.com/engine/installation/) documentation.

1. Extract the `bonita-continuous-delivery_<version>.tar.gz` archive:
    ```
    $ tar xzf bonita-continuous-delivery_<version>.tar.gz
    ```
    This step creates a `ansible_<version>` directory which contains:
    - Bonita Continuous Delivery Ansible playbooks and roles.
    - A pre-built Docker image for the Control Machine. This Docker image is provided as a `bcd-controller_<version>.tar.gz` archive located in the `ansible_<version>/docker` directory.

1. Load the `bcd-controller_<version>.tar.gz` Docker image:
    ```
    $ cd ansible_<version>/docker
    $ gunzip -c bcd-controller_<version>.tar.gz | docker load
    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:
    - **`.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:
        ```ini
        [Credentials]
        aws_access_key_id = <YOUR_AWS_ACCESS_KEY>
        aws_secret_access_key = <YOUR_AWS_SECRET_ACCESS_KEY>
        ```
    - **`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`).
    - **`/local/path/to/ansible_<version>`** (mounted as `/home/bonita/ansible`) - The provided `ansible` directory contains Ansible playbooks for Bonita Continuous Delivery.

1. Start a Docker container for the Control Machine:
    ```
    $ docker run --rm -ti --hostname control_machine --name bcd-controller \
        -v <local_path_to_.boto_file>:/home/bonita/.boto \
        -v <local_path_to_ansible_directory>:/home/bonita/ansible \
        -v <local_path_to_ssh_private_key_file>:/home/bonita/.ssh/<ssh_private_key> \
        bonitasoft/bcd-controller /bin/bash
    ```

### Complete installation example

Here is a complete example of how to install the Control Machine Docker image for Bonita Continuous Delivery.

**Warning**: This example uses *fake* AWS credentials and SSH private key... :-)

Assuming you have a `bonita-continuous-delivery_0.1.0.tar.gz` archive in your `$HOME` directory:

```
$ cd $HOME
$ tar xzf bonita-continuous-delivery_0.1.0.tar.gz

$ cd ansible_0.1.0/docker

$ gunzip -c bcd-controller_0.1.0.tar.gz | docker load
[...]
Loaded image: bonitasoft/bcd-controller:0.1.0
Loaded image: bonitasoft/bcd-controller:latest

$ cd $HOME

$ ls -nh
total 418M
drwxrwxr-x 12 1000 1000 4,0K juil.  6 11:34 ansible_0.1.0
-rw-rw-r--  1 1000 1000 418M juil.  6 11:34 bonita-continuous-delivery_0.1.0.tar.gz

$ cat ~/.boto
[Credentials]
aws_access_key_id = AKO9PHAI7YOSHAEMOHS6
aws_secret_access_key = aicheeChe8Koh4aeSh3quum4tah8cohku3Hi8Eir

$ ls -n ~/.ssh/bonita_us-west-2.pem
-rw------- 1 1000 1000 1692 jul. 6 11:36 ~/.ssh/bonita_us-west-2.pem

$ docker run --rm -ti --hostname control_machine --name bcd-controller \
        -v ~/.boto:/home/bonita/.boto \
        -v ~/ansible_0.1.0:/home/bonita/ansible \
        -v ~/.ssh/bonita_us-west-2.pem:/home/bonita/.ssh/bonita_us-west-2.pem \
        bonitasoft/bcd-controller /bin/bash
bonita@control_machine:~$
bonita@control_machine:~$ cd ansible
bonita@control_machine:~/ansible$
```


## Use Bonita Continuous Delivery solution

We provide a [BCD Command Line Interface](../docker/cli/README.md) (CLI) to execute Bonita Continuous Delivery commands.

The BCD CLI is directly available as a `bcd` command when using the `bonitasoft/bcd-controller` Docker image.

The `bcd` command must be launched from the `ansible` directory where Bonita Continuous Delivery Ansible playbooks are located.

You can call the `bcd` command with the `--help` option to get available options and commands:
```
bonita@control_machine:~$
bonita@control_machine:~$ cd ansible
bonita@control_machine:~/ansible$ bcd --help
Usage: bcd [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

  Bonita Continuous Delivery CLI.

Options:
  -s, --scenario PATH    YAML scenario file (required)
  -y, --yes              Execute action without confirmation prompt
  -v, --verbose          Enable Ansible verbose mode
  -e, --extra-vars TEXT  Extra vars for Ansible (multiple) - Variables are
                         passed using the key=value syntax.
  -h, --help             Show this help message

Commands:
  status     Show the platform status
  create     Create AWS instances
  deploy     Deploy Bonita stack
  run-tests  Run Bonita performance tests
  undeploy   Undeploy Bonita stack
  destroy    Destroy AWS machines (EC2 instances)
```