Improve XWiki docker image configuration strategy

Hi devs and all xwiki users,

Currently, when using one of the XWiki docker images, when you start the container, an image script will check if there are xwiki configuration files (hibernate.cfg.xml, xwiki.cfg and from the xwiki runtime that are not in your xwiki permanent directory on your host and if not, it’ll copy them to save them, so that you can make easy changes to them, and at the next restart, these files will be copied to the runtime.

While this makes it easy to change the XWiki configuration, it has one problem:

  • If you’ve not made changes to the config files and you upgrade the version of xwiki, and it happens that there’s a config change that was made in XWiki in one the 3 files mentioned, then your instance will start with the old config.

So to work around this, I’d like to propose a change of config strategy:

  1. We document on xwiki-docker/ at master · xwiki/xwiki-docker · GitHub that if users need to make changes to config files, they’ll need to map a docker volume for them. We document the locations of all config files to make it easier.
  2. We keep the backward-compatibility so that if these config files exist in the host permanent directory, they are copied to the runtime (as it’s the case now). We also document that this can be used as an alternative to point 1) if you want to have all the config files located in the host permanent directory.

It should also fix Loading... and Loading....

Note that this strategy doesn’t address merging configuration files if you’ve made changes to them and the XWiki runtime also has made changes to them. This has to be done manually currently (we could document some command line to help with this though).



1 Like

I’m definitively +1 with the idea, since I was puzzled by the current behavior during my initial tests of the docker image.

PS: I’m not sure I am still considered as an active committer, so I’ll let you apply the rules concerning if my vote should count or not.

don’t worry it’s not a vote :wink: (just a proposal)

Excellent idea and proposal, and the impact on XWiki Helm will be minimal considering that configs volume is already created/mounted as volume and has a similar proposed strategy but made on an additional startup script.

I would like to verify if we can consider others files/configs on this mounted volume. On XWiki Helm we are providing ways to configure that are:

  • Logs: WEB-INF/classes/logback.xml
  • JGroups (for cluster setup): WEB-INF/observation/remote/jgroups

With this improvement in configuration strategy, we can get closer to having support for read only container image. That maybe we just need to address extension.xed change at startup.

The idea is for the user to mount these 2 files (and any other config files) if they need to modify them. There’s no default mount and all config file locations will be documented in the README. Actually we can provide an example through the docker compose example.

The files are not config and are generated by XWiki automatically when they don’t exist. They should be considerd more lilke cache files I think. It’s true that it would be cleaner if these could be generated in the perm dir rather than in WEB-INF/lib which would be better as read only. I don’t know if there’s a jira already about this, couldn’t find one, so could be interesting to start a forum thread about it.


Done in Loading...

Will be in effect for the next releases, i.e. XWiki 16.6.0, 16.4.2 and 15.10.12.

Documented at xwiki-docker/ at master · xwiki/xwiki-docker · GitHub

1 Like