Unverified Commit f86c3285 authored by Agustin  Larreinegabe's avatar Agustin Larreinegabe Committed by GitHub

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

fix static inventory documentation + update with new examples
parents 6f20399e 703d84f5
# 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/).
:::
......@@ -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.
......
......@@ -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
......@@ -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
......
......@@ -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)
......
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