Commit d372fdf9 authored by Truc Nguyen's avatar Truc Nguyen

feat(livingapp): update livingapp howtos with configuration management (BCD-315)

parent e7f82236
......@@ -38,7 +38,7 @@ $ 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
$ bcd livingapp build -p path/to/livingapp-repo -e Test
```
Running the `version` command which does not require a scenario file:
......@@ -63,7 +63,7 @@ $ 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
livingapp build -p path/to/livingapp-repo -e Test deploy
```
......
......@@ -111,7 +111,7 @@ node('bcd') {
}
stage('build-bonita-app') {
bcd args: "livingapp build -p ${WORKSPACE} -e Qualification"
bcd args: "livingapp build -p ${WORKSPACE} -e Test"
}
def jobBaseName = "${env.JOB_NAME}".split('/').last()
......
......@@ -20,17 +20,17 @@ For this tutorial, we will use the [Bonita Vacation Management example repositor
```
$ cd bonita-continuous-delivery
$ git clone https://github.com/bonitasoft/bonita-vacation-management-example
$ git clone -b dev/7.8.0 https://github.com/bonitasoft/bonita-vacation-management-example
```
This step creates a `bonita-continuous-delivery/bonita-vacation-management-example` directory which is the Living App repository we are going to build.
This step creates a `bonita-continuous-delivery/bonita-vacation-management-example` directory which is the Living App repository we are going to build. This example checks out the `dev/7.8.0` Git branch.
### 2. Provide the repository's build dependencies
The next step is to provide all dependencies required to build your repository, see [Common Installation Steps](getting_started.md#toc1).
Hence the following artifacts must be present in the `$BCD_HOME/dependencies/<bonita_version>` directory:
Hence the following artifacts must be present in the `$BCD_HOME/dependencies` directory or any of its subdirectories:
**`bonita-la-builder-<bonita_version>-exec.jar`**
The Bonita Living Application Builder library. Its version must correspond to the **`bonita_version`** variable defined in your BCD scenario. This is the version of the Bonita stack where generated artifacts will be deployed.
......@@ -46,16 +46,22 @@ BCD is now ready to build your repository using the `bcd livingapp build` comman
```
$ cd bonita-continuous-delivery
$ bcd -s scenarios/euwest1_performance.yml --yes livingapp build -p bonita-vacation-management-example -e Qualification
$ bcd -s scenarios/build_and_deploy.yml --yes livingapp build -p bonita-vacation-management-example -e Test
```
The build process finally generates a zip package located in the repository's `target` repository. The generated archive is named after the repository's root directory name.
For instance with the `bonita-vacation-management-example` example, a `bonita-vacation-management-example/target/bonita-vacation-management-example_<timestamp>.zip` file is generated.
The build process finally generates a **.zip** package and a **.bconf** artifact located in the repository's `target` repository. The generated artifacts are named after the repository's root directory name and the selected environment name.
For instance with the `bonita-vacation-management-example` example, the following files will be generated:
- `bonita-vacation-management-example/target/bonita-vacation-management-example-<environment>-<timestamp>.zip`
- `bonita-vacation-management-example/target/bonita-vacation-management-example-<environment>-<timestamp>.bconf`
::: info
Refer to the [BCD Command-line reference](bcd_cli.md) for a complete list of available options for the `bcd livingapp build` command.
Since BCD 3.0.0, process configurations are built into a separate **.bconf** artifact. This configuration artifact allows to separate process configuration (parameters) from application assets.
As a result, the same **.zip** package can be deployed on all environments (Development, Test, Staging) whereas a specific **.bconf** artifact may be applied to each environment.
:::
Refer to the [BCD Command-line reference](bcd_cli.md) for a complete list of available options for the `bcd livingapp build` command.
## Repository vs. Builder version compatibility
......@@ -79,7 +85,7 @@ In this example, the REST API extension has a dependency on Bonita 7.7.0.
```
$ cd bonita-continuous-delivery_3.0.0
$ git clone https://github.com/bonitasoft/bonita-vacation-management-example
$ git clone -b dev/7.8.0 https://github.com/bonitasoft/bonita-vacation-management-example
$ ls -nh bonita-vacation-management-example
total 60K
drwxrwxr-x 2 1000 1000 4,0K Mar 29 16:17 applications
......@@ -99,7 +105,7 @@ drwxr-xr-x 26 1000 1000 4,0K Mar 29 16:19 web_widgets
drwxrwxr-x 2 1000 1000 4,0K Mar 29 16:17 xsd
$ grep "<bonita.version>" bonita-vacation-management-example/restAPIExtensions/tahitiRestApiExtension/pom.xml
<bonita.version>7.6.3</bonita.version>
<bonita.version>7.7.0</bonita.version>
$ ls -nhR dependencies/
dependencies/:
......@@ -120,7 +126,7 @@ total 106096
-rw-r--r-- 1 1000 1000 19.2M Nov 13 14:03 bonita-sp-7.8.0-maven-repository.zip
$ grep "bonita_version" scenarios/euwest1_performance.yml
$ grep "bonita_version" scenarios/build_and_deploy.yml
bonita_version: 7.8.0
```
......@@ -128,13 +134,15 @@ bonita_version: 7.8.0
**In the BCD controller container**
```
bonita@bcd-controller:~$ cd bonita-continuous-delivery
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/euwest1_performance.yml --yes livingapp build -p bonita-vacation-management-example -e Qualification
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/build_and_deploy.yml --yes livingapp build -p bonita-vacation-management-example -e Test
bonita@bcd-controller:~/bonita-continuous-delivery$ ls -nh bonita-vacation-management-example/target
total 8,1M
drwxr-xr-x 9 1000 1000 4,0K Mar 29 16:29 bonita-vacation-management-example
-rw-r--r-- 1 1000 1000 8,1M Mar 29 16:29 bonita-vacation-management-example_20180329162901.zip
drwxr-xr-x 3 1000 1000 4,0K Mar 29 16:29 bpmn
drwxr-xr-x 2 1000 1000 4,0K Mar 29 16:29 generated-jars
drwxr-xr-x 3 1000 1000 4,0K Mar 29 16:29 ui-designer
total 9,0M
drwxr-xr-x 9 1000 1000 4,0K Dec 6 13:59 bonita-vacation-management-example
-rw-r--r-- 1 1000 1000 2,4K Dec 6 13:59 bonita-vacation-management-example-Test-20181206125838.bconf
-rw-r--r-- 1 1000 1000 9,0M Dec 6 13:59 bonita-vacation-management-example-Test-20181206125838.zip
drwxr-xr-x 3 1000 1000 4,0K Dec 6 13:59 bpmn
drwxr-xr-x 3 1000 1000 4,0K Dec 6 13:58 configurations
drwxr-xr-x 2 1000 1000 4,0K Dec 6 13:58 generated-jars
drwxr-xr-x 3 1000 1000 4,0K Dec 6 13:58 ui-designer
```
# How to build and deploy Living Apps (Best Practices)
Bonita Continuous Delivery enables you to easily build and deploy a Bonita Living Applications on a running Bonita platform.
Bonita Continuous Delivery enables you to easily build and deploy a Bonita Living Applications on a Bonita runtime.
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 use cases to let you easily build and deploy your Bonita Living Application repository.
......@@ -8,7 +8,7 @@ In the following, we present best practices and various use cases to let you eas
All examples assume that:
* 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
* you already have a Bonita runtime up and running
## Best practices about repositories
......@@ -42,12 +42,11 @@ This is the simplest use case: you want to build a Bonita repository and deploy
To do so, you only have to pass the repository path to the build command and chain a deploy command without path parameter
like in the following:
```
$ bcd -y -s <path/to/scenario> livingapp build -p <path/to/bonita/repository> deploy
$ bcd -s <path/to/scenario> -y livingapp build -p <path/to/bonita/repository> -e <environment> deploy
```
This command will first build the Bonita repository. The output of the build is a zip file. It is located in the _target_ directory, created by the builder. This zip file corresponds to the _Application Archive_ used by the deployer. It contains all the resources built from the input repository.
This command will first build the Bonita repository for the given environment. The output of the build command are located in the _target_ directory, created by the builder. The generated _Application Archive_ and _Configuration Artifact_ are then automatically used by the deploy command.
In a second time, the deployer deploys all those resources on the running Bonita platform.
## Build and select what to deploy
......@@ -55,12 +54,12 @@ Sometimes, you may need to perform some actions between the build phase and the
The idea is always the same:
- **Build** a Bonita repository with BCD
- **Update** the application archive created by the builder
- **Deploy** the updated application archive
- **Update** the application or configuration artifacts created by the builder
- **Deploy** the updated artifacts
First, we build the Bonita repository:
```
bcd -y -s <path/to/scenario> livingapp build -p <path/to/bonita/repository>
bcd -s <path/to/scenario> -y livingapp build -p <path/to/bonita/repository> -e <environment>
```
The build operation creates a **target** directory in the Bonita repository. Let's move to this directory:
```
......@@ -68,7 +67,7 @@ cd <path/to/bonita/repository>/target
```
This directory contains built artifacts, including the application archive we want to update. Keep in mind that the deployer can take a zip file or a directory as input. So, we are going to unzip the raw application archive, in a _to-deploy_ directory:
```
unzip -d to-deploy <bonita-repository-name>_<timestamp>.zip
unzip -d to-deploy <bonita-repository-name>-<environment>-<timestamp>.zip
```
A new directory _to-deploy_ has been createda and it contains all the built artifacts from your Bonita repository.
......@@ -78,7 +77,7 @@ You can perform some actions on the content of this directory to customize your
In this example, we only want to deploy the BDM. The _to-deploy_ directory should contain a subfolder _bdm_. We simply need to tell the deployer to deploy this subfolder as follows:
```
bcd -y -s <path/to/scenario> livingapp deploy -p <path/to/bonita/repository>/target/to-deploy/bdm
bcd -s <path/to/scenario> -y livingapp deploy -p <path/to/bonita/repository>/target/to-deploy/bdm
```
#### Example 2: I only want to deploy all the resources from my Bonita repository except applications
......@@ -86,12 +85,12 @@ bcd -y -s <path/to/scenario> livingapp deploy -p <path/to/bonita/repository>/tar
The _to-deploy_ directory should contain a subfolder _applications_. We simply need to delete this subfolder, then tell the deployer to deploy the _to-deploy_ directory as follows:
```
rm -rf <path/to/bonita/repository>/target/to-deploy/applications/
bcd -y -s <path/to/scenario> livingapp deploy -p <path/to/bonita/repository>/target/to-deploy
bcd -s <path/to/scenario> -y livingapp deploy -p <path/to/bonita/repository>/target/to-deploy
```
#### Example 3: I want to add some custom pages in the resources to deploy
This use case is a bit more advanced. Imagine that your Bonita repository is stored on a given Git repository and your custom pages used by your applications in an other Git repository. You will have to build your Bonita repository as described above, then to retrieve your custom pages (Git clone...) and to add them to the application archive to deploy.
This use case is a bit more advanced. Imagine that your Bonita repository is stored on a given Git repository and your custom pages used by your applications in an other Git repository. You will have to build your Bonita repository as described above, then to retrieve your custom pages (Git clone...) and to add them to the application archive to deploy.
## Build and select how to deploy parts of the Application Archive
......@@ -99,6 +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 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
The format of the deployment descriptor file might evolve in future versions to make it more user-friendly.
:::
......@@ -24,8 +24,11 @@ First, here are the **types of artifacts** that can be deployed:
The deployment entry point is called an **Application Archive**. It consists of all artifacts to be deployed and an optional configuration file called **Deployment Descriptor**. This file describes which **Policy** should be applied while deploying each artifact.
Since BCD 3.0.0, **Application Configuration** artifacts can also be deployed. An Application Configuration artifact has a **.bconf** extension and is generated by the [Living App Build command](livingapp_build.md).
Application Configuration artifacts can be customized using the `bcd livingapp extract-conf|merge-conf` commands as described in [this documentation](livingapp_manage_configuration.md).
::: danger
Read carefully the deployment supported policies per artifact before deploying a living application on a final Production environment. Using the default policies may result in a clean of the whole Bonita runtime.
Read carefully the deployment supported policies per artifact before deploying a Living Application on an existing environment. Using the default policies may result in a clean of the whole Bonita runtime.
:::
### Application Archive structure
......@@ -176,11 +179,14 @@ The following artifacts are used with **implicit policies**. It means that you d
Use the `bcd livingapp deploy` command to deploy Living App artifacts:
```
bcd -s <scenario> livingapp deploy -p <path>
bcd -s <scenario> livingapp deploy -p <application_path> -c <configuration_path>
```
where:
* **\<scenario>** is the path to the BCD scenario which defines the target Bonita stack. Artifacts will be deployed using tenant credentials defined by this scenario (`bonita_tenant_login` and `bonita_tenant_password` variables).
* **\<path>** is the path to the Application Archive to deploy (file or directory).
* **\<application_path>** is the path to the Application Archive to deploy (zip file or directory).
* **\<configuration_path>** is the path to the Application Configuration bconf artifact to deploy.
You may deploy an application archive and an application configuration artifact separately. The `bcd livingapp deploy` command requires at least one the deployable artifacts to be provided.
You can add a **--debug** option to enable debug mode and increase verbosity.
......@@ -194,30 +200,36 @@ Refer to the [BCD Command-line reference](bcd_cli.md) for a complete list of ava
Here is how to deploy artifacts of the [Bonita Vacation Management example Living App](https://github.com/bonitasoft/bonita-vacation-management-example).
Assuming that:
* artifacts have been built and that a `bonita-vacation-management-example_20180329162901.zip` Application Archive zip file has been generated in the `bonita-vacation-management-example/target` directory
* a Bonita stack is up and running as defined in a `scenarios/euwest1_performance.yml` scenario file
* a `bonita-vacation-management-example-Test-20181206125838.zip` Application Archive zip file has been generated in the `bonita-vacation-management-example/target` directory
* a `bonita-vacation-management-example-Test-20181206125838.bconf` Application Configuration artifact bconf file has been generated in the `bonita-vacation-management-example/target` directory
* a Bonita runtime is up and running as defined in a `scenarios/build_and_deploy.yml` scenario file
_In the BCD controller container_:
```
bonita@bcd-controller:~$ cd bonita-continuous-delivery
bonita@bcd-controller:~/bonita-continuous-delivery$ ls -nh bonita-vacation-management-example/target
total 8,1M
drwxr-xr-x 9 1000 1000 4,0K Mar 29 16:29 bonita-vacation-management-example
-rw-r--r-- 1 1000 1000 8,1M Mar 29 16:29 bonita-vacation-management-example_20180329162901.zip
drwxr-xr-x 3 1000 1000 4,0K Mar 29 16:29 bpmn
drwxr-xr-x 2 1000 1000 4,0K Mar 29 16:29 generated-jars
drwxr-xr-x 3 1000 1000 4,0K Mar 29 16:29 ui-designer
total 9,0M
drwxr-xr-x 9 1000 1000 4,0K Dec 6 13:59 bonita-vacation-management-example
-rw-r--r-- 1 1000 1000 2,4K Dec 6 13:59 bonita-vacation-management-example-Test-20181206125838.bconf
-rw-r--r-- 1 1000 1000 9,0M Dec 6 13:59 bonita-vacation-management-example-Test-20181206125838.zip
drwxr-xr-x 3 1000 1000 4,0K Dec 6 13:59 bpmn
drwxr-xr-x 3 1000 1000 4,0K Dec 6 13:58 configurations
drwxr-xr-x 2 1000 1000 4,0K Dec 6 13:58 generated-jars
drwxr-xr-x 3 1000 1000 4,0K Dec 6 13:58 ui-designer
```
Then artifacts can be deployed using the generated zip file as follows:
Then artifacts can be deployed as follows:
```
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/euwest1_performance.yml --yes livingapp deploy -p bonita-vacation-management-example/target/bonita-vacation-management-example_20180329162901.zip
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/build_and_deploy.yml --yes livingapp deploy \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Test-20181206125838.zip \
-c bonita-vacation-management-example/target/bonita-vacation-management-example-Test-20181206125838.bconf
```
Artifacts can also be deployed providing the Application Archive directory as follows:
Artifacts can also be deployed providing the Application Archive directory and without configuration as follows:
```
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/euwest1_performance.yml --yes livingapp deploy -p bonita-vacation-management-example/target/bonita-vacation-management-example
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/build_and_deploy.yml --yes livingapp deploy \
-p bonita-vacation-management-example/target/bonita-vacation-management-example
```
......@@ -12,8 +12,8 @@ Here is an example of a build result:
```
bonita-vacation-management-example
├── target
   └── bonita-vacation-management-example-Qualification-20181003140237.zip
   └── bonita-vacation-management-example-Qualification-20181003140237.bconf
   └── bonita-vacation-management-example-Test-20181003140237.zip
   └── bonita-vacation-management-example-Test-20181003140237.bconf
```
It's possible to extract the configuration to check it and also override (merge) some parameters if needed.
......@@ -23,9 +23,9 @@ It's possible to extract the configuration to check it and also override (merge)
You can extract the configuration if you want to check it or modify it
```bash
bcd -y -s scenarios/euwest1_performance.yml livingapp extract-conf \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Qualification-20181003140237.bconf \
-o scenarios/euwest1_performance_Qualification.yml
bcd -s scenarios/build_and_deploy.yml -y livingapp extract-conf \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Test-20181003140237.bconf \
-o scenarios/build_and_deploy_Test.yml
```
The configuration looks like this :
......@@ -46,7 +46,7 @@ processes:
As it may contain sensitive data, it's recommended to encrypt your configuration using [vault](how_to_use_bcd_with_data_encrypted):
```
ansible-vault encrypt scenarios/euwest1_performance_Qualification.yml
ansible-vault encrypt scenarios/build_and_deploy_Test.yml
New Vault password:
Confirm New Vault password:
Encryption successful
......@@ -55,9 +55,9 @@ Encryption successful
You can also just check if there are parameters that have no value for this environment:
```bash
bcd -y -s scenarios/euwest1_performance.yml livingapp extract-conf --without-value \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Qualification-20181003140237.bconf \
-o scenarios/euwest1_performance_Qualification_missing_parameters.yml
bcd -s scenarios/build_and_deploy.yml -y livingapp extract-conf --without-value \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Test-20181003140237.bconf \
-o scenarios/build_and_deploy_Test_missing_parameters.yml
```
Notes :
......@@ -69,10 +69,10 @@ Notes :
You may want to complete or override some parameter values coming from your Living App repository, to do that you can modify the output file of the __extract-conf__ command and ***merge*** with your ***bconf*** file.
```bash
bcd -y -s scenarios/euwest1_performance.yml livingapp merge-conf \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Qualification-20181003140237.bconf \
-i scenarios/euwest1_performance_Qualification.yml \
-o /tmp/bonita-vacation-management-example-Qualification-20181003140237-modified.bconf
bcd -s scenarios/build_and_deploy.yml -y livingapp merge-conf \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Test-20181003140237.bconf \
-i scenarios/build_and_deploy_Test.yml \
-o /tmp/bonita-vacation-management-example-Test-20181003140237-modified.bconf
```
Note : the content of bconf file is not encrypted so it's recommended to clean them after usage.
......
......@@ -27,7 +27,7 @@ To do so, first you need to identify the target server where the Bonita containe
It's possible through the `bcd stack status` command:
```
bcd -y -s scenarios/myscenario.yml stack status
bcd -s scenarios/myscenario.yml -y stack status
[...]
[10:44:12.802] TASK [List Docker containers.] **************************************************************************************************
......@@ -38,7 +38,7 @@ FQDN: ec2-54-191-90-85.us-west-2.compute.amazonaws.com
Docker running containers
--
CONTAINER ID IMAGE CREATED STATUS NAMES
5d73a2446245 bonitasoft/bonita-subscription:7.6.2 6 minutes ago Up 6 minutes bonita8081
5d73a2446245 bonitasoft/bonita-subscription:7.8.0 6 minutes ago Up 6 minutes bonita8081
[...]
```
......@@ -55,7 +55,7 @@ docker logs bonita8081
If you want to copy all the logs (bonita, catalina) you can use `docker cp`:
```
docker cp bonita8081:/opt/bonita/BonitaSubscription-7.6.2-Tomcat-8.5.23/server/logs/ /tmp/
docker cp bonita8081:/opt/bonita/BonitaSubscription-7.8.0-Tomcat-8.5.34/server/logs/ /tmp/
```
Then you will be able to retrieve all the files through a `scp`:
......@@ -68,7 +68,7 @@ scp -i ~/.ssh/my_key.pem ubuntu@54.191.90.85:/tmp/logs /tmp/
Ansible facts are local variables registered in hosts. It is possible to save them in JSON files with the `setup` command.
```
$ cd bonita-continuous-delivery
$ bcd -y -s scenarios/myscenario.yml stack create deploy
$ bcd -s scenarios/myscenario.yml -y stack create deploy
$ ansible all -vv -i ansible/inventory/ec2/ec2_wrapper.sh -m setup -u ubuntu --private-key=~/.ssh/my_key.pem --tree tmp_facts/
```
This command will identify every EC2 instance (depending of `bcd_stack_id` set into ec2.ini by the last `bcd stack deploy` command) and put its facts into the `tmp_facts` directory.
......
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