This is version . It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]


The most secure way to upgrade is to simply merge your configuration files from your previous installation to the location of your new installation.

You may want to make a backup of your previous installation, undeploy and redeploy the new installation from scratch.

Merge or copy?#

All of the 2.x releases should be somewhat compatible with each other, so basically you'll just need to upgrade the files themselves. The ReleaseNotes suggest that you make a brand new install and copy your old configuration over it. You should consider merging files and directories instead. Merging is better then copying. A simple copy may cause you to loose any new text or properties that might have been introduced. If you don't know how to automate the merge process (Ant tasks recommended)then you will have to manually compare each configuration file for differences.

Upgrading from previous releases (From 2.x.y to 2.x.z ):#

Copying is done from the new distribution to $JSPWIKI_HOME, the place where the old JSPWiki version is installed.
  • Install the JSP files (top-level and the default template)
    • Copy all top-level JSP files (Wiki.jsp, Edit.jsp, etc) to $JSPWIKI_HOME/
    • Copy all default template JSP files to $JSPWIKI_HOME/$myDefault
  • Install the set of JAR files.
    • Copy all of the .jar -files into your $JSPWIKI_HOME/WEB-INF/lib
  • In addition, please check web.xml for any additional definitions that may have been added.

The following configuration files have typically been modified in the old version and need to be merged with the new files:

  • in the $JSPWIKI_HOME/WEB-INF directory
    • web.xml
    • jspwiki.policy
    • jspwiki.jaas
    • jspwiki.tld
  • in the $JSPWIKI_HOME/WEB-INF/lib and $JSPWIKI_HOME/WEB-INF/classes directories
    • merge your plugin libraries and filter files

Important: #

  • In JSPWiki 2.3+, JavaCryptographyArchitectureJCAis used. If the jspwiki.jks file is missing, the server won't recognize the JSPWiki.jar file as secured. Therefore, move your jspwiki.jks file from for example $JSPWIKI_BUILD_HOME/etc/jspwiki.jks) to the $JSPWIKI_HOME/WEB-INF directory on the server. The JSPWiki.jar file is now signed so this step is crucial; failing to do so will cause the new security checks to fail. For more info see:KeyStore.
  • If you added plugins to the old tld file, be sure to include these in the new.

Upgrading to a new version:#

Jspwiki and the MVC model #

Our template files provide the "View", the JSPWiki.jar provides the "Model", and the top-level JSPs provide the "Controller". While the top-level JSP files are JSP (provide HTML with Java snippets".), they're actually "the backend code placed upfront" and are essentially treated as "easy- to-deploy servlets".

When upgrading to a new version, *always* assume that the top-level JSP files are incompatible and *must* be upgraded every single time. View files (those under templates/) are normally kept compatible. There might be bug fixes, though, which is why it is a good idea to upgrade the default template as well. If you want to "freeze" the template, make a copy of the default template, call it "mytemplate" and use that. JSPWiki will then fall back to the default template in case any new JSP files are added.

Upgrading from 2.x:

  • Please reinstall in a new directory. Then move your modified templates into the new templates/ -directory. You MUST have the default template in place, else things might not work. If you have modified the default template, please rename your old template to "mymodifications" or something. You must NOT modify the default template anymore.
  • Replace with your old configuration file. It should run unmodified, though you might want to go through the new file to see new options. Most specifically: * jspwiki.baseURL is now mandatory * jspwiki.workDir is a good idea to set * Set, if you don't want JSPWiki to use its own security system. If you do, head over to for further instructions.
  • You can copy your old filters.xml to WEB-INF/classes

Upgrading from earlier installations:

  • Please make a complete reinstall. Your wiki pages will still be compatible, and the configuration for the most part.

From 1.8.x to 2.0.x#

  • Providers now sleep in a different package. You must change your "jspwiki.pageProvider" setting.
  • CachingProvider is no longer set explicitly. You must use the new "jspwiki.usePageCache" property instead.
  • All HTML code should now go into *Template.jsp instead of Wiki.jsp and the other main JSP pages.
  • SystemInfo.jsp is gone. Instead, there is now a page called "SystemInfo".

So, the best way to do the update is to simply save your "", and "web.xml" files to some safe location, DELETE your previous installation, and install it again from scratch. However, after this your templates should be easily modifiable, and you never again have to resort to such drastic measures again... We hope.


Wrong Version#

I did the upgrade from 2.0.45 to 2.0.48 just like this... And it seems that the upgrade took hold (much faster)... But the version still says I'm on .45... any clues? -- MatthewSimpson

The problem is that when you upgrade, the compiled JSP files contain the compiled version of the version number as well... This problem has actually been solved in 2.1. Remove the compiled JSP files. For Tomcat, remove the $TOMCAT_HOME/work/<your web app> directory, or just touch the JSP files using touch(1).

Nobody seems to have any permissions#

Make sure you've copied the Java KeyStore file $JSPWIKI_BUILD_HOME/etc/jspwiki.jks) to the $JSPWIKI_HOME/WEB-INF directory on the server. JSPWiki 2.3+ uses the JavaCryptographyArchitecture JCA. Absent the jspwiki.jks file, the server won't recognize the JSPWiki.jar file as secured. -- MurrayAltheim

Search is not working properly#

I upgraded from 2.2.33 to 2.4.71 and a word that can be found in the main page cannot be found by the search function. However, when I modified the main page, the search was able to find it. So it seems like there is some kind of refresh required. How am I able to do that so that I don't have to open and save every page?

Define the working directory to the file and the search will work just fine.

Add new attachment

Only authorized users are allowed to upload new attachments.
« This particular version was published on 25-Sep-2007 17:30 by