[{TableOfContents }]

!!! Getting Started with JSPWiki

!! Installation

__What is JSPWiki?__


JSPWiki is a simple (well, not any more) WikiWiki clone, 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 2.5.  We recommend [Tomcat|http://tomcat.apache.org] for a really easy installation.
  Tomcat 6.x or later is supported.

* JDK 1.6 or higher


__Quick and simple install__


# Install Tomcat from http://tomcat.apache.org/ (or any other servlet container)
# Rename the JSPWiki.war file from the download and rename it based on your desired URL (if you want it different from /JSPWiki). 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.
   Place this WAR in your $TOMCAT_HOME/webapps folder and then (re)start Tomcat
# Point your browser at http://<myhost>/<appname>/Install.jsp
# Follow the installation dialog by answering a couple of simple questions
# Restart Tomcat
# Point your browser to http://<myhost>/<appname>/

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

\\
__Customizing your Installation__

The above steps assume you have r+w access to the following directories, as some 
files and folders will be generated there: your user home (for wiki pages), 
your temp folder (as indicated by the java.io.tmpdir property, for lucene indexes 
and ehcache files) and the directory where your servlet container is started (JSPWiki's
log will be placed there). 

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 $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.

Review these defaults to look for values you may wish to override.  
Some common values to override include :
* jspwiki.baseURL
* 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) in the download that you can load into your wiki.
Unzip the contents of jspwiki-corepages.zip into your newly created directory.  
You can find the rest of the documentation in the JSPWiki-doc.zip file.

(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.


!! Configuration

Have a look at the default [jspwiki.properties|Documentation#section-Documentation-ConfigurationAndAdministration] 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|Configuration] 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 [CustomUserPreferences]

!! 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 "plugpoints" 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|JSPWikiCorePlugins]

! 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|WikiFilters]


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

! Reserved Pages
These are pages with a fixed name that are special, [more details|ReservedPages]


----
[Category.Documentation]

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