Active development of JAMWiki has ceased, and bug fixes and support will be limited at best. If you are interested in taking over management of JAMWiki please send an email to the jamwiki-devel mailing list.

Tech:Upgrade Simplifications

ktip.png This page (and all pages in the Tech: namespace) is a developer discussion about a feature that is either proposed for inclusion in JAMWiki or one that has already been implemented. This page is NOT documentation of JAMWiki functionality - for a list of documentation, see Category:JAMWiki.
Status of this feature: Planned for Tech:JAMWiki 1.2.


While JAMWiki setup is relatively simple, the current upgrade process requires saving and restoring property and other configuration files. It should be possible for this process to be much simpler and less error prone.

Proposed changes

  • Moved configuration files from the webapp to the JAMWiki file system directory. This will eliminate the need to restore files during upgrades. Note that this does not apply to all files - for example, Spring configuration would remain in the webapp folder.
  • Combine the setup and upgrade process. The first step of the process would be to identify the file system directory, and from there the code would either perform a new setup or an upgrade depending on the contents of the file system directory. The upgrade process would then become something like:
    1. Specify file-system directory.
    2. Read configuration from file-system directory.
    3. Login.
    4. Perform upgrade.
  • Potentially move the default /upload folder out of the webapp directory. This would also have the advantage of eliminating bug reports when people install with non-webapp-accessible folders, but might have performance implications.


  • Because installations prior to JAMWiki 1.2 will still have configuration files in the webapp directory it may not be possible to fully implement the simplified upgrade until the ability to to upgrade to 1.2 is removed.
  • For publicly-accessible wikis the setup / upgrade screen may need some protection to prevent malicious users from intercepting the process. Currently the upgrade screen is login protected, but if setup/upgrade are combined then that will no longer be possible since the system won't have any configuration to use for validating logins on initial upgrade install.
  • logback.xml, web.xml and applicationContext-security.xml should remain in the webapp folder, but both of these files may contain user customizations. That means that those files would still need to be restored on upgrade.
  • Any updates to translation files would also require a restore.
  • Files to move to the file-system directory include spam-blacklist.txt, (note that these properties are also stored in the database), jamwiki-configuration.xml.




  • revision 3823 moves the spam-blacklist.txt file and the jamwiki-configuration.xml file to the JAMWiki system directory so that they will not need to be restored during upgrades. -- Ryan • (comments) • 14-Nov-2011 18:56 PST
  • revision 3936 moves the default file upload location from the webapp directory to the JAMWiki file system directory, eliminating one additional manual step that is required during upgrades. -- Ryan • (comments) • 07-Jan-2012 15:56 PST
  • revision 3946 now allows upgrades without the need to copy the old file. If, after the user specifies database and file system, an existing installation is found during setup (ie the user installed a new WAR file without copying old configuration) then the user is given an option to restore the old configuration and automatically perform any required upgrades. -- Ryan • (comments) • 11-Jan-2012 21:07 PST

Update for JAMWiki 1.2

JAMWiki 1.2 includes several changes, including allowing images to be uploaded from the JAMWiki system folder and moving several configuration files out of the app server root and into the JAMWiki system folder. Simplifying the upgrade process will likely continue for JAMWiki 1.3. commons-configuration may be a useful tool for allowing inheritance of configuration values and should probably be examined more closely, so (for example) users would only need to override those values that are of specific interest to them, and in all other cases the JAMWiki defaults would be used.


General comments

Ryan, most of it I had in mind for several mind because I was not happy how JAMWiki handles data right now. This is a huge undertaking but I think this doable within a few month if we have a good design plan. I'd like to be involved in the process. Moreover, from my point of view this should be a non-compatible release 2.0 because it is so different to the prior approach. The best example for such a solution is Sonatype Nexus. It has virtually the best approach for having all generated files out of the webapp. --Michael Osipov 22-Oct-2011 14:45 PDT

I'm not familiar with Sonatype Nexus but will take a look. My hope was that if most of the configuration and other files that change could be moved out of the webapp root and into the system folder that upgrades would be much simpler (as outlined above). I was hoping to do this in a non-incompatible way, so since JAMWiki supports upgrading across two major versions that would mean supporting the old upgrade path until 1.4 is released, but if there isn't any way to implement this capability fully without a non-compatible release then that would be something to consider. I'd be interested in hear your proposed changes. -- Ryan • (comments) • 23-Oct-2011 09:32 PDT
Ryan, your hope can be realized. This is how Nexus does. Please download Nexus's WAR distro and check the /WEB-INF/ nexus-work is the target property. With this one you indicate the work dir. When you do an upgrade, all you need to do is swap the WAR file. It works transparently. Now, you are refering to minor version, not major. x.2.y is a minor. I cannot tell if this can be compatible but a some stuff has to be rewritten in JAMWiki. Especially the file upload/serving stuff. If it breaks something we have to tag it 2.0. Maybe Spring can help us realize those work dir configurations. That's for now. The next step would be a redesign of the installation process. We can leave upgrades aside for a moment. The current setup page can be dramatically reduced. I would check how Nexus determines if there is a work dir or not. After that, we have to determine what config files can be and should be moved out of the webapp dir. Maybe a sample project would be reasonable to examine all necessary capabilities we need. --Michael Osipov 24-Oct-2011 12:09 PDT
Hi Michael - sorry for not responding sooner, but life has been busy. I started outlining some properties to move and some changes to the install / upgrade processes above, and those are all relatively easy to implement. One thing that I haven't looked at closely, and that would be awesome if you could do so, is dealing with serving files/images from a location other the webapp root. Some comments:
  • Building a servlet to read a file and serve it is relatively straightforward, but I've got some concerns about performance, particularly with large files. I'm sure someone has found a way to do this without killing the app server, but I haven't searched for solutions.
  • I'd like to make sure that it is still possible to server files/images via the web server for those who wish to do so ( does this). Allowing this capability might entail a configuration setting or something similar.
Let me know if that's something you have ideas about and would be interested in working on as it would both simplify upgrades and also address a configuration setting (file upload root) that has confused a lot of users over the years. -- Ryan • (comments) • 27-Oct-2011 12:58 PDT

Database schema changes

Currently schema changes are managed using the DatabaseUpgrades class. A downside of this approach is that it is a fairly clunky process, and it is not fine-grained enough to work between major versions, so if a schema changes occur during development then developers must manually update their schemas. An alternative worth considering is something like Flyway, which is a tool that keeps track of what schema changes have been applied and automatically applies any new changes. I haven't delved too deeply into the details, but this might be a nice way to eliminate a pain point for developers and users. -- Ryan • (comments) • 10:46, 23 January 2013 (PST)