Getting JSPWiki

Requirements

You need:

• Java (1.4 for 2.2)
• To know what a WAR file is and how to use it.
• A Servlet 2.3 -compliant web server. JSPWiki of course runs on 2.4 -compliant servers, we just don't require anything more than 2.3. Containers that are known to work include:
  • Tomcat (4.0 and higher) works quite nicely. For best results, we recommend Tomcat 5.5.
  • See below for more container-specific notes
• A server to run your Wiki on. It does not have to be a very big server: JSPWiki has been run on a 266 MHz Pentium II with 192 Mbytes of memory.
• Some patience (the setup is not as easy as I would like it to be)
• If you want to email things, you need JavaMail and the Java Activation Framework JARs. Email is needed for password recovery, or error logging (log4j) if you wish to configure it that way.

Downloading the Distribution

You can download JSPWiki from the JSPWiki Download Page. There are three different builds of JSPWiki you can download: Stable, Beta, and Latest.

Stable:

• This version has been tested and known to work properly without much error.
• This version is recommended for people who are new to JSPWiki or don't plan on doing much coding or developing.

Beta:

• Beta is being actively developed and tested and known to mostly work.

Latest:

• This version is the latest release with the most recent changes.
• WARNING: This code has not been thoroughly tested and may cause severe problems

All three versions may be downloaded in a package or in whole source code.

Obtaining the Latest CVS Version

• Users are able to download JSPWiki releases through AnonymousCVSAccess.
• The command for AnonymousCVSAccess is:

   cvs -d :pserver:anonymous@cvs.jspwiki.org:/p/cvs checkout JSPWiki

• There are different JSPWiki branches in the CVS, where different releases of JSPWiki can be retrieved.

Installation

Easy Install

JSPWiki is designed to "drop in" to your favorite servlet container and will run without much customization.

To install JSPWiki, just drop the JSPWiki.war file into your servlet container's web application directory. For example, on Tomcat this folder is $CATALINA_HOME/webapps.

Next, point your browser to http://myhost/JSPWiki/Install.jsp and follow the on-screen directions. The installer will ask you where you'd like to store wiki pages, put log files, and a few other things. It will also set up a privileged user account that you will use to manage the wiki. After that, you should restart the JSPWiki webapp (or the container) and you should be ready to start using your new wiki.

By design, the JSPWiki installer page offers only a limited number of configuration options, JSPWiki's other default settings should be sufficient to get you started. By default:

• the default login configuration and security policy is loaded automatically
• anonymous users can edit pages and create user profiles
• users log in with a login name and password
• user identities are stored in an XML file inside WEB-INF
• wiki groups are stored in an XML file inside WEB-INF
• JSPWiki relies on its own authentication and authorization system to manage security, and does not rely on container-managed security

The default settings allow users to create profiles, create pages and groups, and create page ACLs. It's good for a workgroup or small intranet that needs only a single wiki, and it requires no container configuration. If you want to use JSPWiki in a real production environment, you will want to read the Advanced Installation section (next).

In some cases, particular web containers require a small amount of configuration to work properly. See the Container Notes section of this page for details.

Security is the most common configuration issue first-time JSPWiki deployments. JSPWiki has a built-in diagnostic page, at http://myhost/JSPWiki/admin/SecurityConfig.jsp that can help troubleshoot typical problems. For more installation help, see Troubleshooting.

Advanced Installation

Configuring container authentication

As described in the security documentation JSPWiki authenticates users in via either of these methods:

• Custom authentication, which looks up and validates the user's id and password against those stored in JSPWiki's UserDatabase
• Container authentication, which relies on the servlet container to perform the authentication and supply credentials

In many corporate environments, container authentication is the preferred method. Depending on the container's realm configuration, this sharply expands the range of authentication mechanisms available to JSPWiki. Many containers support LDAP, database, Kerberos, SecurID, Shibboleth, SAML and NT domain controller authentication among others. JSPWiki is smart enough to detect whether you are using container authentication. To set up container authentication, you must: 1. Configure your container's authentication realm 2. Uncomment the <security-constraint> block in JSPWiki's web.xml file. See the security documentation for more details on how to do this.

Locking down your wiki

JSPWiki's default policy is suitable for a small team, but is probably too loose for a corporate intranet or public wiki. To constrain privileges for editing, viewing or creating pages, you can modify JSPWiki's default security policy. When JSPWiki starts up, it loads the default policy (stored in WEB-INF/jspwiki.policy).

JSPWiki uses the standard Java 2 security policy APIs under the covers, so if you are familiar with the syntax it should be easy to understand. Default permissions are granted using standard security policy file syntax. See the security documentation for details on customizing the policy for your needs.

Additional options

Additional installation instructions and other options can be found from the package, as a file called 'README'. The 'README' file also has lots of good information on the structure and layout of JSPWiki.

Platform Notes

Building JSPWiki on Fedora Core 6 (linux - FC6)

If you're developing JSPWiki applications on FC6 you should be aware that FC6 comes pre-packaged with GNU Java 1.4.2. A lot of incompatibilities have been reported, so it's highly recommended that you upgrade to the latest Sun version (1.5.0_10 as of the time of this note).

It's also recommended that you don't remove GNU Java from your FC6. Instead, install JPackage and then install the sun compatibility package for that. Basically, what this does is to create a bunch of links that point to different java (or any other application with various versions) implementations. You use the JPackage application 'alternatives' to select the version of any particular application you choose.

It's pretty important to get this straight, because mixing Java versions can create some pretty difficult-to-diagnose problems. With JSPWiki, you need not only the standard java tools ('java' and 'javac'), but also the signing tools ('keytool' and 'jarsigner'). If you end up (like I did) inadvertently running the signing tools from 1.4.2 on code that was compiled with 1.5.0, you get a confusing mess of errors.

See also

For specific platform installs see:

• Windows Install
• Linux Install

Container Notes

Tomcat 5.x

If you are having problems with Tomcat 5.x and JSPWiki with UTF-8, please note the following. We highly recommend that you enforce UTF-8 encoding for Tomcat's HTTP connector. You can do this by editing the appropriate <Connector> element in $CATALINA_HOME/conf/server.xml. For example, change:

<Connector port="8080"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               debug="0" connectionTimeout="20000" 
               disableUploadTimeout="true"/>

so that it includes the term 'URIEncoding="UTF-8"':

<Connector port="8080"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               debug="0" connectionTimeout="20000" 
               disableUploadTimeout="true" 
               URIEncoding="UTF-8"/>

If you are installing multiple installations, please check out InstallingJSPWikiStepByStep for some hints and tips.

Configuring Apache HTTPD and mod_jk

Many people use Apache's AJP connector (mod_jk) to split web-serving duties between Apache (for the front end) and Tomcat (as the app server). To do this properly, you need to configure Apache to delegate web-serving duties for your JSPWiki webapp to Tomcat. You also need to do some light configuration on the Tomcat side.

Apache configuration

First, you need a configuration file that tells Apache to load mod_jk. In your Apache server's configuration directory (typically /etc/httpd/conf.d you'll need a file called mod_jk.conf that contains contents similar to these:

LoadModule      jk_module modules/mod_jk.so
JkWorkersFile   /etc/httpd/conf/workers.properties
JkLogFile       /var/log/httpd/mod_jk.log
JkLogLevel      info

These entries tell Apache to load the mod_jk shared object, log information messages to a specific log file, and obtain detailed configuration information from /etc/httpd/conf/workers.properties.

Next, you need a workers.properties file to tell Apache how its AJP "workers" should function. These can include sophisticated load-balancing and redundancy features, but for most people this isn't necessary. A typical, minimal configuration like this will do the job:

[channel.socket:localhost:8009]
port=8009
host=127.0.0.1

[ajp13:localhost:8009]
channel=channel.socket:localhost:8009

This says: create a single worker called ajp13 that connects to localhost on port 8009. This is the port number that Tomcat's AJP connector listens to.

Finally, you need some Apache configuration directives to tell it which URLs to send to Tomcat. Create a text file, for example /etc/httpd/conf.d/mywebsite.conf with a single directive that redirects all traffic for the /mywebsite path to our AJP worker (ajp13):

JkMount /mywebsite/* ajp13

Tomcat configuration

For Tomcat 5.5, all you need to do is make sure that the AJP connector is enabled, which it is by default. Open the $CATALINA_HOME/conf/server.xml file and verify that its AJP connector is uncommented:

    <Connector port="8009" 
               enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

High-security configuration

If you follow the preceding steps, you should be able to get mod_jk working properly. Apache will happy delegate web serving duties to Tomcat, and all should be well. However, we can optimize our configuration further. Recall that in the simple configuration above, we passed all traffic for the /mywebsite path through to Tomcat. But it would be nicer, and more secure, if we only passed through the traffic that actually needed to go to Tomcat. It would also be better for performance if we could persuade Apache to serve the static content (like graphics and stylesheets) rather than Tomcat.

So, in your mywebsite.conf file, here is an improved set of directives:

UseCanonicalName Off
RewriteEngine on
RewriteRule ^/$ /mywebsite/Wiki.jsp [R]
RewriteRule ^/mywebsite/$ /mywebsite/Wiki.jsp [R]

JkMount /mywebsite/*.jsp ajp13
JkMount /mywebsite/attach ajp13
JkMount /mywebsite/attach/* ajp13
JkMount /mywebsite/attach/*/* ajp13
JkMount /mywebsite/rss.rdf ajp13
JkMount /mywebsite/j_security_check ajp13

These directives will only pass through traffic for RSS, JSP pages, and to the attachment servlet (at /mywebsite/attach). The directive for j_security_check should be included if you use container-managed authentication, and omitted if not. Also, note the RewriteRule: it will cause Apache to re-write any traffic for http://www.mywebsite/ so that it instead goes to http://www.mywebsite/mywebsite/Wiki.jsp.

For the high-security configuration, the last thing you will need to do is extract JSPWiki's static content files and move them to a directory where Apache can serve them from. In the JSPWiki Ant build scripts, the task staticzip exists for just this purpose. In your build.properties file, set the static.user property to the Unix runtime user Apache uses (default: apache), and set the static.group to the Unix runtime group daemon. The staticzip task will extract the static files, apply the correct user and group permissions, and create a tar/gzip file called build/JSPWiki-static.tar.gz. You should unpack this file into a directory Apache will serve from. Make sure that the paths to the content match what your website expects (for example, you will want to put the static files into a mywebsite directory off of the main HTTP content root).

Using Apache for authentication

Some people prefer to use Apache's native and third-party authentication modules, for example SecurID or digital certificates. These are an alternative to Tomcat-managed (or JSPWiki-managed) authentication. Essentially, what is needed is to use Apache as the main source for authentication credentials. This is very easy to do.

You need to do only one small thing: configure Tomcat so that it trusts the identities set by Apache. This will allow Apache to propagate identities so that they are injected into the Java HTTP request stream. Thus, when JSPWiki sees either a 'remoteUser' or 'userPrincipal' property in the request, it will automatically pick it up and treat the user as authenticated.

To configure: if you are using the AJP connector (mod_jk), then you should add a tomcatAuthentication atrtibute to the Tomcat AJP connector's configuration, and give it the value of false. For more details, see the official Tomcat documentation.

JBoss 3.x and 4.x

JSPWiki makes extensive use of JAAS, which in its standard implementation uses a plain text file for configuration. But JBoss uses a special JAAS configuration file format. So we need to translate the standard JAAS configuration file syntax into something JBoss can use.

You should add the following (adjusted for your needs if necessary) to your server's login-config.xml file, which is by default in JBOSS_HOME/server/default/conf/login-config.xml:

    <application-policy name="JSPWiki-container">
      <authentication>
        <login-module code="com.ecyrd.jspwiki.auth.login.WebContainerLoginModule"
          flag="sufficient"/>
        <login-module code="com.ecyrd.jspwiki.auth.login.CookieAssertionLoginModule"
          flag="sufficient"/>
        <login-module code="com.ecyrd.jspwiki.auth.login.AnonymousLoginModule"
          flag="sufficient"/>
      </authentication>
    </application-policy>

    <application-policy name="JSPWiki-custom">
      <authentication>
        <login-module code="com.ecyrd.jspwiki.auth.login.UserDatabaseLoginModule"
          flag="required"/>
      </authentication>
    </application-policy>

GlassFish

This documentation was cheerfully stolen from a blog post by Senthil Chidambaram. It has been edited and reformatted.

1. Deploy the JSPWiki.war file to your GlassFish appserver using the "asadmin deploy" command, or go to the admin console to deploy the web app.
2. Once the war file successfully deployed, make the following configuration changes:
   1. Edit the jspwiki.properties file, which should be stored in $GLASSFISH_HOME/applications/j2ee-modules/. You'll need to change a few settings, like the location of your wikipages, attachments etc. This file is self explanatory.
   2. Copy WEB-INF/jspwiki.jks to the GlassFish $GLASSFISH_HOME/config directory.
   3. Append the contents of WEB-INF/jspwiki.policy to $GLASSFISH_HOME/config/server.policy. Feel free to make changes to the JSPWiki-related policy blocks as you need, as described elsewhere in the security documentation.
   4. Append the contents of WEB-INF/jspwiki.jaas to $GLASSFISH_HOME/config/login.conf.

Restart the server, and access the context root of your JSPWiki webapp. You should see the front page.

You can also find some additional and detailed instructions for setting up JSPWiki & Glassfish here.

Caucho Resin

According to Jacky Liu, JSPWiki works on Caucho's Resin servlet container on versions 3.0.22 and higher.

JSPWiki does not run on Resin versions earlier than 3.0.22. The root cause was due to the fact that Resin did not properly load certificates in signed JAR files, which JSPWiki uses. Thanks to Caucho's Scott Ferguson for working with us on the fix.

Download the war file and drop it to $resin_dir/webapps/ then other configurations almost the same as Tomcat 5.

Jetty

JSPWIki is reputed to work on jetty-5.1.6 and 5.1.10. Version 5.1.7 and later requires a symlink in $jetty_dir/ext to JSPWiki's log4j.jar. Alternatively, you may also copy log4j.jar into $jetty_dir/ext.

Note: these instructions have not been confirmed by the JSPWiki core team. Feel free to mark up this entry with more accurate information or corrections.

WebLogic

See http://jspwiki.org/wiki/WebLogic.

WebSphere Community Edition

This is an 'IBM-enhanced' version of Apache Geronimo, available for free as an open source offering: WebSphere Application Service, Community Edition.

See http://www-306.ibm.com/software/webservers/appserv/community/ and http://www-128.ibm.com/developerworks/downloads/ws/wasce/

However, although WAS CE V1.1 supports Java 5, Servlets 2.4 and J2EE 1.4, it did not seem happy to run JSPWiki, at least not under Windows XP :(

Warning: installing JSPWiki.war and then starting the application just breaks WAS CE - from that point you cannot login to the WAS console to do anything at all!