The root of the tomcat installation is referred to as "${catalina.home}" and will be used from here. The root of a tomcat installation can be recognized by the webapps and conf directories.

It is recommended to give a tomcat a heapsize of at least 1GByte, but preferably more. This can be done using the -Xmx1024m java argument. Since 2019.02 the FEWS Web Services won't start if there is not enough memory available.  For general instructions on installing tomcat, see also: Delft-FEWS Installation - Install Apache Tomcat.

FewsWebServices.war installation

The FEWS Web Services are packaged in a file called the FewsWebServices.war. Before installation, make sure the tomcat server has been shutdown. Inspect the ${catalina.home}/webapps folder and inspect if there is a FewsWebServices folder. If this folder exists, delete the ${catalina.home}/webapps/FewsWebServices folder. The FewsWebServices.war file has to be copied to the ${catalina.home}/webapps folder.

Web Services log files

After upgrading the FewsWebServices.war, old log files have to be deleted. The log files are stored in: ${catalina.home}/fews/Region_Home folder. All *.txt files should be deleted.

<?xml version="1.0" encoding="UTF-8"?>
<clientConfiguration xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd">
    <connection id="Database" name="Database">
        <databaseServer>
            <url>FEWS_DATABASE_URL</url>
            <user>dummy_username</user>
			<encryptedPassword>dummy_password_encrypted</encryptedPassword>
        </databaseServer>
    </connection>
</clientConfiguration>

Cache configuration

Since 2020.02 it is possible to use the localCacheSizeMB in the clientConfig.xml to tune the amount of in memory caching the PI service is allowed to do. This can be quite useful for performance tuning when using seamless integration with the archive.

This setting was already available to the Operator Client and Forecasting Shell Servers. If not configured a default cache size of 500MByte will be used.

See also: 08 Root Configuration Files for Operator Client and Forecasting Shell Servers

Configure Database connection over Active Directory

When using MS Sql Server it is possible to connect to the database through Active Directory. This can be configured by updating the client configuration file (see example below). 

• remove user
• remove encryptedPassword
• extend URL by adding integratedSecurity=true
  

Furthermore it is necessary to copy sqljdbc_auth.dll  to the Tomcat/bin folder. This can be found here:

• 2020.02 and earlier: from the Master Controller build/lib folder installation
• 2021.01 and later: Delft-FEWS bin folder

<?xml version="1.0" encoding="UTF-8"?>
<clientConfiguration xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd">
    <connection id="Database" name="Database">
        <databaseServer>
            <url>FEWS_DATABASE_URL;integratedSecurity=true</url>
        </databaseServer>
    </connection>
</clientConfiguration>

FewsPiService.properties

The FEWS Web Services have a custom property file that can be used to make service specific configurations available. This is a property file that is located in the FEWS configuration in the directory:

%REGION_HOME%/Config/PiClientConfigFiles/FewsPiService.properties

For more information about the possible properties, see FEWS Web Services Configuration FewsPiService.properties (- deprecated since 2022.02). 

Global Properties

In case global properties are needed by the FEWS Web Services, a global.properties file can be put in the Region_Home directory as well. If the same global.properties is available in the RootConfigFile in the FEWS configuration, the properties will be overwritten by the one in the FEWS database. 

Index Files

Since 2018.02 the FEWS Web Services will not startup before an index file is available in the Database. Index files are created automatically by Forecasting Shells. This means that the FEWS Web Services will only start if a running Forecasting Shell is available on the live system.

The FewsWebServices will be available at http://localhost:8080/FewsWebServices01/. For multiple configurations more context xml files can be created with custom ENV variables.

Advanced Installation and Configuration (Since 2020.02)

Since 2020.02 multiple FewsWebServices are supported in the same tomcat by specifying the ENV_PREFIX servlet context variable. The prefix is used to resolve the FewsWebServices specific environment variables. If not set, the ENV_PREFIX defaults to FEWS_WS_ .

For example if multiple FewsWebServices are deployed in the same tomcat, multiple Context.xml configurations can be configured with different prefixes.

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="${catalina.home}/fews/FewsWebServices.war">
    <Parameter name="ENV_PREFIX" value="FEWS_WS_01_" override="false"/>
</Context>

Using this configuration the web service will now expect the following ENV variables to be available:

FEWS_WS_01_DATABASE_URL=jdbc:postgresql://dummy_hostname:6001/dummy_databasename
FEWS_WS_01_DATABASE_USER=dummy_username
FEWS_WS_01_DATABASE_ENCRYPTED_PASSWORD=dummy_password_encrypted
FEWS_WS_01_CLIENT_CONFIG_FILE_NAME=ws_clientConfig.xml
FEWS_WS_01_HOME=d:\fews-ws\region-home-01
FEWS_WS_01_CLIENTCONFIGFILEID=FewsPiService01.properties

The FewsWebServices will be available at http://localhost:8080/FewsWebServices01/. For multiple configurations more context xml files can be created with custom ENV variables.

Advanced Installation and Configuration (Before 2020.02)

In some cases it may be required to support different FewsPiService.properties on the same database, for example to support different default filters. In this case and advanced installation of the FEWS Web Services is required that is similar to installations before 2017.02. 

 The FewsWebServices.war file should be put in the ${catalina.home}/fews folder, instead of the ${catalina.home}/webapps. 

In the ${catalina.home}/conf/Catalina/localhost folder a context.xml should be created where a specific client config file id can be configured. In this xml file a reference to the FewsWebServices.war file should be made and a reference to the property file to be used.

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="${catalina.home}/fews/FewsWebServices.war">
    <Parameter name="clientConfigFileId" value="FewsPiService01.properties" override="false"/>
    <Parameter name="regionHome" value="${catalina.home}/fews/Region_Home01" override="false"/>
</Context>

The FewsPiService01.properties is expected to be in:

%REGION_HOME%/Config/PiClientConfigFiles/FewsPiService01.properties

Using this configuration the web service will now be available at http://localhost:8080/FewsWebServices01/. For multiple configurations more context xml files can be created.

Testing

The FEWS Web Services come with a testing page that can be accessed at: http://localhost:8080/FewsWebServices/. This leads to an overview page with links to test pages for the different services (SOAP, REST, WaterML, Digitale Delta). You can find more on how to configure the different services on 18 FEWS data exchange interfaces.

See.  For general instructions on installing tomcat, see also: Delft-FEWS Installation - Install Apache Tomcat.

Migrating from before 2017.02