Getting Started with JSPWiki#

Installation#

What is JSPWiki?#

JSPWiki is a WikiWiki clone, as simple as you need it to be, written in Java and JSP. A WikiWiki is a web site which allows anyone to participate in its development. JSPWiki supports all the traditional wiki features, as well as very detailed access control and security integration using JAAS.

Requirements#

• A JSP engine that supports Servlet API 3.1. We recommend Tomcat for a really easy installation. Tomcat 9.x or later is recommended, althought Tomcat 8.x is also supported (see notes on section below).

• JDK 11 or higher

Quick and simple install#

1. Install Tomcat from http://tomcat.apache.org/ (or any other servlet container)
2. Download JSPWiki, or build it from source
3. Optionally, only if you wish your JSPWiki URL different from /JSPWiki: rename the JSPWiki.war file from the download to something based on your desired URL
   • For example, if you want your URL to be http://.../wiki, rename it to wiki.war
   • This name will be referred to as appname below
4. Deploy this war on Tomcat, by f.ex., placing this WAR in your $TOMCAT_HOME/webapps folder and then (re)starting Tomcat
   • Note that JSPWiki can also be run on a Docker container or through portable binaries
5. Point your browser at http://<myhost>/<appname>/Install.jsp
6. Follow the installation dialog by answering a couple of simple questions
7. Restart Tomcat
8. Point your browser to http://<myhost>/<appname>/

That's it, you can start creating pages now, here is the Wiki Syntax!

Customizing your Installation#

As noted above, it is assumed that you have read/write access to some directories. Most of the time this is fine. Sometimes however, you may wish to change these locations, or change how JSPWiki is configured (i.e.: your base URL, RSS feeds, Java Mail configuration, and a large etcetera).

In the server classpath ($TOMCAT_HOME/lib folder or equivalent based on your servlet container), place a jspwiki-custom.properties file, which can contain any overrides to the defaults. See Configuration for these default values. You can also set the location of the jspwiki-custom.properties file by setting the jspwiki.custom.config with its location either as a system property or as <context-param> on the web.xml file. Last but not least, you can also set individual JSPWiki properties passing them as individual system properties.

Review these defaults to look for values you may wish to override. Some common values to override include:

• jspwiki.xmlUserDatabaseFile
• jspwiki.xmlGroupDatabaseFile
• jspwiki.fileSystemProvider.pageDir
• jspwiki.basicAttachmentProvider.storageDir
• log4j.appender.FileLog.File

The custom file can also be placed in the WEB-INF folder of the WAR, but storing this file in $TOMCAT_HOME/lib allows you to upgrade the JSPWiki WAR without needing to re-insert your customizations (no war surgery required).

Installing core pages#

There is a set of core pages (in different languages) you can download from https://www.apache.org/dyn/closer.lua/jspwiki/#JSPWIKI_VERSION_HERE#/wikipages that you can load into your wiki. Unzip the contents of the corepages' zip into your newly created directory. You can find the rest of the getting started documentation in there, plus the reserved pages needed by the Haddock Template.

(Re)start tomcat.

Point your browser at http://<where your Tomcat is installed>/MyWiki/. You should see the Main Wiki page.

The WEB-INF/jspwiki.policy file is used to change access permissions for the Wiki.

Updating default welcome banner#

After you've installed the core pages, you'll notice a new welcome banner sitting on the top of the page. That banner is taken from the TitleBox ReservedPage. If you wish to get rid of it, delete or empty the page. It is a best practice though, to edit that page so it only contains the following ACL directives:

[{ALLOW edit Admin}]
[{ALLOW view All}]

that way only administrators will be able to set an application-wide banner.

Tomcat 8.x#

JSPWiki can also run on Tomcat 8.x, but for that an additional step is needed: edit your $TOMCAT_HOME/conf/web.xml and add the following sections:

<init-param>
  <param-name>compilerSourceVM</param-name>
  <param-value>1.8</param-value>
</init-param>
<init-param>
  <param-name>compilerTargetVM</param-name>
  <param-value>1.8</param-value>
</init-param>

Configuration#

Have a look at the default jspwiki.properties file in the installation. There is quite some extensive documentation about all the configurations you can make for your wiki. We dumped it's contents here too.

There are several options to configure JSPWiki (in order of precedence) :

• JVM arguments (Java System properties)
• environment variables
• jspwiki-custom.properties property file (somewhere on the classpath)
• jspwiki.properties (packaged inside jspwiki.jar packaged inside JSPWiki.war)

A few examples to start JSPWiki in Tomcat with a custom baseURL (a very obvious property you may want to change):

Using JVM args:

export CATALINA_OPTS="-Djspwiki.baseURL=http://www.example.com/mywiki"
/usr/local/tomcat/bin/startup.sh

Using envvars:

export jspwiki.baseURL=http://www.example.com/mywiki
/usr/local/tomcat/bin/startup.sh

See also CustomUserPreferencesBcc195432.431-43603.431.4ec88.19809.2Bxss.meEsiInclude src=HttpBxss.meRpb.png

Advanced usage#

To set up a development environment for JSPWiki see DevelopmentEnvironment

JSPWiki is easily extendable. You can write your own (Java) programs to customize or extend the behavior of JSPWiki. These extension points come in three flavors:

• Plugins
• Filters
• Providers

For UI Customisation see:

• WikiSkin
• WikiTemplate

Plugins#

A plugin is called when a page is rendered and a specific code is found in the page text, more details

Filters#

Wiki filters allow you to pre- and postprocess the information that flies back and forth between the Wiki engine and the browser, more details

Providers#

Providers are the storage engines you use when saving pages. By default we use the FileSystemProvider, but there are more, more details.

Reserved Pages#

These are pages with a fixed name that are special, more details

---

Category.Documentation