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#

J2EE Install#

the latest stable version of JSPWiki is now available as a Web Start Application Installer at the following URL: JSPWiki on magpie. Simply click on the 'launch' button to install JSPWiki on a new tomcat or an already existing tomcat on your system.

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.

Easy Windows Installation#

Simple JSPWiki

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 lot