Gatein introduction: installation

GateIn is a portal framework dedicated to implementing highly customizable portal solutions with a powerful set of components based on well-known and adopted open source technologies and standards based on the Java web technologies.

  This article is an excerpt from Chapter 1 of Gatein CookBook published by Packt publishing. More information about this book at the end of this article.

Installing GateIn from a binary package

GateIn is released through different bundles that differ for the included application server. These bundles are dedicated to the following application servers—JBoss AS 5.x, JBoss AS 6.x, JBoss AS 7.x, Tomcat 6.x, Tomcat 7.x, and Jetty 6.x. In this recipe, we will see which are the required packages you need to download before starting a GateIn instance.

Getting Ready

A pre-requisite for running GateIn is the availability of the Java Development Kit (JDK), which must be updated to the latest revision of version 1.6.

GateIn can be installed using different packages, so now you can download your preferred bundle depending on which application server you need to use for your installation.

Typically, the right application server can be chosen by thinking about what you need for your software architecture. Let's assume that you need to deploy GateIn together with other standard Java EE applications that need explicit support for middleware components such as DataSource, Enterprise Java Bean (EJB), Java Message Service (JMS), or an Enterprise Service Bus (ESB).
You would then probably want to use the JBoss AS bundle. JBoss AS is completely focused on middleware support having the availability of a total J2EE-compliant application server. Otherwise, if you only need to use a standard servlet container, you can choose to download the Tomcat bundle.

Once you have chosen the right bundle for yourself, you are ready to download it from http://www.jboss.org/gatein/downloads. After downloading the GateIn package, you can extract it in your preferred directory in your file system.

Configuring the Content Storage

By default, GateIn is configured to use the Hypersonic SQL database and a relative folder in the bundle to manage the content storage. This type of setting is only useful for running a product demo without specifying any parameter, but this is not the suggested way to set up the platform for a production environment.

For production system environments, you should configure GateIn for using external DBMS and using a file system with good I/O performance to prevent bottlenecks during reading and writing operations on contents and search indexes.

We need to configure the components that manage content storage in GateIn.

Step #1 Configure exoJCR

The first component you need to configure is exoJCR: This is an open-source implementation of the Java Content Repository (JCR)specification provided by the eXo Community. It is used internally by GateIn to manage all the content data related to portals, pages, portlets, and metadata

Locate the configuration file in the shared class loader according to your application server.
If you want to use JBoss AS 7, you have to edit the configuration file here:
<JBOSS7_HOME>/standalone/configuration/gatein/configuration.properties

Carry out the following steps to configure the content storage:
1. Locate the following properties inside the configuration file:

gatein.jcr.datasource.driver
gatein.jcr.datasource.url
gatein.jcr.datasource.username
gatein.jcr.datasource.password

The default database settings of the JCR component of GateIn are based on these standard JDBC parameters:

gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver
gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name}
gatein.jcr.datasource.username=sa
gatein.jcr.datasource.password=

The above parameters will configure your HSQL database in a folder in your file system. As you can see, the parameter named gatein.db.data.dir, used for the value of the parameter gatein.jcr.datasource.url, allows you to set a specific folder that will contain all the content storage dedicated to the GateIn instance.
These parameters allow you to set the typical settings for a JDBC connection, so for example, if you need to configure Oracle DBMS for the JCR database, you should have a similar configuration to the following:

gatein.jcr.datasource.driver=oracle.jdbc.OracleDriver
gatein.jcr.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInJcr
gatein.jcr.datasource.username=<ORACLE USERNAME>
gatein.jcr.datasource.password=<ORACLE USER PASSWORD>

2. You or your DBA must create the database schema and the user above in your DBMS instance before running GateIn. The user credentials used by GateIn must have all the necessary permissions to manage tables and rows in the database instance.

  Notice that the default encoding for the database needed by GateIn is latin1, so be sure to set this parameter in your DBMS configuration.

3. Remember install the database JDBC driver (packaged as a JAR) into the application server (See this tutorial about installing a JDBC Driver on JBoss AS 7. For JBoss AS 4-5-6 See this tutorial)

Now that we have configured the database for the JCR component, we can continue configuring the JCR file system location. This section allows you to set a specific file system dedicated to store all the binaries and search indexes files managed by GateIn.
The default properties' values relating to the file system configuration are as follows:

gatein.data.dir=../gatein/data
gatein.jcr.data.dir=${gatein.data.dir}/jcr
gatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/values
gatein.jcr.index.data.dir=${gatein.jcr.data.dir}/lucene

Using these parameters, you can change the default location of the content binaries of GateIn. Here, you can change the default configuration for contents and search indexes as needed for your architecture.

Step #2 Configure the Identity Manager

Identity manager is configured using PicketLink IDM. This is an open-source project that can be embedded in any standard Java EE application and allows managing user identities by storing the information in a database. It also supports many ways to negotiate credentials and Single Sign On (SSO)mechanisms.

The built-in properties' values for the database JDBC connection of the identity management are the following:

gatein.idm.datasource.driver=org.hsqldb.jdbcDriver
gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name}
gatein.idm.datasource.username=sa
gatein.idm.datasource.password=

As seen above for the JCR database settings, a potential configuration for an Oracle database dedicated to the identity manager could be the following:

gatein.idm.datasource.driver= oracle.jdbc.OracleDriver
gatein.idm.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInIdm
gatein.idm.datasource.username=<ORACLE USERNAME>
gatein.idm.datasource.password=<ORACLE USER PASSWORD>

When the application server runs for the first time, GateIn will automatically create all the needed data structures in the database and inside the file system.

MySQL example configuration

gatein.jcr.datasource.url=jdbc:mysql://:/gateInJcr

For the identity manager you should have the following:

gatein.idm.datasource.url=jdbc:mysql://:/gateInIdm

Finally, remember to install the MySQL JDBC driver library into the application server in order to make the driver class available to GateIn.

Running GateIn on your machine

Let's assume that you have correctly configured GateIn as shown in the previous recipes or you are using the default settings found in the standard binary package. Now we are going to run GateIn for the first time.

Locate the binfolder of your application server; this is the location where the start/stop script is stored in your machine. Here are the details for the scripts in different application servers:

If you are using Tomcat then you have a specific script gatein.sh, for Windows gatein.bat, provided in the binary folder <TOMCAT_HOME>/bin
For JBoss AS 6 you can use the standard run.sh script available in <JBOSS6_HOME>/bin
JBoss AS 7 requires using the script standalone.sh stored in <JBOSS7_HOME/bin>

If the first deployment of GateIn finishes without errors we expect to see in the browser the following homepage of the default portal at: http://localhost:8080/sample-portal/

In the next tutorial we will show how to install the development tools and deploy a simple Portlet on it. Stay tuned !

Here you can view this sample chapter in PDF format.

Recommended Reading

All you need to develop and manage a GateIn portal and all available portlets.

Thorough detail on the internal architecture needed to use the components

Manage portal resources on a command line

Choose the authentication system

Configure users and groups and migrate portlets from other portals

Follow us on Twitter