Creating a provisioning script

October 8, 2024

To help you understand how to use the provisioning API and build advanced provisioning scripts, try the tutorials that are accessible at https://github.com/Jahia/provisioning-tutorials. We recommend you go through these tutorials before continuing with the rest of this document, which provides additional recommendations.

Triggering execution of a script

When a provisioning script is submitted to Jahia, Jahia tries to execute it as soon as possible. If Jahia is booting up when the script is received, execution will begin once Jahia has started.

Multiple methods are available for you to trigger execution of the provisioning script. You can:

  • Place the provisioning script (YML file) in the [JAHIA_DATA]/patches/provisioning folder, which can be done through a volume bind or docker cp.
  • Use the EXECUTE_PROVISIONING_SCRIPT environment variable when starting a container.. This script can be either located remotely or placed within the container through a volume bind or docker cp.
  • Submit a script using the provisioning REST API.

Using artifacts

When designing the API, we paid particular attention to being able to handle provisioning use cases in situations where you wouldn't have direct filesystem or host access to Jahia. This means having Jahia in a remote location and only interacting with it through its public APIs. Although volume binding and docker cp are easy alternatives when working locally, they don't necessarily scale easily in complex containerized environments.

We also designed the API to be as flexible as possible, offering a diverse set of implementation paths for particular use cases.

The most concrete examples relate to accessing provisioning artifacts, such as GraphQL, Groovy scripts, and exported sites. Jahia must be able to access these artifacts to handle its own provisioning. 

Accessing remote resources individually

One of the easiest paths is simply to let Jahia access resources stored in a remote location (either on the Internet or on a local private network). As long as Jahia can resolve the path, it can execute the script. This method is used extensively in the tutorials that demonstrate the use of the provisioning API.

Although this technique is easy to comprehend, it may pose challenges when used with production resources. For example, you would want to ensure that these scripts can only be modified by authorized people.

Fetching resources in bulk

Since the provisioning API gives you access to tools packaged with Jahia through the karafCommand, you can use it to fetch resources through other means, for example, using scp, git, and more.

- karafCommand: "shell:exec git clone https://github.com/myAccount/jahia-provisioning-as.git"

Sending resources

The provisioning API's REST endpoint allows you to submit files and then used them in the submitted provisioning script.

curl -v -u root:root1234 \ 
  -X POST ${JAHIA_URL}/modules/api/provisioning \
  --form script="@my-manifest.yaml;type=text/yaml" \
  --form file="@createToken.groovy"

Using the above example, createToken.groovy can be referred to directly in the provisioning script.

- executeScript: "create-token.groovy"

Note that you can also install a module by submitting an inline provisioning script and the module archive (jar or tgz) in a single curl command: 

curl -v -u root:root1234 \
  -X POST ${JAHIA_URL}/modules/api/provisioning \
  --form script='[{"installAndStartBundle":"my-module.jar", "forceUpdate":true, "uninstallPreviousVersion": true}]' \
  --form file=@my-module.jar