wiki:DownloadPage
Last modified 5 weeks ago

Downloading and installing ncWMS

* IMPORTANT *: before downloading and installing this software you must read the LicencePage.

System Requirements

  • Java runtime environment version 1.6 or above
  • Java application server, such as Tomcat (version 6 or 7 are recommended)
  • Access to local NetCDF dataset(s) or OPeNDAP server(s).

Please join the Users mailing list (ncwms-users@…) by filling in  this form. If you have any problems/comments/requests for features please report them via this list.

Downloading the software

The current version of the software is 1.0RC3. This is a Release Candidate, which means that some bugs may still be present, but no new features will be added before the full release. If you find a bug, please report it to ncwms-users@….

The software is packaged as a single WAR (Web ARchive) file. Download it from Sourceforge here:  http://sourceforge.net/projects/ncwms/files/ncwms/1.0RC3/ncWMS-1.0RC3.war/download.

If you would like to build ncWMS from source, please see the BuildInstructions.

Installation

Installation of the software is very simple: deploy the WAR file, then use the administrative web application to configure the server:

Deploy the WAR file

Follow the instructions of your application server for deploying a WAR file. For example, in Tomcat, simply copy the WAR file to the webapps/ directory. Tomcat will automatically extract and deploy the archive.

Note that you might have to set your application server to run "headless" under a Unix-like system. You might also want to increase the memory available to the app server. To achieve this in Tomcat, edit $CATALINA_HOME/bin/catalina.sh and add the line JAVA_OPTS="-Xms512M -Xmx512M -Djava.awt.headless=true" (this increases the memory available to 512MB, you might want even more if you have lots of datasets).

Quick test

Open your browser at http://<myhost>:<myport>/ncWMS/ (e.g. http://localhost:8080/ncWMS). You should see a page that looks like  this, but your page will not have any useful information on it yet because you haven't added any datasets.

Configure the server using the administrative web page

From the above test page, click on "Admin interface". You will be prompted for a username and password: enter "admin" for the username and "ncWMS" for the password (without the quotes). See below for instructions about how to change the admin password. You should see a page with a set of tables for you to fill in. The most important of these is the Datasets table (you can fill in the Server and Contact information if you like too).

To add a dataset to the ncWMS server, fill in a row of the datasets table. Pick anything for the Unique ID (this is just an internal reference) and give the dataset a title. This title will appear on the web interface and in GIS clients so make it meaningful. Then enter the location: this can be:

  • A single NetCDF file (e.g. /path/to/myfile.nc) - remember to enter the full path
  • An  NcML file (NcML is used for aggregation and to add or alter metadata in NetCDF file headers)
  • A set of NetCDF files (e.g. /path/to/*.nc, /path/to/Mydata*.nc or /path/to/*/200?/*.nc).
  • An OPeNDAP address (e.g. http://myserver:8080/thredds/dodsC/adataset.nc). NOTE: The generation of images from an OPeNDAP server may be significantly slower than from local files. This will be particularly apparent for large or high-resolution datasets. If you notice poor performance over OPeNDAP, consider installing the data on a disk that is local to your ncWMS server.

NOTE: paths to local files (single files, NcML files or glob expressions) are always case-sensitive, even under Windows.

You can enter up to three new datasets at a time. To add more than three, you must click "Save Configuration", then you can add more. If you have a sequence of OPeNDAP URLs that you'd like to view as a single dataset in ncWMS, construct an NcML aggregation for these URLs or see the FrequentlyAskedQuestions.

Click "Save Configuration". The metadata from these datasets will be harvested. If all goes well, the State of each dataset will change to READY (you'll need to refresh your browser). If the State shows ERROR, click on the word ERROR and see if the problem is something obvious, like a mistyped file location. If you don't understand the error message, please report it to the users mailing list ( ncwms-users@lists.sourceforge.net).

Controlling the default style for variables

Upon loading a dataset, ncWMS will automatically harvest metadata required for displaying its variables. It will automatically select a title (display name) for each variable, and choose a default colour scale range and palette. These can be overridden if required. On the admin page click on "edit" in the "Edit variables" column for a dataset. You will be presented with a page that allows you to edit the attributes of the variables in the dataset, including the title, the default colour scale range (i.e. the range of values used at the extremes of the colour scale), the default palette and default scale spacing (linear or logarithmic). These values are saved to the configuration file (see below) so they persist between server reboots.

Customize the Godiva2 menu

See CustomizingGodivaTwo.

(Advanced: configure the server manually by editing the configuration file)

The configuration information is stored in an XML file in $HOME/.ncWMS (which can be found in /private/var in Mac OSX). You can edit the configuration information manually if you wish. Currently this is the only way to change the admin password. If you edit the config file manually (i.e. not through the web interface) you will have to restart the server (unfortunately). NOTE: It is highly recommended to stop the server before making changes to config.xml, to avoid the possibility of corrupting the config file through conflicts with background server processes that also write to the file.

(Advanced: changing the location of the configuration information)

By default, ncWMS stores configuration information in $HOME/.ncWMS. By storing the configuration information separately from the application server, ncWMS can remain portable between different app servers and users can upgrade or change their app server without deleting ncWMS's configuration information. The real location of the configuration directory is platform-dependent ($HOME is found by Java using the system property user.home). If you don't want the config information to be stored in $HOME/.ncWMS, you can change this location by editing WEB-INF/WMS-servlet.xml: change the workingDirectory property of the ncwmsContext bean.

Test

Open your browser at http://<myhost>:<myport>/ncWMS/. You should see a page that looks like this:  http://behemoth.nerc-essc.ac.uk/ncWMS. This page contains links to the Capabilities document and example links to produce maps. Click on these links to make sure everything is working. If you get error messages, check your configuration file. If you find an error that you can't fix, please let us know:  ncwms-users@lists.sourceforge.net.

If the test links work, click on the link "Godiva2 interface" to get a dynamic web page for exploring your data, like this:  http://www.reading.ac.uk/godiva2. As the LicencePage states, if you wish to use this web interface to display your data, you must not remove the logo of the Reading e-Science Centre: otherwise, you may customize this page as you wish.