h1. Portal 3.0 Installation Guide

{cagridroundpanel}
{pre:class=cagridheaderfont}Table of Contents{pre}
{toc:outline=true|exclude=Portal 3.0 Installation Guide|style=none}
{cagridroundpanel}
h1. Pre-Installation
----
h2. Obtaining the caGrid Portal Software
----
You can download the caGrid Portal release or check out the code from SVN.

h3. Download the Release
----
The caGrid Portal 3.0 release can be downloaded from the [caGrid Gforge site|https://gforge.nci.nih.gov/frs/?group_id=25]

https://gforge.nci.nih.gov/frs/?group_id=25

h3. Checkout the Source Code

h4. 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|http://subversion.tigris.org/getting.html#windows]

h4. caGrid Portal 3.0 Release Branch


{terminal}svn checkout https://ncisvn.nci.nih.gov/svn/cagrid/tags/cagrid-portal-3-0_release_final/cagrid/Software/portal/cagrid-portal
{terminal}After checkout, the caGrid Portal source code directory (referred to henceforth as $SRC) will be located under ./cagrid-portal.


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

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|#Configure caGrid Portal Installation] for more information.

{anchor:Create Databases}

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

{terminal}
create database lportal character set utf8;
create database portal2;
{terminal}
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:
{terminal}
grant all privileges on lportal.* to 'portalacct'@'%';
grant all privileges on portal2.* to 'portalacct'@'%';
flush privileges;
{terminal}
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|http://dev.mysql.com/doc/refman/5.0/en/index.html]

h2. 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:
{code}$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore
{code}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:
* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html|http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html]

For instructions on configuring JBoss and Tomcat to use SSL, follow these links:
* [http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html|http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html]
* [http://docs.jboss.org/jbossas/jboss4guide/r5/html/ch9.chapt.html#ch9.https.sect|http://docs.jboss.org/jbossas/jboss4guide/r5/html/ch9.chapt.html#ch9.https.sect]

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

{anchor:Obtain Google Maps API Key}

h2. Obtain Google Maps API Key
----
You can get a Google Maps API key here: [http://www.google.com/apis/maps/signup.html|http://www.google.com/apis/maps/signup.html]If 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|http://my.host.com:8080/]. Save this key for future use.

{anchor:Obtain Yahoo ApplicationID}

h2. Obtain Yahoo ApplicationID
----
Get an ApplicationID from Yahoo at [http://developer.yahoo.com/wsregapp/index.php|http://developer.yahoo.com/wsregapp/index.php]. Save this for future use.

h2. 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|#Configure caGrid Portal Installation].

If you are using another/custom target grid, then you need to do three things:
# Create a sync-description.xml file to configure the GTS client that the portal uses.
# Bootstrap the trust fabric by placing root certificates under the $HOME/.globus/certificates directory.
# 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|gts12:Administrators Guide].

{anchor:Configure caGrid Portal Installation}

h2. 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:
{code}ant -Dtarget.env=testing install
{code}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|#Create Databases])
* liferay.db.host
* liferay.db.port
* liferay.db.name
* liferay.db.username
* liferay.db.password

*Database Information for the Portal database (created* [earlier|#Create Databases])
* 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|#Obtain Yahoo ApplicationID])
* cagrid.portal.geocoder.yahoo.appId

*Google Map key (created* [earlier|#Obtain Google Maps API Key])
* cagrid.portal.map.google.apiKey

*Encryption key*
* cagrid.portal.security.encryption.key
** *Note:* The value is used to encrypt user credentials in memory (See [this section|#Secure Encryption Key] for more information). The key must be *at least 24 characters*.

h2. Install caGrid Portal
----
If you have directly updated build-local.properties, run the following command:
{code}ant install
{code}If you have created another build-<envname>.properties file, run the following command:
{code}ant -Dtarget.env=<envname> install
{code}This will download the required software (JBoss (or Tomcat), Liferay, etc.), install and configure.

h1. Post-Installation
----
h2. Setup Environment
----
h3. 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.
{code}C:\portal-liferay\jboss-4.0.5.GA
{code}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:
{code}export JBOSS_HOME=$HOME/portal-liferay/jboss-4.0.5.GA
{code}

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

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

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

*Windows*
{code}C:\portal-liferay\apache-tomcat-5.5.27
{code}{*}Unix/Linux/Mac*
{code}export JBOSS_HOME=$HOME/portal-liferay/apache-tomcat-5.5.27
{code}

{anchor:Adjust DNS Cache Settings}
h2. 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:

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

For the java.security file approach, you need to use a different property name. Add the following to $JAVA_HOME/lib/security/java.security.
{code}
networkaddress.cache.ttl=60
{code}

{anchor:Adjust maxBytes}
h2. 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|https://gforge.nci.nih.gov/frs/shownotes.php?release_id=1949] for more information)

The system property is {code}org.apache.axis.transport.http.maxBytes{code}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

{code}
...
<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>
...
{code}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:
{terminal}
export JAVA_OPTS="-Dorg.apache.axis.transport.http.maxBytes=100000000"
{terminal}



h2. Start the Application Server
----
h3. JBoss
----
On Windows, do the following:
# Navigate to %JBOSS_HOME%\bin.
# Double-click run.bat

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

{code} cd $JBOSS_HOME/bin
chmod u+x *
./run.sh > portal.log &
{code}
h3. Tomcat
----
*Windows*
# Navigate to %CATALINA_HOME%\bin
# Double-click startup.bat

*Tomcat*
{code}cd $CATALINA_HOME\bin
chmod u+x *.sh
./startup.sh
{code}


{anchor:Import the Site Structure}
h2. 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.

!community_config1.png|alt=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.

!community_config2.png|alt=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.

!community_config3.png|alt=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.

!community_config4.png|alt=Activate staging for the DEFAULT_TEMPLATE community.!

*Figure 4: Activate staging for the DEFAULT_TEMPLATE community.*

{anchor:Set Up Privileges}
h2. 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.

!roles_config1.png|alt=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.

!portal-user_association.png|alt=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.

{anchor:Secure Encryption Key}
h2. 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.

h1. 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.
# Stop the JBoss application server.
# From $SRC, run:

{code} ant -Dtarget.env=<target.env> all {code}

{code} ant -Dtarget.env=<target.env> install {code}
h1. 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:

{code}export ANT_OPTS="-Dhttp.proxyHost=proxy \-Dhttp.proxyPort=8080"{code}For additional instructions, see [http://ant.apache.org/manual/proxy.html|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.