Access Keys:
Skip to content (Access Key - 0)

Portal

Portal 2.2 Installation Guide

Table of Contents

Pre-Installation

Obtaining the caGrid Portal Software

You can download the caGrid Portal release or check out the code from SVN.

Download the Release

The caGrid Portal 2.2 release can be downloaded gforge.

Subversion Checkout on Windows

The caGrid 1.3 release stream provides access to the official source code repository for caGrid 1.3. On Windows systems, we recommend the following 3rd party tool as a GUI front-end to subversion to check out a caGrid release: http://tortoisesvn.tigris.org The command line version of subversion can be obtained from http://subversion.apache.org/source-code.html

caGrid 1.3 Release Stream

caGrid 1.3 latest

 svn checkout https://ncisvn.nci.nih.gov/svn/cagrid/branches/caGrid-1_3_release/cagrid-1-0/caGrid

caGrid 1.3.0.2

 svn checkout https://ncisvn.nci.nih.gov/svn/cagrid/tags/caGrid-1_3_release_1_3_0_2/cagrid-1-0/caGrid/

caGrid 1.3.0.1

 svn checkout https://ncisvn.nci.nih.gov/svn/cagrid/tags/caGrid-1_3_release_1_3_0_1/cagrid-1-0/caGrid/

caGrid 1.3.0.0

 svn checkout https://ncisvn.nci.nih.gov/svn/cagrid/tags/caGrid-1_3_release_final/cagrid-1-0/caGrid

After checkout, the caGrid Portal source code directory (referred to henceforth as $SRC) will be located under ./cagrid-portal.

Obtain Required Software

The following software must be installed:

  • Java 1.5
    • Make sure JAVA_HOME is set and Java SDK executable is on the PATH.
  • Ant 1.6.5
    • Make sure that ANT_HOME is set and Ant executable is on the PATH.
  • MySQL 5+
    • You will need privileges to create and delete databases.

Create the Databases

The caGrid Portal application requires two databases: one for Liferay data, and one for caGrid Portal data. By convention, the names of these databases are lportal and portal2. If you are using these database names, then you need to execute the following SQL in your MySQL database:

  create database lportal character set utf8;
  create database portal2;

You will also need to provision an account that has access to these databases. If the same account will have full access to both database, you can use the following SQL:

  grant all privileges on lportal.* to 'portalacct'@'%' identified by 'mypwd';
  grant all privileges on portal2.* to 'portalacct'@'%' identified by 'mypwd';
  flush privileges;

This gives the user portalacct all privileges on these databases. This user can access the databases from any host. For more information, see the MySQL admin documentation:http://dev.mysql.com/doc/refman/5.0/en/index.html

Create SSL Certificate and Keystore

Some pages in the Portal need to be protected with HTTPS. You will need to create an SSL certificate that the embedded Tomcat instance (running in JBoss) will use. The installation script will configure the Tomcat HTTPS Connector, but you still must either create a certificate and PKCS12 keystore or specify the path to an existing keystore and provide the keystore password.

To create a keystore using the Java keytool, run this command:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore

Make sure to use the same password for keystore and key. When prompted for first and last name, specify the host name.

For complete instructions on using keytool, follow this link:

For instructions on configuring JBoss and Tomcat to use SSL, follow these links:

By default, the installation script assumes that the keystore is located at $USER_HOME/portal-liferay/portal-keystore and that the keystore password is portal. This location and password can be configured in the properties file that the installation script uses (described later).

Obtain Google Maps API Key

You can get a Google Maps API key here: http://www.google.com/apis/maps/signup.htmlIf your host's name is my.host.com, and the HTTP server is listening to port 8080, then the URL you should use is http://my.host.com:8080. Save this key for future use.

Obtain Yahoo ApplicationID

Get an ApplicationID from Yahoo at http://developer.yahoo.com/wsregapp/index.php. Save this for future use.

Configure the caGrid Trust Fabric

The caGrid Portal uses GAARDS to authenticate users, so the caGrid trust fabric must be configured on the machine that will host the Portal. The Portal itself uses the GTS client to maintain the trust fabric, but you must also bootstrap the trust fabric.

By default, the Portal will use the training as the target grid. If you are using this grid, you don't need to do anything (See note below).

NOTE: The default property evs.remoteAPI.url points to _http://evsapi-qa.nci.nih.gov/evsapi40_. This URL is unreachable from outside the NIH network. So this might need to be changed, in build.properties or build-local.properties, to _http://evsapi.nci.nih.gov/evsapi40_ if you are deploying the Portal outside the NIH firewall.

If you are using one of the following grids:

  • nci_dev
  • nci_qa
  • nci_prod

You will need to configure properties relevant to the target grid environment by creating a corresponding build.properties file. Look at build-nci_qa.properties as an example. When you run the installation script, you must specify the name of your target environment. More details about this are provided in the Configure caGrid Portal Installation section below.

If you are using another/custom target grid, then you need to do three things:

  1. Create a sync-description.xml file to configure the GTS client that the portal uses.
  2. Bootstrap the trust fabric by placing root certificates under the $HOME/.globus/certificates directory.
  3. Configure caGrid Portal to use your sync-description.xml configuration.

To configure the portal to uses your sync-description.xml and certificates, you need to edit the aggr.trust.syncgts.file and aggr.trust.certs.dir properties to the path to your sync-description.xm file and the directory in which the root certificates are found, respectively.

Directions for configuring a trust fabric using caGrid tools are here.

Configure caGrid Portal Installation

The caGrid Portal installation script is at $SRC/build.xml. This is an Ant build file configured by the properties that are defined in the build.properties file in the same directory. To customize the installation, you can directly edit build.properties or you can override those properties by specifying them in the build-local.properties file.

NOTE: By default, the build.xml file will load the build-${target.env}.properties file first and then the build.properties file. The ${target.env} is 'local', so the build-local.properties file is used.

Furthermore, if you want to maintain installation configurations for multiple deployment tiers, you can create multiple properties files whose names have the form: build-<tier>.properties, where '<tier>' is replaced with the name of the tier. For example, if I have created a configuration for the 'testing' tier, then I would create a file named build-testing.properties, and then run Ant from the $SRC directory like this:

ant -Dtarget.env=testing install

See the $SRC/build-local.properties file itself for a list of all the properties that you will need to specify to customize the Portal. The build-local.properties has a list of all mandatory (database properties, etc.) and optional properties. If you are using the training target grid and default installation location, then you will usually only need to edit the following properties:

Set password for the Liferay administrator

  • liferay.admin.password

Email address for the Portal administrator

  • cagrid.portal.admin.email

Database information for the Liferay database (created earlier*)*

  • liferay.db.host
  • liferay.db.port
  • liferay.db.name
  • liferay.db.username
  • liferay.db.password

Database Information for the Portal database (created earlier*)*

  • cagrid.portal.db.url
  • cagrid.portal.db.username
  • cagrid.portal.db.password

caGrid Services

The Portal builds against the caGrid Training tier by default. Change the following properties if you want to deploy the Portal against a different tier of caGrid (for example, Production).

  • aggr.trust.target.grid
  • cagrid.portal.indexServiceUrls
  • cagrid.portal.idpInfo
  • cagrid.portal.ifsUrl
  • cagrid.portal.gmeUrl
  • cagrid.portal.cadsrUrl
  • fqp.service.url

*Note:*The build-nci_qa.properties can serve as an example.

Yahoo application id (created earlier*)*

  • cagrid.portal.geocoder.yahoo.appId

Google Map key (created earlier*)*

  • cagrid.portal.map.google.apiKey

Encryption key

Installation

Install caGrid Portal

From the $SRC directory, run the following command:

ant -Dtarget.env=<envname> install

If you have just directly updated build.properties or build-local.properties, then you would run the following command:

ant install

Post-Installation

Setup Environment

On MS Windows, use the System application in the Control Panel to set the JBOSS_HOME environment variable to point to the directory in which JBoss was installed. By default, the variable will point to the following path:

%HOMEDRIVE%%HOMEPATH%\portal-liferay\jboss-4.0.5.GA

On Unix/Linux/Mac, the default location will be $HOME/portal-liferay/jboss-4.0.5.GA. You can set the environment variable in the bash shell as follows:

export JBOSS_HOME=$HOME/portal/liferay/jboss-4.0.5.GA

Start the Application Server

On Windows, do the following:

  1. Navigate to %JBOSS_HOME%\bin.
  2. Double-click run.bat.

On Unix/Linux/Mac, you should do something like this:

  cd $JBOSS_HOME/bin
  chmod u+x *
  ./run.sh > portal.log &

Import the Site Structure

You can configure the basic site structure by using the Liferay administrative portlets to import Liferay Archive (lar) files. These files are available in the $SRC/portals/liferay/lars/ directory. To import the lar files, follow these steps:

Login as Admin

Setup the Administrator Community Layout

This step needs to be done only once. If you have already setup the administrators community previously, you can skip ahead to the next section.

  • From upper right-hand corner, click "Welcome" drop-down list, then select MyPlaces > My Community. You will see two additional options drop down: "Public Pages" and "Private Pages". Click on the icon to the right of the "Private Pages" text.
  • Click on the "Import/Export" tab.
  • Click on the "Import" sub tab.

Note If you don't see the Import sub tab, just navigate to the portal homepage (by clicking on the upper right-hand corner, click "Welcome" drop-down list, then select My Places > My Community. > Public pages). Start again from step 1.

  • Select the "User Preferences" checkbox.
  • Press the "Browse..." button to navigate to and select "portaladmin-private-community.lar" in the $SRC/portals/liferays/lars folder of the portal source distribution.
  • Click "OK".
  • Click "Import" button.
  • Click the back arrow icon in upper, right-hand corner.

Setup the Guest Community Layout

  • In upper right-hand corner, click "Welcome" drop-down list, then select My Places > My Community > Private Pages. This time, just click on the "Private Pages" text, NOT the icon to the right.
  • In Communities portlet, click "Communities I have joined" tab.
  • Click the "Actions" button and select "Manage Pages"
  • Click on the "Import/Export" tab.
  • Click on the "Import" sub tab.
  • Select the "Portlet Preferences" and "Portlet Data" checkboxes.
  • Press the "Browse..." button to navigate to and select "guest-community.lar" in the $SRC/portals/liferays/lars folder of the portal source distribution.
  • Click "OK".
  • Click "Import" button.
  • Click back arrow icon in upper, right-hand corner of page.
  • In upper, right-hand corner, click "Welcome" drop-down list, then selected My Places > Guest Community > Public Pages.

You should see the caGrid Portal Home page. Sign out by selecting the "Sign Out" option from the "Welcome" drop-down list.

Note: If you see an error message just below the Google Map on the Home page stating that you do not have privileges to view this portlet, simply restart JBoss.

Secure Encryption Key

A file named agridportal.properties is generated and placed in two locations on the file system:

  • $JBOSS_HOME/server/default/deploy/liferay-portal.war/WEB-INF/classes/cagridportal.properties
  • $JBOSS_HOME/server/default/deploy/cagridportlets/WEB-INF/classes/cagridportal.properties

The value of the cagrid.portal.security.encryption.key property in this file is used to encrypt authentication tickets as well as Portal users' temporary grid credentials (in the database). It is important that these files are protected so that users' grid credentials cannot be decrypted by a malicious user who has access to both the hosting system and database. Set file permissions appropriately for your system.

Re-Installation

This section describes the steps needed to wipe out an existing installation and re-install. All existing data will be destroyed. See the Administrator's Guide for directions on backing up data and running batch imports of data.

  1. Stop the JBoss application server.
  2. Drop the portal2 and lportal databases.
  3. Re-create databases.
  4. From $SRC, run:
 ant \-Dtarget.env=<env> clean install

Firewall/Connectivity Considerations

By default, the portal installation script will download JBoss and several Liferay artifacts. If you are behind a firewall, you will need to provide the proxy configuration for your Java Virtual Machine. Essentially, you simply need to set the ANT_OPTS environment variable to include the standard Java proxy settings using the following command:

export ANT_OPTS="-Dhttp.proxyHost=proxy \-Dhttp.proxyPort=8080"

For additional instructions, see http://ant.apache.org/manual/proxy.html.

IF YOU HAVE NO INTERNET ACCESS, you can still use the installation script. You will just need to download the dependencies manually and then edit/provide the following properties in build.properties so that they point to local directories/files:

- liferay.jboss.home
- liferay.jboss.zip
- liferay.downloads.dir
- liferay.dependencies.zip
- liferay.war

See build-liferay.xml for details.
Last edited by
Manav Kher (825 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence