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.

Please also see the Supported Configurations guide for a list of supported configurations. 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.

Prerequisites

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

• JDK 1.4 or later
• Servlet 2.4 or later

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 tested with the following databases:

• Postgres 8.0
• Postgres 7.4
• MySQL 4.1
• Oracle 10.2 (requires the 10g or later JDBC drivers)
• H2 Database (ANSI mode)

Note that JAMWiki may work with any ANSI compliant database. Also note that to support double-byte charaters the database should use UTF-8 encoding. See Supported Configurations for additional configurations that have been tested with JAMWiki.

Installation Instructions

New Installs

Important: Do not use these instructions for upgrades, instead see the instructions below. Using the new installation process for an upgrade 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. (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.
4. (Optional) If using an external database verify that the JDBC driver is available in the web application server's classpath.
5. Update the org.jamwiki.pattern value in the logging.properties file with the location where log files should be written. The logging.properties 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.
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:

1. A directory (accessible to the application server) into which JAMWiki files can be written.
2. A directory (accessible to the web/application server) into which images and other files can be uploaded.
3. The relative path (with respect to the web/application server doc root) to the image upload directory.
4. The login and password of an administrative user.
5. (Optional) If using an external database for persistency then the database settings must be provided. See the Database Configuration section below for additional details.
6. (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 starting page, ready for use. If any problem occurs during installation that cannot be solved using information from this install guide please report it on Bug Reports and include any relevant information from your log files with the problem report.

Upgrades

IMPORTANT: The upgrade process will overwrite files that you have modified. You must backup any files from your /WEB-INF/classes/ that have been changed prior to upgrading.

In most cases upgrades can be handled using a mostly-automated wizard process. To upgrade using this automated process follow these steps:

1. Download the latest JAMWiki release from http://sourceforge.net/projects/jamwiki/.
2. The following files will need to be backed up from the webapp installation directory:
   1. /WEB-INF/classes/jamwiki.properties
   2. /WEB-INF/classes/logging.properties
   3. (Optional) The content found in the /upload/ directory. This step is necessary only if the default file upload directory is being used.
   4. (Optional) Any other files in the /WEB-INF/ directory that have custom modifications.
3. (Optional) Back up all database data prior to upgrading. This step is optional but highly recommended.
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.
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.
6. Restore the files that were backed up in steps two and three to their previous locations under the /upload/, /WEB-INF/ and /WEB-INF/classes/ directories, overwriting any new files.
7. (Optional) 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.
10. (Optional) 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 topic (for example: http://jamwiki.org/wiki/en/Special:History?topic=StyleSheet), selecting the pre-upgrade version, and then editing and saving that version.

If the upgrade fails see the UPGRADE.txt for instructions to manually upgrade. If the problem persists please report it on Bug Reports 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.

Troubleshooting

1. Check the log file for any error messages. The log file is set by the /WEB-INF/classes/logging.properties 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.

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.

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.

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.

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.

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.

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

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:

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

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.

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 Username: as appropriate
       Database Password: as appropriate

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: {{file|/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 {{file|/data/apache/htdocs/}} and your upload directory is {{file|/data/apache/htdocs/wikifiles/}} then the relative path to your upload directory would be {{file|/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.

Other Configuration Settings

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.

Fixing

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.

Attention

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!

See Also

• Configuration
• FAQ
• Supported Configurations
• Known Issues