About provisioning

Jahia’s provisioning mechanism facilitates Jahia orchestration, focusing on the steps required for a Jahia environment to autonomously reach a production-ready state. The mechanism can instruct Jahia to install modules, import sites, execute Karaf commands, and more, by means of a script or manifest.

The provisioning script handles all the heavy lifting, from triggering the start of Jahia all the way to Jahia being fully available in production, and can be further configured through Jahia’s GraphQL API.

About the provisioning script

Written in either JSON or YAML, the provisioning script is a sequential list of steps executed either during Jahia startup or once added to Jahia. Steps are executed according to their order in the provisioning script. 

Example of a YAML script:

- installOrUpgradeBundle: "mvn:org.jahia.modules/article/3.0.0" 
  autoStart: true
- installOrUpgradeBundle: "mvn:org.jahia.modules/bookmarks/3.0.0"

Example of a JSON script:

[
  {
    "installAndStartBundle": "mvn:org.jahia.modules/article/3.0.0", 
    "autoStart": true
  },
  {
    "installAndStartBundle": "mvn:org.jahia.modules/bookmarks/3.0.0"
  }
]

Variable interpolation

You can add variables the script to handle elements such as environment variables, credentials, and more. Add variables using this format: ${type:key:-default} .

Based on Apache StringSubstitutor, these interpolations allow dynamic migration scripts to be used.

Name	Variable (example)	Description
Base64 Decoder	${base64Decoder:SGVsbG9Xb3JsZCE=}	Decodes the provided string
Base64 Encoder	${base64Encoder:HelloWorld!}	Encodes the provided string
Java Constant	${const:java.awt.event.KeyEvent.VK_ESCAPE}	Accesses a Java constant
Date	${date:yyyy-MM-dd}	Converts to the current date using the provided format
DNS	${dns:address|apache.org}	Returns the IP address corresponding to a host name of DNS name
Environment Variable	${env:USERNAME}	Accesses an environment variable
File Content	${file:UTF-8:src/test/resources/document.properties}	Returns the content from a file
Java	${java:version}	Returns the current Java version
Localhost	${localhost:canonical-name}	Converts a canonical name to a host name
Properties File	${properties:src/test/resources/document.properties::mykey}	Returns the value of mykey at the path src/test/resources/document.properties
Resource Bundle	${resourceBundle:org.example.testResourceBundleLookup:mykey}	Returns the value of mykey at the path org.example.testResourceBundleLookup
Script	${script:javascript:3 + 4}	Executes a script
System Property	${sys:user.dir}	Returns a system property
URL Decoder	${urlDecoder:Hello%20World%21}	Returns a decoded URL
URL Encoder	${urlEncoder:Hello World!}	Returns an encoded URL
URL Content (HTTP)	${url:UTF-8:http://www.apache.org}	Returns the content at a remote URL
URL Content (HTTPS)	${url:UTF-8:https://www.apache.org}	Returns the content at a remote URL
URL Content (File)	${url:UTF-8:file:///${sys:user.dir}/src/test/resources/document.properties}	Returns the content of a file
XML XPath	${xml:src/test/resources/document.xml:/root/path/to/node}	Returns the content of an XML node

 

In addition to Apache StringSubstitutor, you can use the following Jahia interpolation:

Name	Variable (example)	Description
Jahia properties	${jahia:processingServer}	Accesses a specific property

About execution of files by Jahia

As you're building your scripts, it is important to understand that provisioning scripts are executed by Jahia. For example, you must place all static assets (such as modules and sites) defined in the provisioning script in a location available to the Jahia instance that runs the script. The same applies to environment variables. The provisioning script can only access environment variables known by the Jahia instance running the script.

However, you can use Karaf shell commands with tools such as curl or Git to fetch data located outside of the instance's filesystem, for example, to download a file that is later used by the provisioning script.

Script chaining and composition

Provisioning scripts can be chained (a script can call another script). This includes calling a script located in a remote location. For example, the provisioning scripts below are valid. This script executes a script located on a remote server.

- include: "http://myserver.com/install-augmented-search.yaml"

Remember that if this script contains environment variables (such as variables referring to credentials), they must be known by the Jahia instance executing the script.

Script chaining enables you to use and reuse multiple scripts in multiple locations. You could even use chaining to make scripts available on public locations (even stored as a GitHub repository) as variable interpolation removes the need for including security credentials in scripts.

A script can also be located somewhere on Jahia's filesystem:

- include: "file:/users/johndoe/install-augmented-search.yaml"

Finally, include is a supported commands that you can use to compose more advanced provisioning scripts, for example:

- installOrUpgradeBundle: 
  - "mvn:org.jahia.modules/article/3.0.0" 
  - "mvn:org.jahia.modules/bookmarks/3.0.0"
  autoStart: true
- include: "http://myserver.com/install-augmented-search.yaml"
- include: "http://myserver.com/install-forms.yaml"

Conditional commands

Based on Jahia properties, simple boolean conditions are supported in the script using the following syntax:

- if: "cluster.activated"
  do: 
    - installFeature: "dx-clustering"

Executing a script

Three methods are available to trigger the execution of a script: directly through the filesystem, or through an API call or environment variable (Docker only).

Filesystem

Provisioning scripts are executed by Jahia as soon as they are saved in the [JAHIA_DATA_FOLDER]/patches/provisioning/folder, where [JAHIA_DATA_FOLDER] is the folder corresponding to your system. Docker images use /var/jahia. Once a script is executed, it is automatically renamed with its execution status, either .success or .failed.

API

You can send a provisioning script through a REST API available at /modules/api/provisioning.

For example:

curl --request POST \
  --url http://localhost:8080/modules/api/provisioning \
  --header 'Authorization: Basic cm9vdDpyb290' \
  --header 'Content-Type: application/yaml' \
  --data '- installOrUpgradeBundle: "mvn:org.jahia.modules/article/3.0.0" 
  autoStart: true'

To use the provisioning API, you require the systemTools privileges. The example above contains default root/root credentials (encoded in the Authorization header).

Note that the API is synchronous and will only respond once the script has been fully executed or has failed. If your API client is configured with a timeout, make sure that the timeout allows sufficient time for the script to run in its entirety.

Environment variable (Docker)

If you're using Jahia with Docker, you can also pass an EXECUTE_PROVISIONING_SCRIPT environment variable to automatically execute a provisioning script at startup.

docker run -e EXECUTE_PROVISIONING_SCRIPT="file:/users/johndoe/install-augmented-search.yaml" -p 8080:8080 jahia/jahia-ee:8.0.3.0