Unverified Commit 4f49c44a authored by JeremJR's avatar JeremJR Committed by GitHub
Browse files

Merge pull request #16 from bonitasoft/BCD-97_custom-init.d

feat(custom-init): add tutorial for custom-init.d abilities (BCD-97)
parents f7f370b7 0f0a8eca
# Bonita Container Custom Initialization
The Bonita Docker container deployed by BCD can be further customized thanks to a custom initialization mechanism.
This feature relies on the ability to extend the [Bonita Docker image](https://hub.docker.com/_/bonita/) through custom `*.sh` shell scripts.
## Where should I put custom initialization scripts?
Custom initialization scripts must be placed in BCD's `roles/bonita/files/custom-init.d` folder. Each script to execute must have a `.sh` extension.
Here's the directory layout for a `register-event-handler.sh` custom script:
```
roles
├── bonita
│   ├── files
│   │   ├── custom-init.d
│   │   │   ├── bonita-tenant-sp-custom.xml
│   │   │   ├── config-workers.sh
│   │   │   ├── event-handler-example-1.0.0-SNAPSHOT.jar
│   │   │   └── register-event-handler.sh
```
## When are custom initialization scripts invoked?
Custom initialization scripts are invoked once the database has been initialized and the Tomcat server has been configured with [Bonita Platform setup tool](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/BonitaBPM_platform_setup).
Hence the Bonita Docker image startup sequence can be described as follows:
1. Initialize database: `setup.sh init`
1. Configure Tomcat server: `setup.sh configure`
1. Execute custom initialization `*.sh` scripts found in the container's `/opt/custom-init.d` folder
1. Start Tomcat server
::: info
**Warning**: all custom scripts are re-executed each time the Bonita Docker container is restarted.
If you want your script to be executed only once, you need to handle the conditional execution in your custom script itself.
For example:
```bash
#!/bin/bash
indicator_path=/opt/$(basename $BASH_ARGV)-executed
if [ -f ${indicator_path} ]; then
echo "Custom script already executed" && return 0
fi
#
# Do some interesting stuff
# [...]
# Create indicator file
touch ${indicator_path}
```
:::
## In which order are custom initialization scripts invoked?
Custom scripts are executed in natural sort order as implemented by the `ls` shell command. It is also referred as _natural sort of (version) numbers within text_.
More precisely scripts are executed in the order returned by this command: `ls -v /opt/custom-init.d/*.sh`.
## Examples
### config-workers.sh
Ths `config-workers.sh` script is provided as part of BCD's core scripts.
In particular it shows how to further configure the server using [Bonita Platform setup tool](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/BonitaBPM_platform_setup).
### register-event-handler.sh
This sample script deploys and registers a Bonita engine Event handler as described in [Event handlers Documentation](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/event-handlers).
Assuming the following files:
- `roles/bonita/files/custom-init.d/event-handler-example-1.0.0-SNAPSHOT.jar` (event handler JAR file)
- `roles/bonita/files/custom-init.d/bonita-tenant-sp-custom.xml` (tenant configuration file where the event handler is registered)
Here's a sample `register-event-handler.sh` script:
```bash
#!/bin/bash
set -euxo pipefail
indicator_path=/opt/$(basename $BASH_ARGV)-executed
if [ -f ${indicator_path} ]; then
echo "Custom script already executed" && return 0
fi
BONITA_PATH=${BONITA_PATH:-/opt/bonita}
BONITA_FILES=${BONITA_FILES:-/opt/files}
BONITA_SETUP_SH="${BONITA_PATH}/Bonita*Subscription-${BONITA_VERSION}-Tomcat-${TOMCAT_VERSION}/setup/setup.sh"
EVENT_HANDLER_FILENAME=event-handler-example-1.0.0-SNAPSHOT.jar
war_path=$(find "${BONITA_PATH}/Bonita"*"Subscription-${BONITA_VERSION}-Tomcat-${TOMCAT_VERSION}/server/webapps" -name bonita.war)
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
workdir="${BONITA_FILES}/register-event-handler"
rm -rf ${workdir} && mkdir -p ${workdir}
pushd ${workdir}
# copy event handler jar
mkdir -p WEB-INF/lib
cp ${script_dir}/${EVENT_HANDLER_FILENAME} WEB-INF/lib/
# repackage war
zip -r "${war_path}" "WEB-INF/lib/${EVENT_HANDLER_FILENAME}"
# register event handler
${BONITA_SETUP_SH} pull
cp /opt/custom-init.d/bonita-tenant-sp-custom.xml ${BONITA_PATH}/Bonita*Subscription-${BONITA_VERSION}-Tomcat-${TOMCAT_VERSION}/setup/platform_conf/current/tenant_template_engine/
${BONITA_SETUP_SH} push
# Create indicator file
touch ${indicator_path}
```
......@@ -41,7 +41,7 @@ If you have fulfilled all the prerequisites then you can follow the [Quickstart
## How to use
The classic usage at this very moment is:
The nominal usage of BCD can de described as the following workflow:
- (Optional) Amazon EC2 instance creation
- Bonita platform deployment in EC2 or on premises
- (Optional) Amazon EC2 instance deletion
......
......@@ -3,6 +3,7 @@
* [Amazon AWS prerequisites](aws_prerequisites.md)
* [Licensing prerequisites](licensing_prerequisites.md)
* [Quick start](quickstart.md)
* [Bonita container custom initialization](custom_init.md)
* [Scenario variables reference](scenarios.md)
* [Known issues](known_issues.md)
* [BCD Controller Docker image](_docker.md)
......
{
"varVersion": "1.0"
"varVersion": "1.0",
"bonitaDocVersion": "7.6"
}
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