Provisioning commands

October 8, 2024

This section of the documentation lists all provisioning commands available with Jahia. This content, as well as some more advanced parameters, is also available in our GitHub repository.

Managing modules

Installing a module

This command installs a module, also called an OSGI bundle, by providing a PAX-url. These options are available:

  • target
    The cluster group name where the operation will be performed (unset to execute on all nodes), or local to perform operation on a node individually using standard non-clustered module deployment
  • autoStart
    Autostarts the bundle after installation (at the end of the script execution)
  • uninstallPreviousVersion
    Uninstalls all other versions (at the end of the script execution).
  • forceUpdate
    If true, updates the module if it is already installed. The default is false.
  • if
    Optional condition that must be met to perform the operation

Example:

- installBundle: "mvn:org.jahia.modules/article/3.0.0"
  autoStart: true
  uninstallPreviousVersion: true

or:

- installBundle: "file:/tmp/example-1.0.0.jar"

Multiple bundles can be installed with the same command and options:

- installBundle:
  - 'mvn:org.jahia.modules/forms-snippets-extension/3.0.0'
  - 'mvn:org.jahia.modules/forms-nocss-theme/2.0.0'
  - 'mvn:org.jahia.modules/font-awesome/6.0.0'
  - 'mvn:org.jahia.modules/forms-prefill/2.0.0'
  - 'mvn:org.jahia.modules/forms-core/3.2.0'  
  autoStart: true
  uninstallPreviousVersion: true

The autoStart option starts all listed bundles once they have all been installed. Then previous versions will be uninstalled.

Conditional installation

You can add a condition on install by adding the if option. 

- installBundle: 'mvn:org.jahia.modules/sdl-generator-tools/2.1.0'
  if: "'${jahia:operatingMode}' == 'development'"

Additional commands

As an alternate to autoStart: true, you can use installAndStartBundle:

- installAndStartBundle: "file:/tmp/example-1.0.0.jar"

The  installOrUpgradeBundle additional command is also available for upgrades. The behavior changes for new installs and upgrades:

  • If no version of this bundle is installed, it behaves like installAndStartBundle.
  • If another version of the bundle is installed, this installs the new version, uninstalls the previous ones (as with uninstallPreviousVersion), and restores the state of the previous version (started or stopped)
- installOrUpgradeBundle: "mvn:org.jahia.modules/article/3.0.0"

Adding a Maven repository

Add a Maven repository to allow modules to be installed from that repository. The repository will be available when using mvn:// URL.

- addMavenRepository: "https://devtools.jahia.com/nexus/content/groups/enterprise@id=jahia-enterprisee@snapshots"

Or if that repository requires authentication:

- addMavenRepository: "https://devtools.jahia.com/nexus/content/groups/enterprise@id=jahia-enterprise@snapshots"
  username: "USERNAME"
  password: "PASSWORD"

Enabling a module on a site

You can enable a module on a specific site. For example:

- enable: "news"
  site: "digitall"

Installing a package

All packages based on jahia-packages-parent from 8.0.3.0 have an associated provisioning script that is generated when building. You can install a package by just referencing its script. For example:

- include: "mvn:org.jahia.packages/forms-package/3.2.1/yaml/provisioning"

Uninstalling a bundle

You can uninstall a bundle using a key composed of the symbolic name and version (optional): <symbolic-name>[/<version>]. This additional option is available:

  • target
    The cluster group name where the operation is performed (unset to execute on all nodes), or local to perform operation on a node individually using standard non-clustered module deployment

Example:

- uninstallBundle: "article/3.0.0"

Managing configurations

Installing a configuration

Install a configuration by providing a link to the file.

Example:

- installConfiguration: "file:/tmp/org.jahia.services.usermanager.ldap-config-rqa5.cfg"

Editing a configuration

You can create or edit configurations by using editConfiguration with the configuration PID. If the PID is a factory PID, you must specify the configIdentifier value or use the  <factory-pid>-<config-Id>  syntax. For example:

- editConfiguration: "org.jahia.modules.jexperience.settings"
  configIdentifier: "global"
  properties: 
    jexperience.jCustomerURL: "https://jcustomer:9443"
    jexperience.jCustomerUsername: "karaf"
    jexperience.jCustomerPassword: "karaf"
    jexperience.jCustomerTrustAllCertificates: "true"
    jexperience.jCustomerUsePublicAddressesForAdmin: "false"
    jexperience.jCustomerKey: "670c26d1cc413346c3b2fd9ce65dab41"

You can also put the content of the properties file in the script (the formatting will be maintained for config creation only) :

- editConfiguration: "org.jahia.modules.test"
  configIdentifier: "id1"
  content: |
    # LDAP configuration
    user.uid.search.name:dc=jahia,dc=com
    group.search.name:dc=jahia,dc=com
    url=ldap://rqa5.jahia.com:389/

Importing a zip file

You can import a zip that was previously exported from Jahia.

This additional option is available:

  • rootPath
    Specifies where the content will be imported. Leave this undefined to import in /.

Example:

- import: "file:/Users/toto/users.zip"

Importing a site

You can import a site that was previously exported from Jahia.

- importSite: "file:/Users/toto/mySite_export_2020-12-30-10-37/mySite.zip"
Important: Exporting a site from Jahia Administration generates a container zip archive containing multiple zip files. The container zip file cannot be imported directly through the provisioning API. To import a site previously exported from Jahia Administration, begin by extracting the container zip, and use the importSite command with the file called [sitekey].zip. The other zip files extracted from the container can be imported through the provisioning API using the import command.

Managing Karaf features 

Deployment of custom Karaf features inside Jahia is not supported. Use this section very carefully.

Installing a Karaf feature

You can install a Karaf feature.

Example:

- installFeature: "transaction-api"

Adding a feature repository

You can add a feature repository.

Example:

- addFeatureRepository: "mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features"

Uninstalling a Karaf feature

You can uninstall a Karaf feature.

Example:

- uninstallFeature: "webconsole"

Executing a script

You can execute a graphql or groovy script located either on the Jahia instance or remotely.

- executeScript: "http://myserver.com/a-graphql-query.graphql"
- executeScript: "file:/tmp/my-new-script.groovy"

Executing a Karaf command

You can perform a command which is not available as a dedicated operation. The command output will be displayed in the logs.

- karafCommand: "bundle:refresh news"
- karafCommand: "bundle:list"

You can specify an optional timeout in ms (default 1s):

- karafCommand: "shell:exec git clone https://github.com/Jahia/personal-api-tokens.git" 
  timeout: 10000

Sleep

You can tell the script to wait for a specific amount of time (in ms) before proceeding with the next instruction:

-sleep: 1000

Adding operations 

Add a new operation by extending the org.jahia.services.provisioning.Operation class and exposing it as an OSGi service.