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.
/WEB-INF/classes/logback.xmlfile and change the
LOG_DIRvalue to point to a directory on your server where logs should be placed.
See the long version below for more detailed instructions.
jamwiki.propertiesfile from your old install to your new install (note: this step is optional for users of JAMWiki 1.2 and later).
jamwiki.propertiesin step 6 then you will first need to provide setup information, and will then be asked if you would like to perform an upgrade.
See the long version below for more detailed instructions.
JAMWiki requires a web application server (such as Tomcat >= 6 or Websphere) that supports the following specifications:
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:
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.
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:
LOG_DIRvalue in the
/WEB-INF/classes/logback.xmlfile 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.
The configuration process begins automatically with the first JAMWiki pageview after setup. Configuration will request the following information (see below for details):
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.
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:
TOMCAT_HOME/webapps/wikifolder and the
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.
Users who want to migrate an installation from one machine to another have two options:
/WEB-INF/classes/jamwiki.propertiesfile 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
Note that backups of the webapp and the database should be performed prior to any migration to ensure that no data is lost.
/WEB-INF/classes/logback.xmlfile and by default write to the
jamwiki.log.0file in the application server's temp directory.
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.
1. tar xvzf jetty.tar.gz 2. cd jetty 3. cp jamwiki.war webapps/ 4. mkdir work 5. java -jar start.jar 6. Done !!
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.
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.
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.
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:
<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.
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.
Installation of JAMWiki on OAS requires that the JAMWiki WAR file be deployed using "Oracle Application Server Control" or "OPMN Command Line".
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.
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:
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:
createdb -E UTF8 database-name
create database database-name 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
dbinit -b -z UTF8 database-name
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.
Note that software versions may vary, this account specifies a specific setup that worked for one user.
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:
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
JAMWiki runs just fine unless you try to resize an image in the image tag with
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!
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>