GCube Portal Installation

gCube adopts Liferay Portal as enabling portal technology for its Infrastructure Gateway. gCube portal is built over Liferay Portal 6.0.6 (Bunyan)

gCube Infrastructure Gateway 4.0.0 (June 2016)

Starting from 3.0 release, the gCube Infrastructure Gateway has been mavenized, this make installing it a very simple process and takes less than five minutes to complete. We've been working hard to make this process as easiest and quicker as possible.

Supported Operating Systems are Linux and MacOSX. With Java7 installed.

Install the gCube Infrastructure Gateway Bundle

gCube Infrastructure Gateway 4.0.0 is bundled with Apache Tomcat 7 and the latest stable relase of gCube Featherweight Stack Distribution, gCube Application Support Layer (ASL), gCube Social Networking Library and gCube Home Library

All you need to do is the following:

• Download the latest version of the Portal-Bundle from maven, make sure you get the latest snapshot from our Nexus repo: gcube-portal-bundle SNAPSHOT

<dependency>
  <groupId>org.gcube.distribution</groupId>
  <artifactId>gcube-portal-bundle</artifactId>
  <version>LATEST</version>
  <type>tar.gz</type>
</dependency>

• Extract the gCube Infrastructure Gateway bundle tar.gz into a folder on your machine
• Add to the ~/.bashrc file the following:
  • clean CLASSPATH: "export CLASSPATH="
  • add CATALINA_HOME env. variable (the home directory of tomcat)
  • add JAVA_HOME env. variable (the home directory of java)
  • add JRE_HOME env. variable (JAVA_HOME/jre)
  • add CATALINA_OPTS env. variable "export CATALINA_OPTS="-Dexternal-properties=portal-developer.properties -Xmx1000m -Xms1000m -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol -Dlog4j.ignoreTCL=true -Dlog4j.configuration=file://$CATALINA_HOME/portal-log4j.properties"
  • add CATALINA_PID env. variable "export CATALINA_PID=~/pid.txt"

IMPORTANT The CATALINA_OPTS env variable: -Dexternal-properties=portal-developer.properties optimizes Liferay Portal for development by removing all caches and thus making sure that any change made by the developer is visible in the website as soon as technically possible. One of the final goals is to avoid rebooting the server as much as possible. Further Information at: LiferayDeveloper Mode Doc

After that, say you created a "Portal-Bundle" folder on your user's home(~) and extracted the org.gcube.portal.portal-bundle-2+ in there, the final part of your ~/.bashrc file may look like the following:

export JAVA_HOME=/usr/lib/jvm/java-7-oracle/
export JRE_HOME=$JAVA_HOME/jre
export CATALINA_HOME=~/Portal-Bundle/tomcat-7.0.62
export CATALINA_BASE=$CATALINA_HOME
export CATALINA_TMPDIR=$CATALINA_HOME/temp
 
export CLASSPATH=
export CATALINA_OPTS="-Dexternal-properties=portal-developer.properties  -Xmx1000m -Xms1000m  -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol -Dlog4j.ignoreTCL=true -Dlog4j.configuration=file://$CATALINA_HOME/portal-log4j.properties"
 
export CATALINA_PID=~/pid.txt

First startup of gCube Infrastructure Gateway

gCube Infrastructure Gateway enabling technology (Liferay) comes with a default database called HSQL or "hypersonic." This is not meant for production use!' You should switch to a real database to use the gCube Infrastructure Gateway. For further information see Configuring gCube Infrastructure Gateway database section below

However, if you want to startup gCube Infrastructure Gateway using the default database just open a shell and enter the following command:

source ~/.bashrc

and start tomcat

$CATALINA_HOME/bin/startup.sh

gCube Infrastructure Gateway take less than a minute to initialize, in the meanwhile you might want to check the portal logs, to do so, enter the command:

tail -f $CATALINA_HOME/logs/catalina.out

open your browser and go to http://localhost:8080 if you performed all of the above operations correctly, you should be presented something like the following

all you need to do now is follow the instructions on the screen, a wizard application will guide you through the Portal Staging procedure. Thank you for using gCube.

Starting/Stopping a gCube Infrastructure Gateway

In order to start / stop tomcat, you should execute the following commands:

• source the configured ~/.bashrc
• $CATALINA_HOME/bin/startup.sh
• $CATALINA_HOME/bin/shutdown -force

please note: If you change gCore's configuration or Tomcat's settings or Liferay portal.ext.properties file, you should restart tomcat for the changes to be applied.

Additional Information

Setting the Infrastructure

By Default the bundle is configured to run on the gCube Development infrastructure. However if you want to change infrastructure please edit this file under $CATALINA_HOME/conf/infrastructure.properties

Changing Company web id

By default, gCube Infrastructure Gateway starts with "liferay.com" as default company web id, this means, among other things, that at login time portal will suggest email addresses ending with @liferay.com. If you want to configure the portal to use your own Company web id just add the following property in portal.ext.properties file located under $CATALINA_HOME/webapps/ROOT/WEB-INF/classes.

Replace <MY_COMPANY_WEB_ID> with your own company web id, e.g. google.com

#company web id name
company.default.web.id=<MY_COMPANY_WEB_ID>

please note 1: This change must be performed before starting up your portal for the first time.

please note 2: This change will not work if you use the default HSQL DB (Hypersonic)

Configuring gCube Infrastructure Gateway database

If you want to configure the portal to use a different database than the default HSQL DB one (and you are encouraged to do so) you should add some properties in portal.ext.properties file located under $CATALINA_HOME/webapps/ROOT/WEB-INF/classes. Please refer to the Liferay Database Portal Properties to know which type of database is supported.

Configuration examples: (replace <YOUR_DB_NAME>, <YOUR_DB_USER>, <YOUR_DB_PASSWORD> with actual values

• PostgreSQL

#
# PostgreSQL
#
jdbc.default.driverClassName=org.postgresql.Driver
jdbc.default.url=jdbc\:postgresql\://localhost\:5432/<YOUR_DB_NAME>
jdbc.default.username=<YOUR_DB_USER>
jdbc.default.password=<YOUR_DB_PASSWORD> 

• MySQL

 #
 # MySQL
 #
 jdbc.default.driverClassName=com.mysql.jdbc.Driver
 jdbc.default.url=jdbc:mysql://localhost/<YOUR_DB_NAME>?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
 jdbc.default.username=<YOUR_DB_USER>
 jdbc.default.password=<YOUR_DB_PASSWORD>

The above configuration are known to be working with gCube Infrastructure Gateway.

Troubleshooting

• If you get something like the following exception at portal startup, just cleanup your browser cookies.

ERROR [CompanyThreadLocal:54] com.liferay.portal.NoSuchCompanyException: No Company exists with the primary key 1
com.liferay.portal.NoSuchCompanyException: No Company exists with the primary key 1
	at com.liferay.portal.service.persistence.CompanyPersistenceImpl.findByPrimaryKey(CompanyPersistenceImpl.java:436)
	at com.liferay.portal.service.base.CompanyLocalServiceBaseImpl.getCompany(CompanyLocalServiceBaseImpl.java:325)
	at sun.reflect.GeneratedMethodAccessor515.invoke(Unknown Source)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
	at java.lang.reflect.Method.invoke(Method.java:597)
       .....

• If the Workspace Portlet shipped within this Bundle popups an error on startup you need to Install the Encryption key and add the Encryption key in your classpath to access runtime resources.

Staging procedure

Staging is a new feature bundled with gCube Infrastructure Gateway 2.0 When you install the portal for the first time a Wizard Application will guide you through the installation configuration and will setup everything's needed for you.

Once you logged in for the first time with the suggested credential you are presented the following page, click the button Begin Install (circled in red) to start the installation

At this point the installation procedure has started. The whole procedure consist of 4 steps, as shown in the figure below:

• Infrastructure and Theme Selection
• Virtual Research Environments check-up
• Administrator account creation
• Final step

Provide the information requested, if your not sure about the settings you should read more about gCube on this wiki. The next steps are quite handy and we think no further documentation is needed, however feel free to ask for support if needed.