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

Merge pull request #21 from bonitasoft/BCD-172_custom-init-templating

feat(custom-init): document templating capabilities
parents bbaa37d7 7e5e6374
......@@ -6,7 +6,11 @@ This feature relies on the ability to extend the [Bonita Docker image](https://h
## 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.
Custom initialization files can be **static** or they can be **dynamic** while relying on runtime variables. Dynamic initialization files then leverage the [Jinja2 templating framework used by Ansible](http://docs.ansible.com/ansible/latest/playbooks_templating.html).
### Static initialization files
Static custom initialization files must be placed in BCD's `roles/bonita/files/custom-init.d` folder. All files from this folder will be uploaded to the target host regardless their extension. However only the files with a `.sh` extension will be executed.
Here's the directory layout for a `register-event-handler.sh` custom script:
```
......@@ -20,6 +24,21 @@ roles
│   │   │   └── register-event-handler.sh
```
### Dynamic initialization files
Dynamic custom initialization files must be placed in BCD's `roles/bonita/templates/custom-init.d` folder. All files with a `.j2` extension will be uploaded to the target host and stripped from the `.j2` suffix. However only the files with a `.sh.j2` extension will be executed.
Here's the directory layout for the provided `config-cluster.sh.j2` initialization script:
```
roles
├── bonita
│   └── templates
│   └── custom-init.d
│   ├── bonita-platform-sp-cluster-custom.properties.j2
│   ├── config-cluster.sh.j2
```
## 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).
......@@ -61,12 +80,17 @@ More precisely scripts are executed in the order returned by this command: `ls -
## Examples
### config-workers.sh
### 1. config-workers.sh
Ths `config-workers.sh` script is provided as part of BCD's core scripts.
The `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
### 2. config-cluster.sh.j2
The `config-cluster.sh.j2` script template is provided as part of BCD's core scripts.
In particular it shows how to conditionally configure a cluster deployment on AWS using BCD variables and [Jinja2 templating engine](http://docs.ansible.com/ansible/latest/playbooks_templating.html).
### 3. 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).
......@@ -77,7 +101,6 @@ Assuming the following files:
Here's a sample `register-event-handler.sh` script:
```bash
#!/bin/bash
......@@ -118,3 +141,73 @@ ${BONITA_SETUP_SH} push
# Create indicator file
touch ${indicator_path}
```
### 4. deploy-probe.sh
This sample script deploys [PSI Probe](https://github.com/psi-probe/psi-probe/wiki) (an _Advanced manager and monitor for Apache Tomcat_) along with Bonita in the Tomcat bundle.
In particular, it shows how to reference BCD variables in custom initialization files. All custom referenced variables can be defined at [BCD scenario](scenarios.md) level.
With this example, PSI Probe will be available at this URL: `http://<bonita_host>:8081/probe`. To connect to PSI Probe, use the credentials defined with the `custom_manager_username` and `custom_manager_password` variables. By default: `custom_manager_username=admin` and `custom_manager_password=t0psecret`.
#### deploy-probe.sh.j2
```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}
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
pushd ${BONITA_PATH}/Bonita*Subscription-${BONITA_VERSION}-Tomcat-${TOMCAT_VERSION}
# Allow Tomcat Manager from different host
cp ${script_dir}/manager-context.xml server/conf/Catalina/localhost/manager.xml
# PSI Probe
curl -sSL -o server/webapps/probe.war https://github.com/psi-probe/psi-probe/releases/download/{{ custom_psi_probe_version | default('3.0.0.RC2') }}/probe.war
cp ${script_dir}/tomcat-users.xml server/conf/tomcat-users.xml
# Create indicator file
touch ${indicator_path}
```
#### manager-context.xml.j2
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Context antiResourceLocking="false" privileged="true" >
<Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="{{ custom_manager_allow_pattern | default('^.*$') }}" />
<Manager sessionAttributeValueClassNameFilter="java\.lang\.(?:Boolean|Integer|Long|Number|String)|org\.apache\.catalina\.filters\.CsrfPreventionFilter\$LruCache(?:\$1)?|java\.util\.(?:Linked)?HashMap"/>
</Context>
```
#### tomcat-users.xml.j2
```xml
<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users xmlns="http://tomcat.apache.org/xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
version="1.0">
<role rolename="probeuser" />
<role rolename="poweruser" />
<role rolename="poweruserplus" />
<role rolename="manager-gui" />
<user username="{{ custom_manager_username | default('admin') }}" password="{{ custom_manager_password | default('t0psecret') }}" roles="manager-gui" />
</tomcat-users>
```
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