Howto : GI-cat installation

GI-cat comes in two flavours:

• an automatic installation package, designed to quickly setup a fully functioning GI-cat server demo on your Desktop machine (details in the following sections)
• a .war package version, especially suited for a server installation (refer to the .war package installation guide below)

Auto installer package

The automatic installer is available for: Windows, Linux, MacOS.

Installing on Windows

• Download the windows auto installer file from the Download page

• Double click on the auto installer file, and complete the installation following the installation wizard (a guide is available).

• After a successfull installation, GI-cat will be installed in the directory of your choice and GI-cat manager will be displayed on your taskbar notification area.

GI-cat manager

• GI-cat manager is the GI-cat administration tool (used to start, stop and configure GI-cat). It is accessible through the notification area with the GI-cat logo, and it will automatically start with Windows.

• If you exit from GI-cat manager, you can start it again clicking the menu entry "GI-cat manager" in the startup menu folder "GI-cat server".

Server Start Up

• To start the server, right click on the GI-cat manager icon and select "Start GI-cat".

• A red icon suggests that GI-cat server is up and it is correctly working.

Server Stop

• To stop the server, right click on the GI-cat manager icon and select "Stop GI-cat".

• A gray icon suggests that GI-cat server is down and it is not working.

Configuration

• To configure GI-cat with GI-conf, select "Configure" from the GI-cat manager entries.

A new web tool for GI-cat configuration is now available, directly from the GI-cat welcome page after a successful installation.

Other Funtionalities

• Furthermore you can see the server logs selecting "Show logs" and also visit the running instance homepage selecting "Welcome page".

Installing on Linux

• Download the linux .tar.gz package from the Download page

• Open the console and move to the download directory

• Decompress the downloaded file with tar zxvf GI-cat-linux-autoinstaller.bin.tar.gz

• Execute the decompressed binary file with: ./GI-cat-linux-autoinstaller.bin

• Complete the installation using the wizard (a guide is available).

• After a successfull installation GI-cat will be installed in the directory of your choice. There you can also find the scripts needed to start and stop the service. (If you have Ubuntu the GI-cat manager can also be installed and used to administrate GI-cat. Refer to the Windows guide for information on the GI-cat manager).

Post Installation Check

• Point your browser to the GI-cat installation endpoint, chosen during the graphical installation. A welcome page should appear. Default URL is http://localhost:8090

Server Start Up

To start the server:

• Open the console and move to the installation directory.

• Type ./GI-cat start

Server stop

To stop the execution of the server

• Open the console and move to the installation directory.

• Type ./GI-cat stop

Configuration

Start GI-conf, by clicking on the menu entry from the application menu.

Alternatively you can start it in this way:

• Open the console and move to the installation directory.

• Type ./configure_service.sh

A new web tool for GI-cat configuration is now available, directly from the GI-cat welcome page after a successful installation.

More information on GI-conf in the GI-conf manual.

Installing on MacOS

• Download the MacOS X package from the Download page.

• Double click on the downloaded file to decompress it.

• Double click on the GI-cat-X.X-osx-autoinstaller file.

• The graphical installer appears: follow the installation wizard (a guide is available).

• After a successfull installation GI-cat will be installed in the directory of your choice. In that directory you will also find the scripts needed to start and stop the service.

Post Installation Check

• Point your browser to the GI-cat installation URL, chosen during the graphical installation. A welcome page should appear. Default URL is http://localhost:8090

Service Start Up

To start the service:

• Open the console and move to the installation directory.

• Type sudo start_service.sh

Alternatively you can start GI-cat trough the launchd framework with the command:

sudo launchctl start it.cnr.imaa.essi.gicat

Service Shut Down

To stop the service execution:

• Open the console and move to the installation directory.

• Type sudo start_service.sh

Alternatively you can stop GI-cat trough the launchd framework with the command:

sudo launchctl stop it.cnr.imaa.essi.gicat

Configuration

To configure the GI-cat service you can use GI-conf. You can find GI-conf in your Applications directory.

A new web tool for GI-cat configuration is now available, directly from the GI-cat welcome page after a successful installation.

Installation Wizard

The wizard steps are hereafter described.

• License agreement

You need to accept the license agreement in order to continue the installation.

• Installation folder

GI-cat must be installed in a new folder. A warning will inform you if you choose an existing directory. The folder will contain all the files needed to start the application, except for the start menu links and the internal db data (by default stored on the home folder under the directory .exist: use the configurator to change it later).

• Hostname setup

In order to make GI-cat accessible through the Internet, you need to provide the hostname or the public IP address of your machine (you can put localhost in case you don't wish to publish any interfaces).

If you don't know your machine hostname, consult the automatic resolver and copy and paste the displayed hostname (it should be something like myserver.mydomain.org).

Alternatively (as in the case your machine is not registered to a DNS) you can provide the public IP address. If you don't know it, you can again consult the automatic resolver and copy and paste the displayed IP address (it should be something like 150.217.48.150).

• Port number setup

The service port number is used by GI-cat to receive requests headed for the published interfaces.
The port number must be an integer from 1025 through 65535 and it must be a free service port number (no other service should already use that port number) .

The predefined port number 8090 in the "Port number" field is recommended if you are unsure.

A warning message will inform you if the selected port number is already in use by another service.

• Authentication password

The authentication password is used to configure GI-cat with the GI-cat graphical configurator: GI-conf

.war package

Installation

The GI-cat .war package is ready to be deployed on a web container, such as Apache Tomcat.
The following sections will guide you through the installation steps. Please note that these instructions refer to version 6 and 5 of Apache Tomcat.

Tomcat installation (on Linux)

Apache Tomcat 6 or 5.5 are suggested, running on Java 6 (with the latest update) as web container. On a Linux Debian system type the following commands to install tomcat version 6:

#apt-get install tomcat6
#apt-get install tomcat6-admin
#apt-get install tomcat6-common

or the following, in case of version 5:

#apt-get install tomcat5.5
#apt-get install tomcat5.5-admin
#apt-get install tomcat5.5-webapps

#/etc/init.d/tomcat6 start

or, in case of version 5:

#/etc/init.d/tomcat5 start

(To improve the security level of your tomcat you may need to modify the configuration file tomcat-users.xml found in the configuration directory (usually /etc/tomcat6/ or /var/lib/tomcat5.5/conf) : it allows to modify user privileges and add/remove tomcat users). After a successful installation you should see the tomcat home page at the URL http://localhost:8080

Be sure to start tomcat with a Java Sun Virtual Machine version 6 (latest update): you can check the JVM version from the Tomcat Manager page at http://localhost:8080/manager/html (on the bottom).

A problem could rise by executing tomcat with low memory. Be sure to modify the tomcat startup file (/etc/init.d/tomcat6 or /etc/init.d/tomcat5) appropriately. The following parameters should be present in the variable CATALINA_OPTS -Xms1024m -Xmx1024m -XX:PermSize=1024m -XX:MaxPermSize=1024m

GI-cat needs also to have write and read permissions granted. This is used to store the configurations and data. Add the following lines to the grant section of your catalina.policy or policy.d/04webapps.policy file:

permission java.security.AllPermission;

• Hostname setup

The Endpoint configuration can be changed from the Global Settings page of the configurator.

In order to make GI-cat accessible through the Internet, you need to provide the hostname or the public IP address of your machine (you can put localhost in case you don't wish to publish any interfaces).

If you don't know your machine hostname, consult the automatic resolver and copy and paste the displayed hostname (it should be something like myserver.mydomain.org).

Alternatively (as in the case your machine is not registered to a DNS) you can provide the public IP address. If you don't know it, you can again consult the automatic resolver and copy and paste the displayed IP address (it should be something like 150.217.48.150).

Tomcat installation (on Windows)

Apache Tomcat 6 or 5.5 are suggested, running on Java 6 (with the latest update) as web container. The following instructions assume Tomcat 6 is chosen.

Download the Windows installer from http://tomcat.apache.org/download-60.cgi. After a successful installation you should see the tomcat home page at the URL http://localhost:8080. Be sure to start Tomcat on a Java Sun Virtual Machine version 6 (latest update): you can check the JVM version from the Tomcat Manager page at http://localhost:8080/manager/html (at the bottom).

Memory performance settings

If Tomcat cannot start, look in the /logs directory for error messages, or try launching Tomcat from the command line.
If the logs report "heap overflow" or other messages related to lack of memory, than the following Tomcat JVM memory settings must be configured (for example from the Tomcat tray icon): -Xmx512m
Should the memory problems persist, add the following settings: -XX:PermSize=512m -XX:MaxPermSize=512m

GI-cat deployment

From the Tomcat Manager page at http://localhost:8080/manager/html you can view the list of the deployed web applications. From this page you can stop or restart a given web application and also deploy a new one. Use the WAR file to deploy section to deploy GI-cat: select the GI-cat WAR file and click deploy. Direct your browser at the URL http://localhost:8080/gi-cat/. The GI-cat welcome page should appear after a successful deploy.

Known compatibility issue with GI-cat and eXist deployment on Tomcat ( only for version 6.0.4 and previous versions ).

Please refer to this section of the F.A.Q.

Known compatibility issue with GI-cat and deegree services deployment on Tomcat

Please refer to this section of the F.A.Q.

Password

Since version 7.0 the password for configuring GI-cat can be changed using the GI-conf tool. After deploying GI-cat on a web container such as tomcat, you must run the configurator. The first time you connect to GI-cat, the password is topsecret. You can change it, by selecting "Settings > Change Password" from the GI-conf menu.

Post installation configurations

The GI-conf tool is the recommended tool for GI-cat customization. It can be used with a modern web browser through the GI-cat welcome page. The following sections explain further customizations not achievable with GI-conf.

Customizing the Capabilities document

You need to modify the two templates included in sdi-profiler-cswcore-[version].jar and sdi-profiler-cswiso-[version].jar, called GetCapabilities^?.xml and ISOGetCapabilities^?.xml

Customizing the home page

It is possible to customize the home page title, subtitle and logo from the GI-conf.

To achieve further customizations the file to modify is index.jsp in the application main folder.