Deploy and Configure the Geoportal Web Application in Tomcat
This page contain instruction for deploying and configuring geoportal application in Tomcat, deployment and configuration instruction are different for WebLogic or GlassFish; if you are using those environments, see the requisite installation guides for them available at Installation-Version-1.2.4.
This section assumes that:
- Apache Tomcat (6.x or later) is up and running, if you need to download and install Tomcat, please go to http://tomcat.apache.org
- There is a working geoportal database per documentation at Set up the Geoportal Database
The geoportal uses a Java Naming and Directory Interface (JNDI) key to connect to the database through a JDBC connection. This allows system components to find the database connection information using the JNDI key instead of having to store the JDBC connection information in many places.
1. Identify the jdbc .jar file that your geoportal's JNDI key will use for the database JDBC connection.
The database .jar file you use is determined by the database vendor and Java version you have running. Because Geoportal 1.0 and higher requires Java 1.6, make sure that your driver supports JDBC4. see below to identify recommended .jar files for your environment.
- Oracle (10g, 11g): ojdbc6.jar
- SQL Server (2005, 2008): sqljdbc4.jar
- Postgres (8.4, 9.1): postgresql-9.1-901.jdbc4.jar
- MySQL 5.5: mysql-connector-java-5.1.23-bin.jar or above
Database .jar files are typically provided with your database software, if you cannot find the .jar files that came with your database or need to get an updated version of the jar file, you can obtain them from the manufacturer's website.
2. Copy the database jdbc driver .jar to the \lib directory of Tomcat
3. Copy the geoportal.xml file to C:\\conf\Catalina\localhost folder
- Copy the geoportal.xml file from the \Other\JNDI Configuration\ folder and paste it into your C:\\conf\Catalina\localhost folder.
- If you are using Tomcat 6 and you don't have a Catalina\localhost directory in your conf directory, then you might need to create it.
- Open the geoportal.xml file in a text editor. Modify the properties specified in the table below, then save the file and close it.
<Context docBase="geoportal" path="/geoportal" debug="0" reloadable="true" crossContext="true">
<Resource name="jdbc/gpt" auth="Container" type="javax.sql.DataSource"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://db_server:5432/geoportaldb"
username="geoportal_user"
password="geoportal_user_pwd"
maxActive="20"
maxIdle="10"
maxWait="-1" />
</Context>| docBase | The name of your geoportal web application in Tomcat. Default: geoportal. Example: docBase="geoportal" |
| Path | The name of the geoportal application directory within Tomcat webapps. Example: path="/geoportal" |
| driverClassName |
The JDBC Driver class name. Vendor specific.
|
| url |
The JDBC URL connection string
|
| userName | geoportal database user. Example: username="geoportal", for Oracle ojdbc6.jar: user="geoportal" |
| password | geoportal database user password. Example: password="geoportalpwd" |
Note: Please verify the JDBC settings with official driver documentation found on your database vendor's website.
IMPORTANT: If you are using the ojdbc6.jar file and the configuration described above is not connecting the geoportal to your database, then try the configuration below in your geoportal.xml file. Users have reported that in some instances, this configuration is successful with the ojdbc6.jar file. You will need to change the type attribute, and add the factory attribute, as shown highlighted below:
<Resource name="jdbc/gpt" auth="Container"
type="oracle.jdbc.pool.OracleDataSource"
factory="oracle.jdbc.pool.OracleDataSourceFactory"
driverClassName="oracle.jdbc.driver.OracleDriver" This section deploys the geoportal web application. First you will deploy the geoportal.war file, and then you will configure its property file - gpt.xml - so the web application can successfully communicate with other components of your system.
1. Copy the geoportal.war file from the \Web Applications\Geoportal folder to your \webapps folder.
2. Check and verify a geoportal folder is created by Tomcat after a few moments
- Tomcat should automatically recognize the new war file and deploy it by creating a geoportal folder. If it does not, restart Tomcat.
1. Navigate to: \webapps\geoportal\WEB-INF\classes\gpt\config
2. Open the gpt.xml file in a text editor.
3. Update the gpt.xml file with only the essential configurations to run the geoportal web application.
If a setting is not mentioned in the table, it should be left with its default value. There are many other configurations available in this file for additional geoportal functionality. These are discussed in All gpt.xml file settings.
4. Find the section just after the 'Mail server configuration' comment and make necessary updates
This section defines the mail settings to determine who will receive feedback forms submitted from the geoportal application. It will also determine the return address for any email sent from the geoportal, such as password reminders. Set the following properties:
| smtpHost | smtp of your mail server |
| smtpPort | Port on which the mail server runs |
| siteEmailAddress | The email address of the person who is to receive feedback forms, and is the email address from whom email is sent out from the geoportal. |
| smtpAuth | Settings for username, password and whether the password is encrypted if the smtp server requires authentication |
The interactiveMap settings determine information about the map used on the search page, the geoportal online editor map, the view details map, and the preview map - they all use the same map service. Set the properties as per the table below. For properties not mentioned, leave the defaults already set in the file.
| jsapiUrl | URL to the ArcGIS Server JavaScript API. Default: http://serverapi.arcgisonline.com/jsapi/arcgis/?v=2.5 |
| mapServiceUrl | URL to a map service that is to be used for the geoportal map interfaces. Default Example: http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_Imagery_World_2D/MapServer. See documentation at Search-Map for more details and examples on configuring the map service. |
| mapVisibleLayers | An array of visible WMS layer names. This parameter should be defined only when WMS is used as a map service. Layer names are found in the <name></name> element of the WMS GetCapabilities xml. |
| mapServiceType | The type of map service. Note: the search map may not display tiled services correctly. For best results, set this to dynamic. |
| geometryServiceUrl | REST URL to a geometry service that is used to handle the projection of coordinates when using a projected map service. Default Example: http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer |
| locatorUrl | URL to an ArcGIS Server locator service, used for the find place functionality. Example: http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Locators/ESRI_Geocode_USA/GeocodeServer |
| locatorSingleFieldParameter | Parameter name associated with a single field locator. This is used for the place search function in the geoportal search page map. |
6. Configure Lucene index location.
The lucene settings contain information about the Lucene index. Lucene is the local indexing engine used by the geoportal for indexing published documents for fast retrieval in a search (see Using-Lucene-Search-Text-Queries for more information). IMPORTANT: You will need to create a folder to hold the index files. After creating a new folder and giving it a sensible name (e.g., lucene) set the following property:
| indexLocation | Absolute path to the folder that will hold indexed documents. This can be any path on your machine. Example: C:\lucene |
7. Configure user authentication.
The Geoportal Server offers two different authentication mechanisms: Simple Authentication or LDAP Authentication. Which one you select depends solely on your geoportal instance requirements. The table below gives a quick summary of features available in each option, followed by a more detailed explanation.
| Feature | Simple Authentication | LDAP Authentication |
| Single sign-on with other applications | X | |
| User roles | X | |
| User accounts/profiles | X | |
| LDAP software required | X | |
| Authentication configured in property file | X | |
| Quick installation | X |
Simple Authentication With simple authentication, there is only one user in the geoportal: the administrator. This user is specified in the main geoportal configuration file, gpt.xml. Choosing this authentication mechanism does not require any additional external software to be installed. Single sign-on between the geoportal and other applications is not possible. This mechanism is a quick option for initial application testing, but is not recommended for a production environment.
LDAP Authentication
For full functionality of user-based roles in the Geoportal Server, and to have the possibility of single sign-on with other applications, an LDAP-enabled Directory Server is required for the authentication mechanism. You may use an existing Directory Server if you already have one in your organization. If you currently do not have a Directory Server, and you wish to have user-based roles, and/or single sign-on, you will need to install a Directory Server. If you choose LDAP authentication for your geoportal instance, please see Connecting-to-a-User-Directory and ldap section within All-gpt.xml-file-settings).
A good approach is to first get basic geoportal up and running quickly by using the simpleAdapter, which will let you login as a single user and check most of the geoportal functionalities, then configure ldap if needed. To configure the simpleAdapter, just find simpleAdapter section and uncomment that section (and comment out the ldap section) for a basic geoportal. To configure ldap, comment out the simpleAdapter section and uncomment the LDAP section in gpt.xml and modify parameters for the ldap section (see Connecting-to-a-User-Directory and ldap section within All-gpt.xml-file-settings).
8. You are now finished configuring the geoportal web application for basic functionality. Save and close the gpt.xml file and restart geoportal.
If your geoportal will need to support searching multibyte characters - such as Chinese - then you must configure the Tomcat server.xml file to support UTF-8 character encoding. Below is a sample of how to make this change within Tomcat:
- Navigate to \Conf\ and open the server.xml file.
- Locate the section where Service name is set to Catalina and add text URIEncoding="utf-8" as below in the Connector element.
<Service name="Catalina">
<Connector connectionTimeout="20000" port="8080" protocol="HTTP/1.1" redirectPort="8443" URIEncoding="utf-8"/> - Save the file.