Configuration of ncWMS is normally performed by either accessing the administration web interface (http://serveraddress/ncWMS2/admin/) or by directly modifying
config.xml in the configuration directory. It is recommended to use the web interface - precise documentation of the XML configuration file is beyond the scope of this guide.
Once any changes have been made on this page, click the "Save configuration" button to apply them.
Additionally, adding datasets, removing datasets, and checking the status of a dataset can also be performed by submitting HTTP requests to an API endpoint.
Configuring datasets via the admin interface
On the admin page, new datasets can be added by filling in the information in the "Required Data" column of the Datasets section. All other fields are optional. Already-configured datasets can be modified here.
- ID: An alphanumeric identifier for the dataset. This must be unique on the server.
- Title: The title of the dataset. This is displayed in menus etc. on the user interface.
- Location: The location of the dataset. This should be either a location on disk or an OPeNDAP URL. Note that locations should use slashes - not backslashes - regardless of operating system. For example, on Windows a path such as
C:/Data/dataset.ncshould be used. If referring to a location on disk, glob expressions of the form
/mnt/data/dataset/**/**/*.ncare valid. If such an expression refers to multiple NetCDF files, they will be interpreted as having non-overlapping time axes. Any other configuration of data spanning multiple files is not supported, although ncWMS2 does have support for NcML for more complex aggregations. If you are using NcML, the .ncml file should be referenced in the location field.
- More Info URL: A URL containing more information about the dataset. This will appear when clicking the information button in the web interface.
- Copyright: The copyright information for the dataset. This will appear when clicking the information button in the web interface as well as on graphs generated by ncWMS.
Status information about the dataset will appear here
- Auto-refresh rate: Specifies how regularly the dataset will be scanned for changes
- Force refresh: By ticking this box and saving the configuration, the dataset will be refreshed immediately
- Disabled: Disables this dataset but keeps the configuration intact
- Queryable: Whether or not to allow GetFeatureInfo requests to this dataset
- Downloadable: Whether or not to allow data download for this dataset
Data reading class:
This is the Java class which should be used to read the data. This should be left blank to use the default gridded NetCDF data reader. ncWMS2 also provides the reader
uk.ac.rdg.resc.edal.dataset.cdm.En3DatasetFactory for reading data from the UK Met Office EN3/EN4 dataset (http://www.metoffice.gov.uk/hadobs/en4/). For custom data types you specify their class name here (see Development section for more information)
Tick this box to completely remove this dataset from the configuration
Managing datasets via the API
There are 3 methods for managing datasets using an API. All of them require digest authentication by a user with the
ncWMS-admin role (see here for further details).
removeDataset both require HTTP
POST requests, and
datasetStatus uses a
addDataset method is available at the path
http://localhost:8080/ncWMS2/admin/addDataset), and is accessed via a
POST method containing the following parameters:
id(MANDATORY) - the ID of the dataset to add
location(MANDATORY) - the location on the local filesystem or an OPeNDAP server. Note that the data must already be present on the server - this method does not provide a way to upload data to the server.
title- The title of the dataset. If not present, the ID will be used instead.
dataReader- The data reading class to use to load this dataset. If not present, the default data reader will be used.
moreInfo- A string providing further information about the dataset. Will be present on plots and available in the Godiva3 interface.
copyright- A string providing details of copyright about the dataset. Will be present on plots and available in the Godiva3 interface.
queryable- Should be
false. Whether this dataset should be queryable using
GetFeatureInforequests. If not present, defaults to
downloadable- Should be
false. Whether this dataset should be downloadable as CSV. If not present, defaults to
autoRefreshMinutes- How regularly to update this dataset, in minutes. If not present, the dataset will never automatically refresh.
Because adding a dataset has the potential to take a long time, the
addDataset method only performs a bare minimum of checks to ensure that the dataset is likely to be successfully added to the ncWMS server. If any of these checks fail, a suitable error message will be returned to the user. Otherwise, a successful message is returned, along with a URL at which to check the dataset status.
Example call to
curl --digest -u ncwmsadmin:adminpassword -d "id=hmgrid&title=Hydromodel Rectilinear&location=/mnt/data/RectilinearGrid/*.xml&dataReader=uk.ac.rdg.resc.edal.dataset.vtk.HydromodelVtkDatasetFactory" -X POST http://localhost:8080/ncWMS2/admin/addDataset
Dataset hmgrid (/home/guy/Data/hh/RectilinearGrid/*.xml) is being added. Check the status at http://localhost:8080/ncWMS2/admin/datasetStatus?dataset=hmgrid
removeDataset method is available at the path
http://localhost:8080/ncWMS2/admin/removeDataset), and is accessed via a
POST method containing a single parameter:
id(MANDATORY) - the ID of the dataset to remove
The method will remove the dataset from the catalogue and immediately return with a message confirming that the dataset has been removed.
Example call to
curl --digest -u ncwmsadmin:adminpassword -d "id=hmgrid" -X POST http://localhost:8080/ncWMS2/admin/removeDataset
Dataset hmgrid has been removed.
datasetStatus method is available at the path
http://localhost:8080/ncWMS2/admin/datasetStatus), and is accessed via a
GET method containing a single parameter:
dataset(MANDATORY) - the ID of the dataset to check on.
This will return the status of the dataset, along with any error messages encountered when loading the dataset. This is the same method accessed from the admin web interface when clicking on a dataset status link. This method can respond in either
text/plain, depending on the value of the
Example call to
curl -H "Accept: text/plain" --digest -u ncwmsadmin:adminpassword -X GET http://localhost:8080/ncWMS2/admin/datasetStatus?dataset=hmgrid
Dataset: hmgrid (/home/guy/Data/hh/RectilinearGrid/*.xml): READY
Once a dataset has been added, a link will appear in the "Edit variables" column. By clicking this, all of the variables within the dataset can be individually configured. The properties which can be adjusted are:
- Title: The title of the variable to appear in menus / the capabilities document
- Default colour scale range: This is the value range which the data covers. When a dataset is added, this is populated with a range based upon a small sample of the data
- Default palette: The name of default colour palette to use. Available palettes can be browsed in the Godiva interface by clicking on the colour bar. The names of the palettes can be found by hovering over them.
- Default number of colour bands: The number of gradations of colour to use when plotting the variable. Must be between 2 and 250.
- Default scaling: Whether to plot data on a linear or a logarithmic colour scale.
Dynamic services are equivalent to datasets but are not pre-indexed. This allows users to access potentially very large numbers of files without having to configure them. An explanation of dynamic services is provided on the administration interface and their configuration is very similar to that of standard datasets.
Other server settings
To increase speed, ncWMS uses a cache of recently-extracted data. Enabling/disabling the cache can be done here, as well as configuration of how much memory the cache is allow to consume. The higher this is, the more features will be cached.
- Title: The server name, which will be the title of the Godiva interface, and will also appear in the capabilities document
- Abstract: Description of the purpose of this server - appears in the capabilities document
- Keywords: Keywords describing this server - appear in the capabilities document
- URL: A URL of the service provider - appears in the capabilities document
- Max image width: The maximum allowable width (in pixels) which can be requested in a GetMap call
- Max image height: The maximum allowable height (in pixels) which can be requested in a GetMap call
- Allow GetFeatureInfo: This can be used to disable GetFeatureInfo requests globally on the server. If this is enabled, individual datasets can still have GetFeatureInfo disabled using the "Queryable" option
- Allow global capabilities: Allows clients to request a WMS Capabilities document including all datasets on the server
This configures the contact information which will appear in the capabilities document
Whilst Godiva3 does not generally need configuring, there are a a few options which can be configured. This configuration is done though a simple .properties file, named
godiva3.properties which is stored in the ncWMS2 configuration directory. For convenience, this file is created with default settings the first time ncWMS is run, but can of course be created prior to running ncWMS for the first time.
godiva3.properties file can contain the following entries:
mapHeight- This must be an integer and is the height, in pixels, of the main map in Godiva3
mapWidth- This must be an integer and is the width, in pixels, of the main map in Godiva3
proxy- This is a string containing a proxy URL through which all requests will be made. Request URLs are appended to the end of this proxy URL prior to being made, so any required parameters must be included in it.
This config file can also be used to define new base layers and overlays in addition to the defaults. Base layers can be used as background maps and will always appear underneath ncWMS layers, whereas overlays are designed to be overlaid (as the name suggests) and will always appear above ncWMS layers. Each user-defined layer requires several parameters, and this grouping is defined by a common ID prefix. It is not important what this is, so long as it is common to all parameters. For example, the parameters
mylayerTitle both refer to the same layer, whereas
yourlayerURL refers to a separate layer. The available parameters are:
xxxURL- The URL of the WMS server. This should contain the WMS URL including the final query separator (usually
?). This is because some WMS servers may require default options (e.g.
xxxLayers- A comma-separated list of layers to plot.
xxxTitle- The title to display in the layer switcher. If missing, it will default to the layer ID (
xxxin this case)
xxxProjection- The projection of the layer. If missing, defaults to
CRS:84. Note that although this is mostly equivalent to
EPSG:4326, it is not supported by all servers. It is generally preferred to
EPSG:4326since this latter is handled differently by WMS versions
1.3.0. Supported projections are
xxxVersion- The WMS version to use. Defaults to
xxxFormat- The image format to use. Defaults to
xxxOnByDefault- Whether this layer should be visible on first load. For overlays, any number can be visible initially. For base layers, only one layer may be selected on load. If multiple base layers have this parameter defined as
true, then one of them will be the default layer (but which one it will be is undefined behaviour).
xxxIsOverlay- Whether to use this as an overlay (as opposed to a base map). Defaults to