Commit 8e37eb60 authored by Truc Nguyen's avatar Truc Nguyen

rework deploy documentation

parent 31686fe5
......@@ -50,6 +50,10 @@ $ bcd -s scenarios/euwest1_performance.yml --yes livingapp build -p bonita-vacat
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.
::: info
Refer to the [BCD Command-line reference](bcd_cli.md) for a complete list of available options for the `bcd livingapp build` command.
:::
## Complete example
......
# Build and deploy a Bonita living application
# How to build and deploy Living Apps (Best Practices)
Bonita Continuous Delivery allows 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 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 pratices 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 uses cases to let you easily build and deploy your Bonita Living Application repository.
All examples assume that
* you have clone the demo [Bonita Vacation Management example repository](https://github.com/bonitasoft/bonita-vacation-management-example)
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` folder
* 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
## Best practices about repositories
## Best practices about repositories
The _Bonita living application Builder_ is made to build an entire Bonita repository. It is usually pretty fast, but depending on the size of your repository, the amount of artifacts to build, it can become longer. To avoid such situations, there is some best practices about Bonita repositories that you should respect.
The _Bonita Living Application Builder_ is made to build an entire Bonita repository.
It is usually pretty fast, but depending on the size of your repository, the amount of artifacts to build, it can become longer. To avoid such situations, there is some best practices about Bonita repositories that you should respect.
### One repository per project
A Bonita repository should only contain artifacts related to a given project.
As example, if you want to use Bonita to build a _loan application_ and a _leave request application_, we strongly advise you to manage those two projects in two different repositories. It will allows you to build deploy and test each project separately easily using Bonita Continuous Delivery.
A repository should only contains the resources and the dependencies required to build and deploy the living applications of the project. Resources not used by the living applications should not be in the repository of the project.
For example, if you want to use Bonita to build a _loan application_ and a _leave request application_, we strongly advise you to manage those two projects in two different repositories. It will allow you to build, deploy and test each project separately easily using Bonita Continuous Delivery.
A repository should only contain the resources and the dependencies required to build and deploy the Living Applications of the project. Resources not used by the Living Applications should not be in the repository of the project.
### Use versioning to manage your history
During the life-cycle of a project, resources are brought to evolve. You may need to perform important changes on a process or on a Rest API extension for example. The best way to track the evolution is to use versioning.
Before to perform an important change on a resource, make sure to save the current state of your repository by creating a tag for example if you are using Git. Then you can increase the version of your resource and perform the change, knowing that you can easily do a rollback if needed.
The not recommended alternative would be to _duplicate_ the resource in your repository. If you start to manage your versions this way, your repository will getting bigger and bigger, and the time required by the _Bonita living application Builder_ to build your repository will increase. Moreover, it is really painful to work on a repository containing all the history of a project, it can lead to many confusions and errors during the development ( dependency issues ...).
The recommended way is definitively to keep the latest version of each resources in the working repository, and the history on your Version Control System.
Since the version 7.7.0, the popular Version Control System _Git_ is integrated in Bonita. It is a fine way to manage properly the versioning of your projects. The Bonita documentation provides an example on [how to share a repository on github](share-a-repository-on-github).
**We do not recommend** to _duplicate_ the resource in your repository. If you start to manage your versions this way, your repository will get bigger and bigger, and the time required by the _Bonita Living Application Builder_ to build your repository will increase. Moreover, it is really painful to work on a repository containing all the history of a project, it can lead to many confusions and errors during the development ( dependency issues ...).
**The recommended way** is definitively to keep the latest version of each resources in the working repository, and the history on your Version Control System.
Since the version 7.7.0 of Bonita, the popular Version Control System _Git_ is integrated in Bonita Studio. It is a fine way to manage properly the versioning of your projects. The Bonita documentation provides an example on [how to share a repository on GitHub](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/share-a-repository-on-github).
## Build and deploy straight
## Build and deploy straight
This is the simplest use case: you want to build a Bonita repository and deploy all associated resources.
......@@ -41,11 +45,14 @@ like in the following:
```
$ bcd -y -s <path/to/scenario> livingapp build -p <path/to/bonita/repository> deploy
```
This command will first build the Bonita repository. The output of the build is a zip file, located in a folder _target_ 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. In a second time, the deployer deploys all those resources on the running Bonita platform.
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.
In a second time, the deployer deploys all those resources on the running Bonita platform.
## Build and select what to deploy
Sometimes, you may need to perform some actions between the build and the deploy. You may want to deploy only a sub part of the repository that has been built, or add some external resources in the application archive to deploy. Here are some hints on how to do it.
Sometimes, you may need to perform some actions between the build phase and the deploy phase. You may want to deploy only a subpart of the repository that has been built, or add some external resources in the application archive to deploy. Here are some hints on how to do it.
The idea is always the same:
- **Build** a Bonita repository with BCD
......@@ -56,27 +63,28 @@ First, we build the Bonita repository:
```
bcd -y -s <path/to/scenario> livingapp build -p <path/to/bonita/repository>
```
The build operation has created a folder **'target'** in the Bonita repository, we move in this folder:
The build operation creates a **target** directory in the Bonita repository. Let's move to this directory:
```
cd <path/to/bonita/repository>/target
```
This folder contains some stuff and a zip file, the raw application archive we want to update. Keep in mind that an application archive can be a zip file or a folder. So, we are going to unzip the raw application archive, in a folder _to-deploy_:
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
```
A new folder _to-deploy_ has been created, it contains all the built resources from your Bonita repository.
You can perform some actions on the content of this folder to customize your deployment. Here are some examples:
A new directory _to-deploy_ has been createda and it contains all the built artifacts from your Bonita repository.
You can perform some actions on the content of this directory to customize your deployment. Here are some use cases:
#### Example 1: I only want to deploy the Business Data Model from my Bonita repository
We only want to deploy the BDM in this example. The folder _to-deploy_ should contain a sub folder _bdm_. We simply need to consider this sub folder as the application archive, and ask the deployer to deploy it:
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
```
#### Example 2: I only want to deploy all the resources from my Bonita repository except the applications
#### Example 2: I only want to deploy all the resources from my Bonita repository except applications
The folder _to-deploy_ should contain a sub folder _applications_. We simply need to delete the sub folder, to consider the folder _to-deploy_ as the application archive and to ask the deployer to deploy it:
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
......
# How to deploy a Living Application
# How to deploy Living App artifacts
This tutorial describes how to deploy a Bonita Living Application from the command line using BCD.
This tutorial describes how to deploy Bonita Living Application artifacts from the command line using BCD.
## Concepts
## How it works
Prior to go to the `how to deploy` section, please read the following to understand the concepts used by the deployment
process.
This section provides detailed information of Bonita artifacts deployment with BCD.
### Introduction
Bonita living applications deployer (called `Deployer` in the following) is a tool allowing resources deployment to a running Bonita platform.
### Deployment concepts
It is able to deploy
* applications
* business data model
* business data model access controls
* layouts
* organizations
* pages
* processes
* profiles
* rest APi extensions
* themes
First, here are the **types of artifacts** that can be deployed:
* applications
* business data model
* business data model access controls
* layouts
* organizations
* pages
* processes
* profiles
* REST API extensions
* themes
Its entry point is called an `Application Archive` consisting of all artifacts that need to be deployed and an optional
file called `Deployment Descriptor`.
### Important notice
Prior deploying a Business Data Model, the Deployer put the Tenant in the `paused` state. It then restarts it after
deployment of the BDM. So a downtime of the related Bonita Tenant occurs in this case.
Keep in mind that the `Deployer` does not deploy Rest API extensions authorization, you have to do it manually. See the page [how to configure Rest API authorization](how_to_configure_rest_api_authorization).
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.
### Application Archive structure
The `Application Archive` is a folder or a zip containing
* all artifacts that need to be deployed
* a file, called `Deployment Descriptor`, describing
* the type of the artifacts
* the path to the artifacts in the archive
* the way, called `Policy`, the artifacts will be deployed
The `Deployment Descriptor` is optional. If it is not provided, the `Deployer` first tries to generate it using the
following rules:
* the `Deployer` initializes a `Deployment Descriptor` empty instance in memory
* the `Application Archive` is a unzipped or copied in a temporary folder
* the `Deployer` lists all files in the folder
* for each file, it tries to guess the type of the resource. If it is a supported one, the `Deployer` adds it as a reference
in the descriptor and sets it a [default policy](#default-policies)
* finally, a `Deployment Descriptor` instance is associated to the `Application Archive` and used during subsequent processing
**Note**: if you provide several files related to a resource which is supposed to be single (for instance Business Data Model,
Organization), only one of the resources will be referenced. There is no guaranty about which file is kept so please avoid
this situation to ensure deployment reproducibility.
The Application Archive can be a directory or a zip file. It may contain a Deployment Descriptor in the form of a `deploy.json` file. If not provided, then a Deployment Descriptor is generated in-memory using the following rules:
* the type of artifact is determined from the nature of each file
* a [default policy](#supported-policies) is applied for each supported artifact to deploy
Here is an example of the `Application Archive` structure:
Here is an example of Application Archive structure:
```
parentFolder
-app
-Application_Data.xml
-page-myDashboard.zip
-myResourceRestAPI-1.0.0-SNAPSHOT.zip
-organization
-ACME.xml
-Profile_Data.xml
deploy.json
bonita-vacation-management-example
├── applications
│   └── Application_Data.xml
├── bdm
│   └── bdm.zip
├── deploy.json
├── extensions
│   └── tahitiRestApiExtension-1.0.0.zip
├── organizations
│   └── ACME.xml
├── pages
│   └── page_ExampleVacationManagement.zip
├── processes
│   ├── Cancel Vacation Request--1.4.1.bar
│   ├── Initiate Vacation Available--1.4.1.bar
│   ├── Modify Pending Vacation Request--1.4.1.bar
│   ├── New Vacation Request--1.4.1.bar
│   └── Remove All Business Data--1.4.1.bar
└── profiles
└── default_profile.xml
```
::: warning
**Note**: if you provide several artifacts for a resource which is supposed to be single (for instance Business Data Model, Organization), only one of the artifacts will be deployed. There is no guaranty about which file is kept so please avoid this situation to ensure deployment reproducibility.
:::
### Deployment Descriptor file
The `Deployment Descriptor` file should
* Be a valid json file named `deploy.json` located at the root of the Application Archive
* Have the following attributes
* an object for each resource types to be deployed
* each resource is described by attributes
* `file`: the relative path of the resource in the Application Archive
* `policy`: the way the deployment of the resource is performed. This allows the `Deployer` to decide how to behave in case of the resource is already present in the targeted Bonita platform
The Deployment Descriptor file must be a valid JSON file named **`deploy.json`** and it must be located at the root of the Application Archive.
Example of `Deployment Descriptor` file
Each artifact to deploy must be defined with the following attributes:
* `file`: (Mandatory) the relative path to the artifact in the Application Archive
* `policy`: (Optional) the name of the policy to apply in case the same artifact is already present in the target Bonita platform. If omitted, then the [default policy](#supported-policies) of the artifact's type will be applied.
**Example of Deployment Descriptor file**
```json
{
"organization": {
"file": "relative/path/to/organisationDescriptor.xml",
"file": "organizations/ACME.xml",
"policy": "MERGE_DUPLICATES"
},
"profiles": [
{
"file": "relative/path/to/profilesDescriptor1.xml",
"file": "profiles/default_profile.xml",
"policy": "REPLACE_DUPLICATES"
},
{
"file": "relative/path/to/profilesDescriptor2.xml",
"file": "profiles/custom_profile.xml",
"policy": "REPLACE_DUPLICATES"
}
],
"processes": [
{
"file": "processes/New-Vacation-Request--1.0.bar",
"file": "processes/New Vacation Request--1.4.1.bar",
"policy": "IGNORE_DUPLICATES"
},
{
"file": "processes/Initiate-Vacation-Available--1.0.bar"
"file": "processes/Initiate Vacation Available--1.4.1.bar"
}
],
"restAPIExtensions": [
{
"file": "relative/path/to/restAPIExtension1.zip",
},
{
"file": "relative/path/to/restAPIExtension2.zip"
"file": "extensions/tahitiRestApiExtension-1.0.0.zip",
}
],
"pages": [
{
"file": "relative/path/to/customPage1.zip"
},
{
"file": "relative/path/to/customPage2.zip"
"file": "pages/page_ExampleVacationManagement.zip"
}
],
"layouts": [
{
"file": "relative/path/to/customLayout1.zip"
"file": "layouts/customLayout1.zip"
},
{
"file": "relative/path/to/customLayout2.zip"
"file": "layouts/customLayout2.zip"
}
],
"themes": [
{
"file": "relative/path/to/customTheme1.zip"
"file": "themes/customTheme1.zip"
},
{
"file": "relative/path/to/customTheme2.zip"
"file": "themes/customTheme2.zip"
}
],
"applications": [
{
"file": "relative/path/to/applicationDescriptor1.xml",
"policy": "REPLACE_DUPLICATES"
},
{
"file": "relative/path/to/applicationDescriptor2.xml",
"file": "applications/Application_Data.xml",
"policy": "REPLACE_DUPLICATES"
}
],
......@@ -158,59 +134,87 @@ Example of `Deployment Descriptor` file
}
```
#### Supported Policies
### Supported Policies
<div id="supported-policies">
* Applications:
* `FAIL_ON_DUPLICATES`: deployment fails if the `Application` or `ApplicationPage` already exists
* `REPLACE_DUPLICATES`: if the `Application` or `ApplicationPage` already exists, the deployer deletes the existing one
and deploys the new one
* `REPLACE_DUPLICATES`: **(default)** if the `Application` or `ApplicationPage` already exists, the existing one is deleted and the new one is deployed
* Organization:
* `FAIL_ON_DUPLICATES`: if an item already exists, the deployment fails and is reverted to the previous state
* `IGNORE_DUPLICATES`: existing items are kept
* `MERGE_DUPLICATES`: existing items in the current organization are updated to have the values of the item in the
imported organization
* `MERGE_DUPLICATES`: **(default)** existing items in the current organization are updated to have the values of the item in the imported organization
* Processes:
* `FAIL_ON_DUPLICATES`: if the process already exists (same `name` and `version`), the deployment fails.
* `IGNORE_DUPLICATES`: only deploys a process when it does not already exists (same `name` and `version`)
* `REPLACE_DUPLICATES`: if the process already exists (same `name` and `version`), the deployer deletes the existing one
and deploys the new one. As a reminder, deleting a process means: disable it, delete it and all related cases
* Profiles: `REPLACE_DUPLICATES` (In case of conflict on the name, it replaces completely the profile including profile
entries and profile mappings)
#### Default Policies
* Applications: `REPLACE_DUPLICATES`
* Organization: `MERGE_DUPLICATES`
* Processes: `REPLACE_DUPLICATES`
* Profiles: `REPLACE_DUPLICATES`
#### Implicit Policies:
The following artifacts are used with **implicit** policies, it means that you do not have to declare those policies in
the deployment descriptor file. There is no other policies available for those artifacts.
* Rest API extensions: `REPLACE_DUPLICATES`
* `FAIL_ON_DUPLICATES`: if the process already exists (same `name` and `version`), the deployment fails
* `IGNORE_DUPLICATES`: only deploys a process when it does not already exist (same `name` and `version`)
* `REPLACE_DUPLICATES`: **(default)** if the process already exists (same `name` and `version`), the existing one is deleted and the new one is deployed. As a reminder, deleting a process means: disable the process, delete all related cases and delete the process
* Profiles:
* `REPLACE_DUPLICATES`: **(default)** in case of conflict with the profile's name, the existing profile (including profile entries and profile mappings) is completely deleted and the new one is deployed
The following artifacts are used with **implicit policies**. It means that you do not have to declare those policies in the Deployment Descriptor file. There is no other policy available for those artifacts.
* REST API extensions: `REPLACE_DUPLICATES`
* Pages: `REPLACE_DUPLICATES`
* Layouts: `REPLACE_DUPLICATES`
* Themes: `REPLACE_DUPLICATES`
* Business Data Model: `REPLACE_DUPLICATES`
* BDM access control: `REPLACE_DUPLICATES`
</div>
### Caveats
## Usage
* Prior to deploying a Business Data Model, [the Bonita tenant is paused](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/pause-and-resume-bpm-services). So a downtime of the tenant occurs. The tenant is resumed after the deployment of the BDM.
* REST API extension authorizations are not configured as part of the deployment process. They have to be configured while provisioning the Bonita platform. See [how to configure REST API authorization](how_to_configure_rest_api_authorization) with BCD.
The Bonita Continuous Delivery add-on allows you to deploy living applications artifacts using the Deployer, using the
following command:
## How to use
Use the `bcd livingapp deploy` command to deploy Living App artifacts:
```
bcd -s <scenario> --yes livingapp deploy -p <path>
bcd -s <scenario> livingapp deploy -p <path>
```
Where
* \<scenario>_ is the path to the scenario to be used. It allows to deploy to the running Bonita Stack using the tenant
credentials defined in this file
* _\<path>_ is the file path of the application archive to deploy.
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).
You can add a **--debug** option to enable debug mode and increase verbosity.
::: info
Refer to the [BCD Command-line reference](bcd_cli.md) for a complete list of available options for the `bcd livingapp deploy` command.
:::
**Complete example:**
You can add a _-\-debug_ extra option to enable the log debug mode.
You can refer to the [BCD command line documentation](bcd_cli.md) for a complete list of available options.
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
_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
```
Then artifacts can be deployed using the generated zip file as follows:
```
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/euwest1_performance.yml --yes livingapp deploy -p bonita-vacation-management-example_20180329162901.zip -e Qualification
```
Artifacts can also be deployed providing the Application Archive directory as follows:
```
bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/euwest1_performance.yml --yes livingapp deploy -p bonita-vacation-management-example -e Qualification
```
{
"varVersion": "2.0",
"bonitaDocVersion": "7.6"
"bonitaDocVersion": "7.7"
}
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