Installation

Compatibility

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

Prerequisites

Summary of steps

  1. 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.
  2. Then follow the generic installation instructions.
  3. 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.
  4. 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.