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

Portal

Portal 3.x 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 3.0 release can be downloaded from the caGrid Gforge site

Checkout the Source Code

Subversion Checkout on Windows

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.tigris.org

caGrid Portal 3.x Release Branch

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.7.x or higher version
    • Make sure that ANT_HOME is set and Ant executable is on the PATH.
  • MySQL 5.1.x
    • You will need privileges to create and delete databases.

caGrid Portal runs in the Liferay portlet container, which can deployed into many application servers. The installation script supports deploying to Apache Tomcat 5.5.27 or JBoss 4.0.5.GA. The script will download and configure either Tomcat or JBoss depending on the type of server selected in build.properties. See here for more information.

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'@'%';
grant all privileges on portal2.* to 'portalacct'@'%';
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 grid as the target grid. If you are using this grid, you don't need to do anything (See note below).

If you are using one of the following grids:

  • nci_qa-1.3
  • nci_stage-1.3
  • nci_prod-1.3
  • training-1.3 (default)

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:

Choose server type

  • liferay.server.type: Either 'tomcat' or 'jboss'(default)

If you are using another JBOSS container and do NOT want the Portal to install a new one

  • liferay.jboss.home: JBoss installation directory
  • liferay.jboss.server.name JBoss server configuration to use

Select install location

  • liferay.install.dir: On Windows, change this to a path that does not include spaces (e.g. 'C:\portal-liferay').

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.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

Impromptu queries

  • cagrid.portal.impromptu.min.milliseconds.between.submissions

This is the value in milliseconds of the minimal required period between new impromptu query submissions.

  • cagrid.portal.imprompty.max.cached.queries.count

This is the maximum amount of queries that will be cached (with their results) by the impromptu query facility.

Installation


Install caGrid Portal


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

ant install

If you have created another build-<envname>.properties file, run the following command:

ant -Dtarget.env=<envname> install

This will download the required software (JBoss (or Tomcat), Liferay, etc.), install and configure.

Post-Installation


Setup Environment


JBoss


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.

C:\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

NOTE: Make sure JBOSS has enough memory to run the Portal software. The recommended settings are

JAVA_OPTS=-Xms256m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=256m

Tomcat


Set the CATALINA_HOME environment variable to the location where Tomcat was installed.

Windows

C:\portal-liferay\apache-tomcat-5.5.27

Unix/Linux/Mac

export JBOSS_HOME=$HOME/portal-liferay/apache-tomcat-5.5.27

Adjust DNS Cache Settings


Java's default DNS cache settings are to cache forever. This can cause issues if the IP address of an external service (e.g. Yahoo! Geocoder) changes. To avoid this, we need to adjust the cache settings. This can be done on the command line or in the java.security file. For the command-line approach, just add another option to the JAVA_OPTS environment variable:

JAVA_OPTS=-Xms256m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=256m -Dsun.net.inetaddr.ttl=60

For the java.security file approach, you need to use a different property name. Add the following to $JAVA_HOME/lib/security/java.security.

networkaddress.cache.ttl=60

Adjust maxBytes


The caGrid WS technology stack uses Axis 1.4, which doesn't support streaming. Whatever data a client retrieves from a caGrid data services gets loaded into memory. If a client pulls retrieves too much data, it can degrade the performance of the application server. To prevent this, you can put hard limits on the amount of data that users can retrieve by setting a system property. (See here for more information)

The system property is

org.apache.axis.transport.http.maxBytes

By default, its value is 100000000, or 100MB. To set this value in JBoss, add it to JBOSS_HOME/server/default/deploy/properties-service.xml

  ...
  <mbean code="org.jboss.varia.property.SystemPropertiesService"
	 name="jboss:type=Service,name=SystemProperties">
    <attribute name="Properties">
     org.apache.axis.transport.http.maxBytes=100000000
    </attribute>
  </mbean>
  ...

In Tomcat, just set property in the value of JAVA_OPTS environment variable, either in the shell, or in $CATALINA_HOME/bin/catalina.sh

For example, in the bash shell:

export JAVA_OPTS="-Dorg.apache.axis.transport.http.maxBytes=100000000"

Start the Application Server


JBoss


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 &

Tomcat


Windows

  1. Navigate to %CATALINA_HOME%\bin
  2. Double-click startup.bat

Tomcat

cd $CATALINA_HOME\bin
chmod u+x *.sh
./startup.sh

For tomcat, manually copy log4j-1.2.14.jar to the location <TOMCAT>\webapps\cagridportlets\WEB-INF\lib folder and use property log4j.appender.logfile.File=$

Unknown macro: {cagridportlets.root}

/WEB-INF/cagridportlets.log in log4j.properties under <TOMCAT>\webapps\cagridportlets\WEB-INF folder to create log file.

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:

Go to http://<host>:<port>/group/control_panel

You'll see the login page. Log in using the administrator's username and password. Once successfully authenticated, you'll see the administrator's view of the Control Panel. Select the Communities link on the left. You'll then see the available communities.

Administrator's view of Control Panel with Communities selected.

Figure 1: Administrator's view of Control Panel with Communities selected.

There will be only one community, named Guest. Click on the Actions button and select Manage Pages. On the next page, select the Export/Import tab, and then the Import sub tab.

Import tab for Guest community.

Figure 2: Import tab for Guest community.

Leave all the default selections of checkboxes as they are. Click the Browse button and then navigate to and select SRC/portals/liferay/lars/cagrid-portal-3-guest-community.lar. Then, click the Import button. You should see a message at the top of the page saying "Your request processed successfully."

Click the Communities link on the left side of the page again. This will show the list of communities again. Click the Add button at the top of the page. In the form that appears, enter "DEFAULT_TEMPLATE" into the Name field. The community must have this exact name - all caps with an underscore. This community will server as the template for communities that users create. Then click the Save button.

Creating the DEFAULT_TEMPLATE community.

Figure 3: Creating the DEFAULT_TEMPLATE community.

Follow the same steps from above to import the DEFAULT_TEMPLATE.lar file into this community.
Then, click on the Settings tab. On the Staging sub tab, click the Activate Staging checkbox.

Activate staging for the DEFAULT_TEMPLATE community.

Figure 4: Activate staging for the DEFAULT_TEMPLATE community.

Set Up Privileges


In the Control Panel, click on the Roles link on the left side of the page. You'll see a list of all the default roles.

Default roles list.

Figure 5: Default roles list.

Click the Add button and enter "Catalog Admin" into the Name field. Then, click the Save button. You'll now see Catalog Admin in the list of roles. Click the Action button next to it, and select Define Permissions. On the next page, click the Add Portal Permissions button on the Define Permissions tab. Scroll down to the User section. Next to the Delete action, select "Portal" from the Scope drop-down list. Then, click the Save button.

Click the Roles link on the left of the page again. Click the Add button and add a new role named "Catalog User". Click Actions > Define Permissions and then click the Add Portal Permissions button. In the Portal section, set the Add Community action's scope to "Portal".

You will also need to make these roles the default role for users that sign into the Portal.

Default User Associations.

Figure 6: Default User Associations

For this, select the 'Settings' section from the Control Panel menu. Then select 'Default User Associations' and enter the role "Catalog User" role as one of the default roles. Click the Save button.

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. From $SRC, run:
 ant -Dtarget.env=<target.env> all 
 ant -Dtarget.env=<target.env> 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
William Stephens (1162 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence