TopCAT - TopCAT Installation

Compatibility

TopCAT will work with ICATs with version of 4.3 or greater.

Prerequisites

The TopCAT distribution: TopCAT-1.12.0-distro.zip
A suitable deployed container (here assumed to be glassfish) to support a web application. Testing has been carried out with Glassfish 4.0. Glassfish installation instructions are available.
A database as described in Database installation instructions installed on the server
Python (version 2.4 to 2.7) installed on the server.

Summary of steps

If you have an earlier installation of TopCAT then either upgrade the schema or drop the database and create a new one - which will lose any existing configuration information.
Then follow the generic installation instructions.
Use the admin interface to configure access to one or more ICATs. This may not be necessary if you have a TopCAT database from an earlier deployment.
See if it works.

The topcat-setup.properties file

driver: is the name of the jdbc driver and must match the jar file for your database that you stored in the previous step.
dbProperties: identifies the icat database and how to connect to it.
glassfish: is the top level of the glassfish installation. It must contain "glassfish/domains", and will be referred to here as GLASSFISH_HOME as if an environment variable had been set.
port: is the administration port of the chosen glassfish domain which is typically 4848.
topcatUrlRoot: is the url path where topcat will be deployed (eg. /topcat). Leave blank for the default of / or enter your required path (do not end path with /)
topcatAdminUrlRoot: is the url path for topcatadmin will be deployed (e.g. /topcatadmin). Leave blank for the default of /TopCATAdmin or enter your required root url (do not end path with /)
adminUsername: The user name to use when setting up the topcat admin user. This will then be the user name to use to log on to the topcat admin console.
adminPassword: The password corresponding to the adminUsername

For a local oracle-xe installation the following values of driver and dbProperties should be good except for the user and password values:

driver=oracle.jdbc.pool.OracleDataSource icatProperties=url="'"jdbc:oracle:thin:@//localhost:1521/XE"'":ImplicitCachingEnabled=true:MaxStatements=200:user=icat:password=secret

Note the "'" which is needed because the url contains colons which also separate individual properties.

For MySQL:

driver=com.mysql.jdbc.jdbc2.optional.MysqlDataSource icatProperties=user=icat:password=secret:databaseName=icat

The topcat.properties file

KEYWORDS_CACHED: Boolean flag, 'true' or 'false'. True will result in keywords being cached on the server, this could result in the bypassing of the authorisation rules
LOGO_URL: The location of an image to display in the header of topcat. The value should be a path/file name relative to the <GLASSFISH_HOME>/glassfish/domains/<DOMAIN>/applications/TopCAT/ directory.
MESSAGE: This message will be displayed at the top of the web page. It is intended for use by sys admins so that they can inform users of up coming down times. If you change it then you will need to reload the application.
ACCESSIBILITY: The URL for an accessibility web page, a link to this is included in the topcat footer
PRIVACY_POLICY: The URL for a privacy policy web page, a link to this is included in the topcat footer
DATA_POLICY: The URL for a data policy web page, a link to this is included in the topcat footer
TERMS_OF_USE: The URL for a terms of use web page, a link to this is included in the topcat footer
COMPLAINTS_PROCEDURE: The URL for a complaints web page, a link to this is included in the topcat footer
FEEDBACK: The URL for a mailto link, a link to this is included in the topcat footer.

Add ICATs with the admin console

Connect to the https://<your host name>:8181/TopCATAdmin (or https://<your host name>:8181/<your topcatAdminUrlRoot> ). You will be prompted for a username and password.

Check that TopCAT works

Go to https://<[your host name]>:8181/TOPCATWeb.jsp (or https://<your host name>:8181/<your topcatUrlRoot>/TOPCATWeb.jsp) and try logging in to one of the configured ICATs if you have a login on one of them.

In case of problems look at the log files: server.log, topcat.log and topcat_admin.log all of which can both be found in the logs directory below your domain.

Schema Upgrade

The following changes have been made to the schema in topcat 1.12.0:

ALLOW_UPLOAD and ALLOW_CREATE_DATASET columns added to TOPCAT_ICAT_SERVER
MESSAGE columns were added to TOPCAT_USER_DOWNLOAD

To upgrade an existing database from topcat 1.11.0 to 1.12.0, run the following sql queries for your particular database:

Oracle:

ALTER TABLE TOPCAT_ICAT_SERVER ADD (ALLOW_UPLOAD NUMBER(1), ALLOW_CREATE_DATASET NUMBER(1));

ALTER TABLE TOPCAT_USER_DOWNLOAD ADD MESSAGE VARCHAR2(255);
MySql:

ALTER TABLE TOPCAT_ICAT_SERVER ADD (ALLOW_UPLOAD TINYINT(1), ALLOW_CREATE_DATASET TINYINT(1));

ALTER TABLE TOPCAT_USER_DOWNLOAD ADD MESSAGE VARCHAR(255);
Derby:

ALTER TABLE TOPCAT_ICAT_SERVER ADD (ALLOW_UPLOAD SMALLINT, ALLOW_CREATE_DATASET SMALLINT);

ALTER TABLE TOPCAT_USER_DOWNLOAD ADD MESSAGE VARCHAR(255);

Deployment Behind Reverse proxy

The following are two examples of Apache 2.4 reverse proxy settings for topcat and topcatadmin. One for when topcat and topcatadmin is deployed using the default path and the other when a custom path is used

Using default install paths:

topcatUrlRoot=
topcatAdminUrlRoot=

                    
                        ProxyPreserveHost on
                        SSLProxyEngine on
                        SSLProxyCheckPeerCN off
                        SSLProxyCheckPeerName off
                        SSLProxyCACertificateFile
                        conf/ssl.crt/topcat.crt

                        ProxyPass /topcat/ https://localhost:8181/
                        ProxyPassReverse /topcat/ https://localhost:8181/
                        ProxyPassReverseCookiePath / /topcat

                        ProxyPass /topcatadmin/ https://localhost:8181/TopCATAdmin/
                        ProxyPassReverse /topcatadmin/
                        https://localhost:8181/TopCATAdmin/

                        <Location /topcat/>
                        RequestHeader edit X-GWT-Module-Base ^(.*)/topcat/(.*)$ $1/$2
                        </Location>
                        <Location /topcatadmin/>
                        RequestHeader edit X-GWT-Module-Base ^(.*)/topcatadmin/(.*)$ $1/TopCATAdmin/$2
                        </Location>

                        <Proxy *>
                        Allow from All
                        Require all granted
                        </Proxy>

Using custom install paths:

topcatUrlRoot=/<your topcat path>
topcatAdminUrlRoot=/<your topcatadmin path>

                    
                        ProxyPreserveHost On
                        SSLProxyEngine on
                        SSLProxyCheckPeerCN off
                        SSLProxyCheckPeerName off
                        SSLProxyCACertificateFile
                        conf/ssl.crt/topcat.crt

                        ProxyPass /topcat/ https://localhost:8181/<your topcat path>/
                        ProxyPassReverse /topcat/
                        https://localhost:8181/<your topcat path>/
                        ProxyPassReverseCookiePath /<your topcat path> /topcat

                        ProxyPass
                        /topcatadmin/ https://localhost:8181/<your topcatadmin path>/
                        ProxyPassReverse /topcatadmin/
                        https://localhost:8181/<your topcatadmin path>/

                        <Location /topcat/>
                        RequestHeader edit X-GWT-Module-Base
                        ^(.*)/topcat/(.*)$ $1/<your topcat path>/$2
                        </Location>
                        <Location /topcatadmin/>
                        RequestHeader edit
                        X-GWT-Module-Base ^(.*)/topcatadmin/(.*)$ $1/<your topcatadmin path>/$2
                        </Location>

                        <Proxy *>
                        Allow from All
                        Require all granted
                        </Proxy>

File Upload

Upload functionality in topcat requires the latest IDS 1.1.0 .

File upload is achieved via a cross-domain mechanism where files are uploaded directly to your configured IDS from the browser. In order for this to work, your IDS must have a CA certificate. If you are using a self-signed certificate on a test IDS installation, you must add the IDS certificate to your browser's trusted store for upload to work properly. If you do not add the certificate to your browser's trusted store, you will get a never ending upload progress bar because topcat cannot retrieve the server response from the IDS.

The upload functionality can be enabled/disabled in topcatadmin.

Information for Users

Information for Installers

Project Documentation

Installation