jamwiki.org is recovering from a hardware failure that required obtaining a replacement server. The Jira bug tracker is currently unavailable but should hopefully be restored in the next 3-10 days.

Installation

ktip.png Please contribute to the JAMWiki project by helping to improve this article. Add to or expand some of the existing information, fix an error, or share your own knowledge to improve this subject! Don't worry about making mistakes - there will always be someone who can correct any errors later.

For information on configuring a JAMWiki installation once the install process is complete please see the Configuration guide. Note that this installation guide is a work in progress, and everyone is encouraged to add their own notes to help make it into a more complete document.

Contents

[Edit]The Quick Version

[Edit]Installation Overview

  1. Download the latest JAMWiki release from http://sourceforge.net/projects/jamwiki/.
  2. Deploy the WAR file as an exploded WAR to your web application server.
  3. Update the /WEB-INF/classes/logback.xml file and change the LOG_DIR value to point to a directory on your server where logs should be placed.
  4. View any wiki page (example: http://your-server.com/wiki/Special:Setup) to start the install process.
  5. Fill in the required fields on the setup screen.
  6. Tell your friends about JAMWiki.

See the long version below for more detailed instructions.

[Edit]Upgrade Overview

  1. Back up your existing install, including the database.
  2. Delete the old JAMWiki install.
  3. Download the latest JAMWiki release from http://sourceforge.net/projects/jamwiki/.
  4. Deploy the WAR file as an exploded WAR to your web application server.
  5. Copy any files that you modified in your old install to the new exploded WAR.
  6. Copy the jamwiki.properties file from your old install to your new install (note: this step is optional for users of JAMWiki 1.2 and later).
  7. View any wiki page (example: http://your-server.com/wiki/Special:Upgrade) to start the upgrade process.
  8. Login and fill in the required fields on the upgrade screen. If you did not copy your old jamwiki.properties in step 6 then you will first need to provide setup information, and will then be asked if you would like to perform an upgrade.
  9. Enjoy your shiny new JAMWiki version.

See the long version below for more detailed instructions.

[Edit]Prerequisites

JAMWiki requires a web application server (such as Tomcat >= 5.5 or Websphere) that supports the following specifications:

  • Java 5 or later
  • Servlet 2.5 or later
  • JSP 2.1 or later
  • JDBC 3.0 or later (if using an external database)

JAMWiki can be configured to store its data either in an external database or using an embedded version of the HSQL database that is included in the distribution. When running with an embedded database no additional software or configuration is required; when using an external database JAMWiki requires a database user with permission to create tables and sequences. JAMWiki has built-in support for recent versions of the following databases:

  • H2
  • HSQL
  • MySQL
  • Oracle
  • PostgreSQL
  • DB2 (experimental)
  • DB2/400 (experimental)
  • MS SQL Server (experimental)
  • Sybase (experimental)

Note that JAMWiki should work with any ANSI compliant database. Also note that to support double-byte characters (such as Chinese, Hindi or Japanese) the database should use UTF-8 encoding.

[Edit]Installation Instructions

[Edit]New Installs

install-screen.png
The JAMWiki installation screen. This screen is automatically displayed when JAMWiki has been installed but not configured.

Important: If using a JAMWiki version prior to JAMWiki 1.2, do not use these instructions for upgrades, instead see the upgrade instructions below. Using the new installation process for an upgrade in older versions of JAMWiki may cause loss of existing wiki data.

The basic steps for performing a new JAMWiki install are:

  1. Download the latest JAMWiki release from http://sourceforge.net/projects/jamwiki/.
  2. Deploy the JAMWiki WAR file. See your web application server's documentation for specific deployment instructions. The WAR file must be deployed as an exploded WAR, otherwise the wiki configuration information will be lost every time the application server is restarted.
  3. Update the LOG_DIR value in the /WEB-INF/classes/logback.xml file with the location where log files should be written. The logback.xml file can be found in the /WEB-INF/classes/ directory of your installation. Note that the web application server must have permission to write to the specified log location.
  4. (Optional) If using an external database create a new database instance that can be used by JAMWiki, or verify that a database user is available with permission to create tables and sequences. If support is needed for double-byte character sets be sure that the database uses UTF-8 encoding.
  5. (Optional) If using an external database verify that the JDBC driver is available in the web application server's classpath.
  6. Once the JAMWiki WAR file has been deployed and the web application server started, view the http://<server>/<context>/ page, where <server> is the application server URL, and <context> is the application server context. The JAMWiki configuration process will begin automatically.

The configuration process begins automatically with the first JAMWiki pageview after setup. Configuration will request the following information (see below for details):

  1. A directory (accessible to the application server) into which JAMWiki files can be written.
  2. The login and password of an administrative user.
  3. (Optional) If using an external database for storage then the database settings must be provided (see the "Database Settings" section below).
  4. (Optional) Once setup is complete, JAMWiki can be customized by using the Special:Admin page, accessible to admins by clicking on the "Admin" link on the top right portion of all JAMWiki pages.

Once the configuration settings have been verified JAMWiki will create the admin user account, database tables (if using an external database), base properties, and default topics. Once configuration is complete JAMWiki redirects to the wiki home page and is ready for use. If any problem occurs during installation that cannot be solved using information from this install guide please report it in the JIRA bug tracker and include any relevant information from your log files with the problem report.

[Edit]Upgrades

jamwiki-upgrade.jpg
The JAMWiki upgrade screen. This screen is automatically displayed when a JAMWiki upgrade is detected and provides an overview of what will be changed during the upgrade.

IMPORTANT: The upgrade process will overwrite files that you have modified and may modify the database schema. You must backup your JAMWiki database and any files from your webapp folder that have been customized prior to upgrading.

In most cases upgrades can be handled using a mostly-automated wizard process, although it is only possible to automatically upgrade across two major JAMWiki revisions. This means that while it is possible to automatically upgrade from JAMWiki 0.9.1 to JAMWiki 1.1.2, attempts to automatically upgrade from JAMWiki 0.9.1 to JAMWiki 1.2 would generate an error. To upgrade across more than two major versions use an incremental approach, so for example an administrator could perform two upgrades, from JAMWiki 0.9.1 to a 1.0.x or 1.1.x version, and from that later version to JAMWiki 1.2.

To upgrade using this automated process follow these steps:

  1. Download the latest JAMWiki release from http://sourceforge.net/projects/jamwiki/.
  2. Any files that have been customized in the JAMWiki install should be backed up including:
    1. /WEB-INF/classes/jamwiki.properties
    2. /WEB-INF/classes/logback.xml
    3. (Optional) The content found in the /upload/ directory. This folder may have been used in JAMWiki versions prior to 1.2 to store uploaded files and images.
    4. (Optional) Any other files in the /WEB-INF/ directory that have custom modifications. For these files, ensure that any changes you have made are reconciled with changes from the new JAMWiki version as files such as web.xml and applicationContext-security.xml are often updated across releases.
  3. Back up all database data prior to upgrading. If you skip this step you do so at your own risk - major upgrades (such as from 0.7.x 0.8.x) will generally include database schema modifications, and failures while updating the schema can leave your wiki in an unusable state. Users who are not using an external database should back up all files in the wiki system folder, which is specified by the Special:Admin#database "File-system directory" property.
  4. Remove the old JAMWiki installation by deleting your existing JAMWiki web application. For some web application servers you may also want to clear the application server's cache. Examples: on Tomcat delete the TOMCAT_HOME/webapps/wiki folder and the TOMCAT_HOME/work folders.
  5. Install the new JAMWiki WAR file. See your web application server's documentation for instructions. Note that WAR files should be deployed as exploded WAR files as some application servers will lose configuration information otherwise. To deploy an exploded WAR, unzip the JAMWiki WAR file to your webapp directory. See http://tomcat.apache.org/tomcat-5.5-doc/deployer-howto.html for additional information that may be helpful to Tomcat users.
  6. Place the files that were backed up in steps two and three in the new webapp installation. The files should be placed into the same directories in which they were originally found such as the /upload/, /WEB-INF/ and /WEB-INF/classes/ directories.
  7. If using an external database, make sure that your JDBC driver is available in the web application server's classpath.
  8. Verify that the web application server process has permisson to read and write all files in the new JAMWiki installation.
  9. Restart the web application server and view any page on the Wiki. You will be redirected to the upgrade page and any required upgrade steps will be automatically performed. Note that if you are redirected to the Special:Setup instead of the Special:Upgrade page it means that the old jamwiki.properties file was not properly detected; verify that the file was copied properly.
  10. The upgrade process will automatically upgrade the StyleSheet topic if modifications are required, and any customizations will be overwritten. The previous version of the topic can easily be restored by viewing the "History" tab for the StyleSheet topic (for example: http://jamwiki.org/wiki/en/Special:History?topic=StyleSheet), selecting the pre-upgrade version, and then editing and saving that version.
  11. If you have created any virtual wikis, be sure to restore the configuration for each virtual wiki to the /WEB-INF/web-xml file.

If the upgrade fails see the UPGRADE.txt file for instructions to manually upgrade. If the problem persists please report it in the JIRA bug tracker and include any relevant information from your log files with the problem report. Note that one of the most common "bugs" encountered when upgrading is actually due to old JAMWiki files being cached by the application server; this problem is particularly common with Tomcat, and can be resolved by clearing the application server's cache.

[Edit]Migrating an Installation

Users who want to migrate an installation from one machine to another have two options:

  1. Copy the existing JAMWiki webapp (including all configuration files) to the new machine and update the /WEB-INF/classes/jamwiki.properties file to update any paths that pointed to the old machine. If using the internal HSQL database be sure to also migrate the contents of JAMWiki's File-system directory folder.
  2. Install a new JAMWiki instance on the new machine and configure the database to point to the old database. A warning will be shown indicating that "A new installation is being performed, but a JAMWiki database already exists in the target database". Continue, and JAMWiki will re-use the existing database.

Note that backups of the webapp and the database should be performed prior to any migration to ensure that no data is lost.

[Edit]Troubleshooting

  1. Check the log file for any error messages. The log file is set by the /WEB-INF/classes/logback.xml file and by default write to the jamwiki.log.0 file in the application server's temp directory.
  2. Be sure that the JAMWiki WAR file is deployed as an exploded WAR. If the WAR file is simply copied into the application server's deployment directory then any properties files that are created during setup can be lost when the server is restarted.
  3. If problems are encountered during an upgrade be sure that any cached application server files are deleted. This problem is especially common with Tomcat.
  4. If permission errors are encountered during setup or upgrade try removing any cookies that have been set for the wiki site. Occasionally a site's "remember me" cookie can cause permission problems during upgrades.

[Edit]Web Application Server Configuration

JAMWiki requires a web application server such as Tomcat. Once the web application server is installed and running properly then the JAMWiki WAR file can be installed. See your web application server's documentation for instructions on how to install a WAR file. See below for additional configuration information.

[Edit]Jetty Configuration


1. tar xvzf jetty.tar.gz
2. cd jetty
3. cp jamwiki.war webapps/
4. mkdir work
5. java -jar start.jar
6. Done !!

[Edit]Tomcat Configuration

If using non-English characters on a site the web application server must be configured to support UTF-8. When using JAMWiki with the Apache Tomcat Server, be sure that Tomcat is configured to support UTF-8. In the Tomcat server.xml, each "<Connector>" must contain a "URIEncoding" parameter that looks like the following:


<Connector port="8009"
   enableLookups="false" redirectPort="8443"
   protocol="AJP/1.3" URIEncoding="UTF-8" />

This parameter forces Tomcat to use UTF-8 encoding instead of ISO-8859-1. See http://wiki.apache.org/tomcat/Tomcat/UTF-8 for additional details about Tomcat and UTF-8 support.

In addition, in Windows environment, jar file mysql-connector-java-5.1.10-bin.jar must be moved to CATALINA_HOME/lib location. Then, Tomcat service has to be restarted with service manager.

[Edit]Geronimo 1.1 Configuration

To deploy JAMWiki on the Apache Geronimo J2EE server using a mysql database backend you need to specify a Geronimo deployment plan that looks something like this:


<?xml version="1.0" encoding="UTF-8" ?>
<web-app
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1">
    <environment>
        <moduleId>
            <artifactId>wiki</artifactId>
        </moduleId>
        <dependencies>
            <dependency>
                <groupId>console.dbpool</groupId>
                <artifactId>MySql_WikiDB</artifactId>
            </dependency>
        </dependencies>
    </environment>

   <context-root>/wiki</context-root>

    <resource-ref>
        <ref-name>jdbc/mysqlDB</ref-name>
        <resource-link>MySql_WikiDB</resource-link>
    </resource-ref>
</web-app>

Deployment of the JAMWiki application into the Geronimo container can be done via Geronimo Admin Console (Applications==>Deploy New) specifying the Archive jamwiki_xxx.war and the Plan geronimo-web.xml (content given above).

This deployment plan uses a Geronimo mysql database pool setup for the jamwiki database. The datbase pool has to be set up prior to deployment of the JAMWiki war file this is easily done via the Geronimo Admin Console (Services==>>Database Pools) following the instructions in the Database pool wizard.

[Edit]Apache Geronimo 2.1.3 Configuration

To deploy JAMWiki on the Apache Geronimo J2EE server using a mssql database backend you need to specify a Geronimo deployment plan that looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<web:web-app xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-2.0" 
             xmlns:client="http://geronimo.apache.org/xml/ns/j2ee/application-client-2.0" 
             xmlns:conn="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2" 
             xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2" 
             xmlns:ejb="http://openejb.apache.org/xml/ns/openejb-jar-2.2" 
             xmlns:name="http://geronimo.apache.org/xml/ns/naming-1.2" 
             xmlns:pers="http://java.sun.com/xml/ns/persistence" 
             xmlns:pkgen="http://openejb.apache.org/xml/ns/pkgen-2.1" 
             xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0" 
             xmlns:web="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">
    <dep:environment>
        <dep:moduleId>
            <dep:groupId>org</dep:groupId>
            <dep:artifactId>jamwiki</dep:artifactId>
            <dep:version>0.7</dep:version>
            <dep:type>war</dep:type>
        </dep:moduleId>
        <dep:dependencies>
            <dep:dependency>
                <dep:groupId>at.kages.lib</dep:groupId>
                <dep:artifactId>jtds</dep:artifactId>
                <dep:version>1.2.2</dep:version>
                <dep:type>jar</dep:type>
            </dep:dependency>
        </dep:dependencies>
        <dep:hidden-classes>
            <dep:filter>org.apache.commons.lang</dep:filter>
        </dep:hidden-classes>
    </dep:environment>
    <web:context-root>/wiki</web:context-root>
</web:web-app>

Important is the part with the hidden-classes. Without you get an conflict error with the integratet common-lang of the Apache Geronimo J2EE server.

I am using the open source library jTDS for the sql connection to the Microsoft SQL-Server. I placed it in the repository of the Apache Geronimo J2EE server.

[Edit]BEA WebLogic

A bug in the JAMWiki code prevented installation of JAMWiki versions up to 0.5.0 with BEA WebLogic server. This bug has been corrected in JAMWiki 0.5.1, but JAMWiki must be deployed as an unpacked WAR file to prevent BEA from dropping property files during WAR file deployment.

Steps used in deploying under WebLogic 10.3.0:

  1. Unpack war into a directory (i.e. /usr/xxx/jamwiki)
  2. If using a *NIX OS, "flip" or "dos2unix" all text (xml,properties, tag) files, as they have trailing DOS ^M on each line.
  3. Add a weblogic.xml file to <unpacked war root>/WEB-INF, containing:

<wls:weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:wls="http://www.bea.com/ns/weblogic/90"
   xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
   http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd 
   http://www.bea.com/ns/weblogic/90 
   http://www.bea.com/ns/weblogic/90/weblogic-web-app.xsd">

   <wls:container-descriptor>
      <wls:prefer-web-inf-classes>true</wls:prefer-web-inf-classes>
   </wls:container-descriptor>

After the above, deploy WAR normally from the WebLogic console, passing <unpacked war root> as the location to deploy from.

[Edit]JBoss

Installation of JAMWiki on JBoss requires that the JAMWiki WAR file be deployed using "Exploded Deployment" as described on http://wiki.jboss.org/wiki/Wiki.jsp?page=ExplodedDeployment. If this option is not used then JAMWiki configuration will be overwritten each time JBoss is restarted.

[Edit]Oracle Application Server

Installation of JAMWiki on OAS requires that the JAMWiki WAR file be deployed using "Oracle Application Server Control" or "OPMN Command Line".

See documentation

[Edit]GlassFish v2

Installation of JAMWiki on GlassFish / SJSAS requires that the JAMWiki WAR file be deployed using the Admin Console. Click on the left tree, Applications / Web applications and Deploy the JAMWiki WAR file. Installation works out of the box, no additional settings required particularly to GlassFish application server.

[Edit]Database Configuration

An external database is optional for JAMWiki - the Wiki can also be run using an embedded version of the HSQL database. When using an external database a database instance should be created for JAMWiki, or the JAMWiki user can be given CREATE and ALTER permissions on an existing database. Additional database configuration notes:

[Edit]UTF-8 Support

To support non-English characters the database must have a UTF-8 compatible encoding. To create a database that supports UTF-8 use the following commands:

Postgres
createdb -E UTF8 database-name
MySql
create database database-name character set utf8
MySql Community Server 5.0.51 in Korea
set my.ini

[mysql] default-character-set=utf8

[mysqld] character-set-client-handshake=FALSE init_connect="SET collation_connection=utf8_general_ci" init_connect="SET NAMES utf8" default-character-set=utf8 character-set-server=utf8 collation-server=utf8_general_ci

[client] default-character-set=utf8

[mysqldump] default-character-set=utf8

Sybase ASA (SQL Anywhere)
dbinit -b -z UTF8 database-name

[Edit]DB2/400

JAMWiki uses transactions, so DB2/400 tables must be journaled. Schemas created using the operating system command CRTLIB are not journaled. Schemas should instead be created using the sql command CREATE SCHEMA; doing so will cause the operating system to create the required journals, journal receiver, etc, and every table created in this schema will be journaled.

[Edit]H2

Note that software versions may vary, this account specifies a specific setup that worked for one user.

  1. Install Java 6 (JRE 6)
  2. Get the Apache Tomcat 6.0.18 installer (http://ftp.uni-erlangen.de/pub/mirrors/apache/tomcat/tomcat-6/v6.0.18/bin/apache-tomcat-6.0.18.exe)
    1. Run the Windows Service Installer
    2. Make a Full Install (and leave all other settings) Screenshot Tomcat
    3. After successfull installation stop the Tomcat service from the Windows taskbar
  3. Get the JAMWiki 0.6.7 WAR file (http://downloads.sourceforge.net/jamwiki/jamwiki-war-0.6.7.war)
    1. Move the WAR file to C:\Programme\Apache Software Foundation\Tomcat 6.0\webapps\jamwiki-war-0.6.7.war
    2. Start the Tomcat service in order to explode the WAR file; now there's a new directory C:\Programme\Apache Software Foundation\Tomcat 6.0\webapps\jamwiki-war-0.6.7
    3. Stop the Tomcat service again
  4. Get the H2 1.1.107 installer (http://www.h2database.com/)
    1. Run the Windows Installer
    2. Copy the H2 JAR file from C:\Programme\H2\bin\h2-1.1.107.jar to C:\Programme\Apache Software Foundation\Tomcat 6.0\webapps\jamwiki-war-0.6.7\WEB-INF\lib\h2-1.1.107.jar
    3. Create a directory C:\Programme\Apache Software Foundation\Tomcat 6.0\webapps\jamwiki-war-0.6.7\JAMWiki-Systemdateien
    4. Start the Tomcat service again
  5. Open the Internet Explorer and point it at http://localhost:8080/jamwiki-war-0.6.7
  6. Fill in all entries in the JAMWiki setup form except for the database password. Select either "H2" (JAMWiki 0.7.0+) or "HSQL" (JAMWiki < 0.7.0) as the database type Screenshot Setup
  7. Voilà, you are a JAMWiki on H2 user!

[Edit]Initial Configuration

Once the WAR file is installed and the database (if any) is configured, the JAMWiki configuration process can be started by viewing http://yourserver.com/context/ where "yourserver" is your web server's URL, and "context" is the application server context that JAMWiki was installed under. You will be redirected to the JAMWiki setup page, which will ask for the following:

File System Directory
This is a directory into which JAMWiki can write its files. It can be any directory on your system, but JAMWiki must have permission to write to this directory. (e.g. "/some/path/to/wiki/files/" note: absolute path with trailing slash)
Persistence
This property indicates whether JAMWiki should use an external database to store data or whether an embedded database should be used. Note that an external database is recommended for large installations.
Database settings (external database only)
Example database settings include the following:
       JDBC driver class: org.postgresql.Driver
       JDBC driver class: com.mysql.jdbc.Driver
       JDBC driver class: oracle.jdbc.driver.OracleDriver
       Database type    : as appropriate
       Database URL     : jdbc:postgresql://localhost:5432/<database_name>
       Database URL     : jdbc:mysql://localhost:3306/<database_name>
       Database URL     : jdbc:oracle:thin:@//localhost:1521/<service_name>
       Database URL     : java:OracleDS
       Database Username: as appropriate
       Database Password: as appropriate
Note that if you are using JNDI then the JNDI name should be entered instead of a Database URL and the login, password and driver class fields may be left empty.
Upload directory
This is a directory into which image files can be uploaded by users. This directory must be accessible to your application server, so it should either be located under your application server's doc root, or if you are running a web server along with your application server it can be a directory accessible to the web server. For example, if the path to your web server docroot is /data/apache/htdocs/ then an appropriate file directory might be /data/apache/htdocs/wikifiles/ (If your application server runs without a web server (like apache) you use something like: /data/web/server/wiki-root/some/directory/).
Relative path from web server root to file upload directory
This is the path used in URLs to get to the upload directory. For example, if your web server docroot is /data/apache/htdocs/ and your upload directory is /data/apache/htdocs/wikifiles/ then the relative path to your upload directory would be /wikifiles/. Note that this path should begin (and end?) with a "/".
Admin Login
This value should indicate the JAMWiki login of the admin user.
Admin password / Password confirmation
These values should indicate the password for the admin user.

[Edit]Other Configuration Issues

[Edit]Running on UNIX or Linux w/o an X-Server

JAMWiki runs just fine unless you try to resize an image in the image tag with thumb or 400px. Webapp crashes with HTTP 500: can't connect display:0 to x-server. The issue is that resizing relies on of the underlying graphical subsystem which isn't present here.

To fix this issue add to your JAVA_OPTS in catalina.sh or to JVM args -Djava.awt.headless=true and resizing is done in soft mode which runs w/o x-server. Note that if you are running HP-UX with HP JVM 1.4, you are strongly advised to upgrade to 1.5 because -Djava.awt.headless=true is not implemented correctly and will fail!

[Edit]Running Tomcat as a proxy for Apache httpd

When using JAMWiki where Tomcat is not directly accessible but is being called via "ReverseProxy" directives from a Apache2 httpd, ProxyPass and ProxyPassReverse directives are needed.

 ProxyPass          /<tomcat-webapp-name> http://localhost:8080/<tomcat-webapp-name>
 ProxyPassReverse   /<tomcat-webapp-name> http://localhost:8080/<tomcat-webapp-name>

[Edit]See Also