Unverified Commit 2b0ea7ee authored by JeremJR's avatar JeremJR Committed by GitHub

Merge pull request #49 from bonitasoft/feat/BS-18284_include_doc_deployer_in_doc_bcd_Patch1

add deployer doc (BS-18284)
parents a89595c1 c46a47cb
# IntelliJ
.idea/
*.iml
# How to build a Living Application repository
# How to build a Living App repository
This tutorial describes how to build a Bonita Living Application repository from the command line using BCD.
::: info
A Bonita repository contains the artifacts developed in Bonita Studio and the UI Designer. Its content is further described in [Bonita's Workspaces and repositories documentation](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/workspaces-and-repositories) page.
A Living Application repository (or **Living App repository**) contains the artifacts developed in Bonita Studio and the UI Designer. Its content is further described in [Bonita's Workspaces and repositories documentation](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/workspaces-and-repositories) page.
:::
The repository build process allows to generate Bonita deployable artifacts (for instance process `.bar` files, UI Designer pages `.zip` files, REST API extensions `.zip` files).
......@@ -13,9 +13,9 @@ The repository build process allows to generate Bonita deployable artifacts (for
### 1. Prepare the repository
A Bonita repository can be created using Bonita Studio and it can be [shared with Git or SVN](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/workspaces-and-repositories#toc5).
A Living App repository can be created using Bonita Studio and it can be [shared with Git or SVN](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/workspaces-and-repositories#toc5).
So first ensure you have your Bonita repository available on your filesystem.
So first ensure you have your Living App repository available on your filesystem.
For this tutorial, we will use the [Bonita Vacation Management example repository](https://github.com/bonitasoft/bonita-vacation-management-example) publicly available on GitHub.
```
......@@ -23,7 +23,7 @@ $ cd bonita-continuous-delivery
$ git clone https://github.com/bonitasoft/bonita-vacation-management-example
```
This step creates a `bonita-continuous-delivery/bonita-vacation-management-example` directory which is the Living Application 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.
### 2. Provide the repository's build dependencies
......@@ -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
......
# 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.
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.
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
## 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.
### One repository per project
A Bonita repository should only contain artifacts related to a given 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.
**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
This is the simplest use case: you want to build a Bonita repository and deploy all associated resources.
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
```
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 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
- **Update** the application archive created by the builder
- **Deploy** the updated application archive
First, we build the Bonita repository:
```
bcd -y -s <path/to/scenario> livingapp build -p <path/to/bonita/repository>
```
The build operation creates a **target** directory in the Bonita repository. Let's move to this directory:
```
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
```
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
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 applications
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
```
#### 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.
## Build and select how to deploy parts of the Application Archive
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.
::: 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
# How to deploy Living App artifacts
This tutorial describes how to deploy Bonita Living Application artifacts from the command line using BCD.
## How it works
This section provides detailed information of Bonita artifacts deployment with BCD.
### Deployment concepts
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
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 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 Application Archive structure:
```
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 must be a valid JSON file named **`deploy.json`** and it must be located at the root of the Application Archive.
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": "organizations/ACME.xml",
"policy": "MERGE_DUPLICATES"
},
"profiles": [
{
"file": "profiles/default_profile.xml",
"policy": "REPLACE_DUPLICATES"
},
{
"file": "profiles/custom_profile.xml",
"policy": "REPLACE_DUPLICATES"
}
],
"processes": [
{
"file": "processes/New Vacation Request--1.4.1.bar",
"policy": "IGNORE_DUPLICATES"
},
{
"file": "processes/Initiate Vacation Available--1.4.1.bar"
}
],
"restAPIExtensions": [
{
"file": "extensions/tahitiRestApiExtension-1.0.0.zip",
}
],
"pages": [
{
"file": "pages/page_ExampleVacationManagement.zip"
}
],
"layouts": [
{
"file": "layouts/customLayout1.zip"
},
{
"file": "layouts/customLayout2.zip"
}
],
"themes": [
{
"file": "themes/customTheme1.zip"
},
{
"file": "themes/customTheme2.zip"
}
],
"applications": [
{
"file": "applications/Application_Data.xml",
"policy": "REPLACE_DUPLICATES"
}
],
"businessDataModel": {
"file": "bdm/bdm.zip"
},
"bdmAccessControl": {
"file": "bdm/bdm-access-control.xml"
}
}
```
### Supported Policies
<div id="supported-policies">
* Applications:
* `FAIL_ON_DUPLICATES`: deployment fails if the `Application` or `ApplicationPage` already exists
* `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`: **(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 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
* 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.md) with BCD.
## How to use
Use the `bcd livingapp deploy` command to deploy Living App artifacts:
```
bcd -s <scenario> livingapp deploy -p <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).
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:**
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
```
......@@ -20,7 +20,7 @@ If you consider deploying to Amazon Web Services (AWS) platform, first read the
### Step-by-step installation
In order to ease your environment setup, we provide a Docker image (_BCD Controller_ image) which contains all required dependencies and tools for the control workstation (ie. the host from which Bonita Continuous Delivery commands are launched).
In order to ease your environment setup, we provide a Docker image called **[BCD Controller](bcd_controller.md)** image which contains all required dependencies and tools for the control workstation (ie. the host from which Bonita Continuous Delivery commands are launched).
Follow these installation steps on your control workstation.
......@@ -141,7 +141,7 @@ Commands:
```
::: info
Read the [BCD Command-line interface](bcd_cli.md) page for further information about the BCD CLI usage.
Read the **[BCD Command-line interface](bcd_cli.md)** page for further information about the BCD CLI usage.
:::
### Scenarios
......@@ -151,5 +151,5 @@ BCD requires a YAML configuration file called **Scenario** which describes your
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.
::: info
Read the [BCD Scenario reference](scenarios.md) page for a comprehensive description of scenario variables.
Read the **[BCD Scenario reference](scenarios.md)** page for a comprehensive description of scenario variables.
:::
* [Quick start](quickstart.md)
* [Release notes](release_notes.md)
* [Quick start guide](quickstart.md)
* [BCD services and scenarios](_bcd_services_and_scenarios.md)
* [Controller Docker image](bcd_controller.md)
* [Command-line interface](bcd_cli.md)
* [Scenario file reference](scenarios.md)
* [Howtos](_howtos.md)
* [Configure Amazon Web Services (AWS) for BCD](aws_prerequisites.md)
* [Configure AWS single sign-on](aws_sso.md)
* [Build a Living Application repository](livingapp_build.md)
* [Manage Bonita stacks](_manage_stack.md)
* [Configure Amazon Web Services (AWS) for BCD](aws_prerequisites.md)
* [Configure AWS single sign-on](aws_sso.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)
* [Enabling remote monitoring with JMX](how_to_enable_remote_monitoring_jmx.md)
* [Manage Bonita Living Applications](_manage_living_application.md)
* [Build a Living App repository](livingapp_build.md)
* [Deploy Living App artifacts](livingapp_deploy.md)
* [Build and deploy (Best Practices)](livingapp_build_and_deploy.md)
* [Integrate BCD with Jenkins](jenkins_example.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)
* [Enabling remote monitoring with JMX](how_to_enable_remote_monitoring_jmx.md)
* [Controller Docker image](bcd_controller.md)
* [Command-line interface](bcd_cli.md)
* [Scenario reference](scenarios.md)
* [Troubleshooting guide](troubleshooting_guide.md)
{
"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