New contrib extension repository - XWiki System Properties updater

Development
#1

Hi everyone,

I’d like to propose the creation of a new contrib extension, named “System Properties updater”.

Now … I’m not too sure about its naming, so don’t hesitate to propose something on your end. :slight_smile:

The goal of this extension is to allow :

  • the update of arbitrary XWiki object properties from system properties
  • the update of arbitrary XWiki attachments from system properties

By “system properties”, I’m referring to the Java system properties as (System Properties (The Java™ Tutorials > Essential Java Classes > The Platform Environment))

The use-case of this extension is to allow anyone to update XWiki configuration from command line arguments passed to the JVM. One could for example update a color of the current color theme through command-line arguments. In order to identify which object property or which attachment to update, the extension would rely on the serialized form of object property references or attachment references, as such :

  • property:xwiki:FlamingoThemes.Iceberg^FlamingoThemesCode.ThemeClass.link-color=green → This would update the property link-color of the Iceberg theme to green
  • attachment:xwiki:FlamingoThemes.Iceberg@logo.svg=http://localhost:9000/logo2.svg → This would update the attachment logo.svg of the Iceberg to http://localhost:9000/logo2.svg

The goal of this extension is not to provide “pretty” system properties that could be passed to XWiki. The main interest here is to provide fast deployments, where settings in XWiki can be defined by an administrator in advance.

This extension is already developed under LGPL, as part of a project that XWiki SAS is doing with the German Ministry of the Interior. In the case of this project, XWiki is deployed as part of a kubernetes cluster, and having this extension allows defining a couple of properties automatically from the Helm charts used for the deployment, instead of going in the wiki administration.

The current version of this extension can be found here : extension/properties-updater · master · XWiki SAS / Sovereign Workplace / XWiki · GitLab

1 Like
#2

Hi Clement. If I understand correctly this is about configuring/customizing an XWiki instance, especially for configuration data located inside wiki pages (since for xwiki.properties or xwiki.cfg, I guess you’re providing them directly?).

It also seems to show that the current solution we have is not good enough. Right now we offer 2 solutions:

  • to provide a custom flavor or extension to bundle the pages for which you need to have different config data. They are the merged automatically by XWiki when upgrades are done.
  • by using the XWiki REST API to update the xproperties on the command line

What is the advantage of the solution you propose vs the REST API for example?

It is slightly simpler than the following but not that much:

$ curl -u Admin:admin 
       -X POST -H "Content-type: application/x-www-form-urlencoded"
       -H "Accept: application/xml"
       -d "className=XWiki.TestClass"
       -d "property#test=Whatever you want"
       http://localhost/xwiki/rest/wikis/xwiki/spaces/Test/pages/Test/objects

(see https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HCreatinganXWikiObject)

It would be easy to encapsulate the curl command with the parameters into a shell alias.

BTW what user is used to make the changes passed as system properties in your code? I guess it’s the super user.

Thanks

PS: There’s no problem creating a new extension for this. My questions/comments below are to try to understand the generic need and see if there’s something we could do/fix in XWiki standard to avoid this need.

#3

By fast do you mean that the main UC is not to have those property values serialized in some file? Right now I find the UC of overriding properties from the command line quite limited. And if the idea is to actually have a file with all the arguments for starting XWiki, well it will quickly start to look like another xwiki.properties no?

For me it sounds like it should be something that you should be able to put in xwiki.properties and read the values from there.

#4

@caubin will be able to confirm but I think Helm charts (for Kubernetes deployment) allows more easily to define jvm arguments than to override properties file.

#5

Hello hello !

Thanks a lot for the feedback, I’ll try to address all of them below :

Hi Clement. If I understand correctly this is about configuring/customizing an XWiki instance, especially for configuration data located inside wiki pages (since for xwiki.properties or xwiki.cfg, I guess you’re providing them directly?).

Yes, for xwiki.properties and xwiki.cfg, we consider that modifications can be done directly on the files before starting XWiki, and we also provide a configuration option in the XWiki Helm chart to set options within these two files from the chart itself.

What is the advantage of the solution you propose vs the REST API for example?

The goal for this application is indeed to provide a “third way” to customize XWiki parameters. We came to the conclusion that it was needed for the following points :

  • a flavor-based approach requires to have a full build + do releases of the flavor every time a change of configuration is required. For some configuration options, doing a release every time may be a bit cumbersome.
  • a REST-based approach requires a bit more “infrastructure” around the XWiki instance that is deployed. If you want to have these in-page properties set-up through REST API calls on automated deployments, there are a couple of things to implement aside from XWiki :
    • we need a sidecar container that will be responsible for doing the REST calls to the wiki
    • the container will need to have a script that checks if XWiki is ready to have properties saved, which means that
      • XWiki should be ready (the wikis to update need to be initialized)
      • the flavor / the extension that brings the page and the object to be customized needs to be installed on the wiki.

Considering the need for a sidecar container, went towards the path of having the extension I’m talking about in this thread. If we had the possibility to use a sidecar container, we would need to look into how we check if an extension is properly installed through the REST API, as I’m not sure that we have an endpoint for it ATM.

BTW what user is used to make the changes passed as system properties in your code? I guess it’s the super user

To be checked. At this point, changes to the object properties from system properties are started through event listeners (either at application initialization, wiki initialization, or when the flavor of the current wiki is installed / upgraded). I’m not sure of the context user used in that case.

By fast do you mean that the main UC is not to have those property values serialized in some file? Right now I find the UC of overriding properties from the command line quite limited. And if the idea is to actually have a file with all the arguments for starting XWiki, well it will quickly start to look like another xwiki.properties no?

The extension works by looking at the Java system properties ; so it has the small advantage of these system properties being set by other means than the command line, which brings a bit more flexibility when it comes to complex deployments.

Regarding using xwiki.properties, I think it could be an option also, but I wouldn’t leave as the “only” option to provide the properties. It would be interesting to keep flexibility on how these properties are provided (because of how various deployments could be).

Helm charts (for Kubernetes deployment) allows more easily to define jvm arguments than to override properties file.

Indeed, we had to do specific customization to the xwiki-helm chart to support adding lines to xwiki.cfg and xwiki.properties

2 Likes
#6

Hello hello

So, following our exchanges, I’ll move forward with the creation of this repository, with the name “system-properties-updater”.

#7

Repository & JIRA project created :