Merge pull request #77 from bonitasoft/fix/static-inventory-doc

fix static inventory documentation + update with new examples

md/deploy_with_static_inventory.md

-# How to deploy Bonita on existing server
+# How to deploy with a static inventory
 
-BCD can not only deploy your Bonita Stack in the cloud. You can also deploy your stack on your existing hosts.
-On this page, you will find detailed information about the usage of BCD with your existing hosts and finally, 
-you will see an example, creating virtual machines with Vagrant and deploying your Bonita application with BCD.
+BCD lets you deploy a Bonita stack on your existing hosts using a **static inventory**.  
+On this page, you will find detailed information about the usage of BCD with your existing hosts. We will also provide an example creating virtual machines with [Vagrant](https://www.vagrantup.com/) and deploying a Bonita stack with BCD.
 
 ## Preparing configuration files
-There is two main files to configure:
+
+There are two main files to configure: an **Ansible inventory** and a **BCD scenario**.
+
 ### Inventory
-This file defines the hosts and groups of hosts upon which BCD will operates. The location of the inventory files is
-`bonita-continuous-delivery_x.x.x/ansible/inventory/`.
-and `static-inventory-1-machine.EXAMPLE` in the `static-inventory` directory.
-In this file, there are two group names, `database` and `bonita` that must appear and under each one you have to describe
-your machines, and a group with the same name of your bonita stack id grouping the `database` and `bonita` groups.
-Also, you have to specify a group variables for `bonita` group with:
-* `bonita_address`, that is the IP of Bonita host
-* `bonita_db_host`, that is the IP of your database
 
-You can see an example in `bonita-continuous-delivery_x.x.x/ansible/inventory/static-inventory/` for one or two machines.  
+This file defines the hosts and groups of hosts upon which BCD will operates. The preferred location for inventory files is the `ansible/inventory` directory.
+
+In particular, you will find examples of static inventory files in the `static-inventory` subdirectory.
 
 ::: info
-It is recommended to have a clear understanding on [Ansible Inventories](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html)
-:::                                                  
+Refer to [Ansible's documentation](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html) for further details about Ansible inventories.
+:::
 
 ### Scenario
-The scenarios follows the same rules as described in the [Scenario file reference](scenarios.md). There are five
-parameters that you don't have to forget to set-up: 
-* bcd_provider: Infrastructure provider. It has to be set with `static-inventory`
-* ansible_ssh_user: The ssh user to use.
-* ansible_ssh_private_key_file: Private key file used by ssh.
-* bcd_inventory: Ansible inventory path required when `bcd_provider` is `static-inventory`
-* configuration: Configuration filename used to group variables for common deployment types.
 
-You can see an example of scenario in `bonita-continuous-delivery_x.x.x/scenarios/static_inventory.yml.EXAMPLE`
+Scenarios follow the same rules as described in the [Scenario file reference documentation](scenarios.md). There are five mandatory variables to configure while using BCD with static inventories:
+* `bcd_provider`: Infrastructure provider. It has to be set with `static_inventory`
+* `ansible_ssh_user`: The ssh user to use.
+* `ansible_ssh_private_key_file`: Private key file used by ssh.
+* `bcd_inventory`: Ansible inventory path required when `bcd_provider` is `static_inventory`
+* `configuration`: Configuration filename used to group variables for common deployment types.
+
+An example scenario is provided with the `scenarios/static_inventory.yml.EXAMPLE` file.
 
-## Deploy with Vagrant
-You will see a complete example of deploying on existing virtual machines created with Vagrant.
+
+## Example with Vagrant
+
+This section describes a complete example of Bonita stack deployment on existing virtual machines created with Vagrant.
 
 ::: warning
-For this tutorial it is highly recommended to have a clear understanding of [Vagrant](https://www.vagrantup.com/intro/index.html) prior to reading this documentation.
+For this tutorial, it is highly recommended to have a clear understanding of [Vagrant](https://www.vagrantup.com/intro/index.html).
 :::
 
 ::: info
-This tutorial is adapted only to the Linux and Mac environment.
+This tutorial is adapted to Linux and Mac environments only.
 :::
 
-## Requirements
-* First, [Vagrant](https://www.vagrantup.com/downloads.html) and [Virtualbox](https://www.virtualbox.org/) as a hypervisor,
- installed on your host.
-* Second, you will need to create and configure your host machine using your [Vagrantfile](https://www.vagrantup.com/docs/vagrantfile/).
-An example of `Vagrantfile` is provided in your `bonita-continuous-delivery_<version>/vagrant/` directory. You can find an
-example for one machine or two.
-* Third, you need to define your infrastructure and Bonita stack with a scenario. An example scenario file 
-named **vagrant_single.yml.EXAMPLE** is provided in the **bonita-continuous-delivery_x.x.x/scenarios**. For more
-information you can read the **[BCD Scenario reference](scenarios.md)**
+### Requirements
+
+* First, [Vagrant](https://www.vagrantup.com/downloads.html) and [Virtualbox](https://www.virtualbox.org/) as a hypervisor must be installed on your host.
+* Second, you will need to create and configure your host machine using your [Vagrantfile](https://www.vagrantup.com/docs/vagrantfile/). An example of `Vagrantfile` is provided in the `vagrant` directory. You can find an
+example for one or two machines infrastructure.
+* Third, you need to define your infrastructure and Bonita stack with a scenario. An example scenario file named **vagrant_single.yml.EXAMPLE** is provided in the **scenarios** directory. For more information you can read the **[BCD Scenario reference](scenarios.md)**.
 * Finally, the virtual machine that you will create must have access to the Internet because some packages will be updated/installed.
 
-## Step-by-step tutorial
+### Step-by-step tutorial
+
 Here is a complete example using the configuration files provided.
 
 ::: warning
-This example uses an insecure private key. See [more](https://www.vagrantup.com/docs/vagrantfile/ssh_settings.html)... 
+This example uses an insecure private key. See [more](https://www.vagrantup.com/docs/vagrantfile/ssh_settings.html)...
 :::
 
 Assuming you have a `bonita-continuous-delivery_2.0.0` directory in your `$HOME` directory.
 
-### 1. Prepare and start your host
-This step will create and configure a single virtual machine with an IP 192.168.10.10 defined in `Vagrantfile`
-In your host machine:
+#### 1. Prepare and start your target virtual machine
+
+This step will create and configure a single virtual machine with an IP **192.168.10.10** defined in `Vagrantfile`.  
+
+On your host machine:
 ```bash
 $ cd $HOME/bonita-continuous-delivery_2.0.0/vagrant/1-machine/
 
@@ -79,33 +76,36 @@ Bringing machine 'bonita-stack' up with 'virtualbox' provider...
 
 $ VBoxManage list runningvms
 "1-machine_bonita-stack_1525085617284_45644" {553ff7af-4d9a-4325-a902-ae17edce1e54}
-
 ``` 
-### 2. Launch your BCD controller and deploy
 
-```bash
-$ docker run --rm -t -i --name bcd-controller \
--v $HOME/bonita-continuous-delivery_2.0.0/:/home/bonita/bonita-continuous-delivery \
--v ~/.vagrant.d/insecure_private_key:/home/bonita/.vagrant.d/insecure_private_key \
-bonitasoft/bcd-controller /bin/bash
+#### 2. Launch your BCD controller and deploy Bonita stack
 
+Copy the **vagrant_single.yml.EXAMPLE** to a **scenarios/vagrant_single.yml** file. Edit your scenario as necessary and start a BCD controller.
+
+```bash
+$ docker run --rm -ti --hostname bcd-controller --name bcd-controller \
+        -v ~/bonita-continuous-delivery_2.0.0:/home/bonita/bonita-continuous-delivery \
+        -v ~/.vagrant.d/insecure_private_key:/home/bonita/.vagrant.d/insecure_private_key \
+        bonitasoft/bcd-controller /bin/bash
 bonita@bcd-controller:~$ cd bonita-continuous-delivery
 bonita@bcd-controller:~/bonita-continuous-delivery$
-bonita@bcd-controller:~/bonita-continuous-delivery$bcd -s scenario/vagrant_single.yml stack deploy
-
+bonita@bcd-controller:~/bonita-continuous-delivery$bcd -s scenarios/vagrant_single.yml stack deploy
 ```
 
-### 3. Open bonita url
-You should now be able to access Bonita Portal at  http://192.168.10.10:8081/bonita
+#### 3. Open Bonita URL
+
+You should now be able to access Bonita Portal at **http://192.168.10.10:8081/bonita**.
 
-## Cleaning up your environment
+#### 4. Cleaning up your environment
+
+Before destroying your virtual machines, it is recommended to *undeploy* your Bonita stack with BCD as follows:
 
-It is recommended to *undeploy* your Bonita application with the BCD controller like in the following:
 ```bash
-$ bcd -y -s <path/to/scenario> stack undeploy
+$ bcd -s <path/to/scenario> -y stack undeploy
 ```
-After, you can destroy your virtual machine `vagrant destroy` command in the same path of your `Vagrantfile`.
+
+Then you may destroy your virtual machine with the `vagrant destroy` command.
 
 ::: info
-You can read more about the Vagrant [CLI](https://www.vagrantup.com/docs/cli/) 
+You can read more about the Vagrant CLI on [Vagrant documentation site](https://www.vagrantup.com/docs/cli/).
 :::

md/getting_started.md

@@ -178,7 +178,11 @@ Read the **[BCD Command-line interface](bcd_cli.md)** page for further informati
 
 BCD requires a YAML configuration file called **Scenario** which describes your infrastructure and the Bonita stack to deploy.
 
-An example scenario file named **uswest_performance.yml.EXAMPLE** is provided in the **scenarios** directory. Use this example to customize your scenario and save it with a `.yml` file extension.
+Example scenario files are provided in the **scenarios** directory, including:
+- **uswest_performance.yml.EXAMPLE** - a scenario for both stack and living application management with AWS provisioning
+- **build_and_deploy.yml.EXAMPLE** - a scenario for living application management only
+
+Use these examples to customize your scenario and save it with a `.yml` file extension.
 
 ::: info
 Read the **[BCD Scenario reference](scenarios.md)** page for a comprehensive description of scenario variables.

md/livingapp_build_and_deploy.md

@@ -3,17 +3,14 @@
 Bonita Continuous Delivery enables you to easily build and deploy a Bonita Living Applications on a running Bonita platform.
 It uses the [Bonita Living Application Builder](livingapp_build.md) and the [Bonita Living Application Deployer](livingapp_deploy.md).
 
-In the following, we present best practices and various uses cases to let you easily build and deploy your Bonita Living Application repository.
+In the following, we present best practices and various use cases to let you easily build and deploy your Bonita Living Application repository.
 
 All examples assume that:
-  * you have cloned the demo [Bonita Vacation Management example repository](https://github.com/bonitasoft/bonita-vacation-management-example)
-GitHub repository as described in the [Bonita Living Application Builder](livingapp_build.md) documentation
-  * you have already defined a scenario file called `build_and_deploy.yml` stored in the BCD `scenarios` directory
-  * you already have a Bonita stack up and running, defined by the `build_and_deploy.yml` scenario file
-
-If you want to deploy into a Bonita platform running on an existing machine, you can find an example of a scenario file `bonita-continuous-delivery_2.0.0/scenario/build_and_deploy.yml.EXAMPLE` 
-with its inventory file in `bonita-continuous-delivery_2.0.0/ansible/inventory/static-inventory/livingapp-build-deploy-static-inventory.EXAMPLE`.
- 
+  * you have cloned a Git repository as described in the [Bonita Living Application Builder](livingapp_build.md) documentation
+  * you have already defined a scenario file for Living Application management and stored it in the BCD `scenarios` directory
+  * you already have a Bonita platform up and running
+
+
 ## Best practices about repositories
 
 The _Bonita Living Application Builder_ is made to build an entire Bonita repository.  
@@ -101,7 +98,7 @@ This use case is a bit more advanced. Imagine that your Bonita repository is sto
 
 As described in the [Bonita Living Application Deployer documentation](livingapp_deploy.md), it is possible to pass to the deployer a _deployment descriptor file_. This file must be called _deploy.json_ and be at the root of the application archive.  
 The deployment descriptor file is used to specify which resources have to be deployed, and with which policy. It is an alternative way to select a sub part of the application archive to deploy.  
-An interesting way to use it is to store some deployment descriptor files in your Bonita repository, one for each 'build and deploy' scenario you want to perform. Between the build and the deploy  phase, just move the fine deployment descriptor at the root of your application archive, as described above.  
+An interesting way to use it is to store some deployment descriptor files in your Bonita repository, one for each 'build and deploy' scenario you want to perform. Between the build and the deploy phase, just move the deployment descriptor file at the root of your application archive, as described above.  
 ::: warning
 The format of the deployment descriptor file is not friendly to use. It might evolve in further versions.
 :::
\ No newline at end of file

md/scenarios.md

@@ -5,7 +5,12 @@ Scenarios enable you to define your infrastructure and Bonita stack. A scenario
 The variables described in a scenario have precedence over those defined in the playbooks or the group vars. It is still possible to overload scenario variables with `--extra-vars` declaration in the `bcd` command line. For instance overloading `bonita_version` can be interesting if you want to test multiple versions of Bonita without duplicating scenario files.
 
 ::: info
-An example scenario file named **uswest_performance.yml.EXAMPLE** is provided in the **scenarios** directory. Use this example to customize your scenario and save it with a `.yml` file extension.
+Example scenario files are provided in the **scenarios** directory:
+- **uswest_performance.yml.EXAMPLE** - a scenario for both stack and living application management with AWS provisioning
+- **static_inventory.yml.EXAMPLE** - a scenario for both stack and living application management with static inventory
+- **build_and_deploy.yml.EXAMPLE** - a scenario for living application management only
+
+Use these examples to customize your scenario and save it with a `.yml` file extension.
 :::
 
 ## Core variables

md/taxonomy.md

@@ -10,7 +10,7 @@
         * [Configure Amazon Web Services (AWS) for BCD](aws_prerequisites.md)
         * [Configure AWS single sign-on](aws_sso.md)
         * [Assume IAM role within AWS Organizations](aws_organizations.md)
-        * [Deploy with a static inventory](deploy_with_static_inventory.md)        
+        * [Deploy with a static inventory](deploy_with_static_inventory.md)
         * [Customize the Bonita container](_custom_init.md)
             * [Using initialization scripts](custom_init.md)
             * [Configuring REST API authorization](how_to_configure_rest_api_authorization.md)