
	News \| FAQs \| Contacts

WebMap Composer Product Home

	Requirements
	Install Note
	Release Note
	Configuration

WebMap Composer 1.0.3 Install Note

31 January 2003
Last updated 10 Nov 2003

This note is for customers wishing to install Web Map Composer (WMC) 1.0.3, obtained by download. It describes how to deploy WMC to the Open Source Tomcat application server.

WebMap Composer is packaged as a standard WAR (Web application ARchive) file. The WAR file can be deployed on most J2EE application servers by simply copying it to an appropriate location.

Do not use the WAR file to upgrade an existing installation, please contact Social Change Online. Additional documentation and automation of upgrade processes is under development.

Requirements

WMC 1.0.3, build r1_43stable, has been tested on Windows 2000, XP and Red Hat Linux 8.0 platforms with IE 6 SP1 and Netscape 4.7 browser clients. Anecdotally, Netscape 7+ and Mozilla 1.2.1+ have been found to function successfully. Note that Netscape and Mozilla browsers require a Java plugin when a locator map is used in a layout. In addition to the WMC WAR file you will need:

Sun Java 2 Platform, Standard Edition, version 1.3.1_06, or higher, eg 1.3.1_09
Apache Jakarta Tomcat 4.1.27 (Open Source Java Servlet / JSP application server)

Although release testing took place with Tomcat 4.1.18, we recommend the later version of tomcat for security reasons. Please note that the version of WMC, Tomcat and the Java Platform (JDK) are interdependent. Whilst many combinations work, some need patching or workarounds, and WMC is not guaranteed to work with older or newer Tomcats / JDKs.

Network Proxies
WebMap Composer must have a clear path to the internet if you want to access services on the internet. The current release cannot be configured to work with a proxy server (the restriction is due to past experiences with caching proxy servers).

Installation

1. Java 2 Platform Installation

Download the full SDK from the link above

Install as per Sun instructions and follow the quick test below

Note: $JAVA_HOME refers to the location where you have installed the Java SDK, eg C:\apps\java\sdk\j2sdk1.3.1_06

Open a command prompt / console window

cd $JAVA_HOME

Type java -version (windows) or ./java -version (linux), you should see something similar to:

java version "1.3.1_06"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_06-b01)
Java HotSpot(TM) Client VM (build 1.3.1_06-b01, mixed mode)

2. Tomcat Installation

Download and unpack Tomcat to a folder

Note: $TOMCAT_HOME refers to the location where you have installed Tomcat, eg C:\apps\Apache Group\jakarta-tomcat-4.1.18

Set $JAVA_HOME

Either set system wide variables (eg in Windows via the Control Panel/System) or directly edit the Tomcat startup scripts:

Edit $TOMCAT_HOME/bin/startup.bat and $TOMCAT_HOME/bin/shutdown.bat. Immediately after the header comments add the line:

set JAVA_HOME=<$JAVA_HOME>
eg set JAVA_HOME=C:\apps\java\sdk\jdk1.1.1_06

On Linux/Unix, edit the equivalent .sh scripts, using
JAVA_HOME=C:\apps\java\sdk\jdk1.1.1_06; export JAVA_HOME

Evidently these are the files that should be used to start and stop Tomcat.

Increase the tomcat memory allocation

Edit $TOMCAT_HOME\bin\startup.bat and insert or alter the line below, substituting for (max heap):

set CATALINA_OPTS="-Xmx(max heap)m"

eg to set max heap to at 128 megabytes (minimum recommended), use
set CATALINA_OPTS="-Xmx128m"

On Linux/Unix, edit the startup.sh script and use
CATALINA_OPTS="-Xmx128m"; export CATALINA_OPTS

In a heavy concurrent user environment, it may be necessary to increase this setting.

Remove activation.jar

Delete or rename activation.jar in $TOMCAT\common\lib.

Note! If activation.jar is renamed, make sure to change the .jar extension, eg to activation.jar.4.1.18, otherwise it will still load and no maps will appear.

Copy wmc.war to Tomcat

Make sure Tomcat is not running
Copy any customised files and saved applications. (See the FAQs to see which files are safe to customise)
Remove the directory $TOMCAT_HOME\webapps\wmc if it exists
Copy wmc.war to $TOMCAT_HOME\webapps
Reinstall any customised files

Note! Always use this procedure if you ever need to replace a wmc.war file.

To deploy the war file to a location other than $TOMCAT_HOME\webapps, please click to find out more

3. Start Tomcat

Start Tomcat using the appropriate startup script. On Windows, after a pause whilst the war file is deployed, you should something like

31/01/2003 15:36:34 org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/30 config=C:\apps\Apache Group\jakarta-tomcat-4.1.
18_jdk1.3.1_06\bin\..\conf\jk2.properties

If not, then it is most likely that the $JAVA_HOME variable is wrong or some other process is using the default Tomcat 8080 port. The port assignment may be changed by editing port="8080" in $TOMCAT_HOME\conf\server.xml

Point your web browser to http://localhost:8080, you should see the Tomcat default page and be able to run the servlet and JSP examples provided.

Next, assuming success, point your web browser to http://localhost:8080/wmc

After a short pause, you should see the WMC login page. Press login and investigate some of the published applications. This is a good time to review the release note for known limitations.

Note! The first application may take up to a couple of minutes to load whilst JSP pages are compiled. After this you should experience much faster performance. Expect this to happen whenever a new war file is deployed. Also, a delay will be experienced by whoever loads the first application following a Tomcat restart. This is partly because Tomcat caches servlets and partly because WMC is a sophisticated middleware system that caches service metadata to improve performance.

The password for creating views and applications is wmc_a. See the note below on how to change this.

Of course it should be possible to view WMC applications from any web browser accessing the Tomcat server, eg http://{tomcat_host}:{tomcat_port}. If not, the Tomcat port is likely tied down by a firewall (possibly on the Tomcat server).

Post Install

Apply Service Pack 1

Please download and apply Service Pack 1. A readme.txt within the service pack zip file explains how to apply the patch. The service pack addresses a previous packaging error: a saved view called "default" referenced a gazetteer not included in the war file - resulting in a servlet exception when using the view.

Change Password

(This procedure will be improved in the next WMC release)

Edit the $WMC_HOME/login_validate.jsp file ($WMC_HOME is location of where the wmc application has been installed)

Change the following for the Application Publisher
from
static final String COMPOSER_PASSWORD="wmc_a";
to
static final String COMPOSER_PASSWORD="$yourpassword";
Where $yourpassword is the password you have chosen

Change the following for the Map data publisher
from
static final String VIEWPUBLISHER_PASSWORD="wmc_p";
to
static final String VIEWPUBLISHER_PASSWORD="$yourpassword";
Where $yourpassword is the password you have chosen.

view Support Documents by category