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 are going to configure the components that manage content storage in GateIn:
- 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.
- 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.
Let's first configure exoJCR, which is the component responsible for the content storage in the portal. This component consists of two physical storage elements:
- Database
- File system
Finally, we will see how to configure a JBoss identity that is based only on a separate database instance.
Locate the configuration file in the shared class loader according to your application server. Assuming that you are using Tomcat, the configuration file is located here:
<TOMCAT6_HOME>/gatein/conf/configuration.properties
If you are using JBoss AS 6 you will find it at the following location:
<JBOSS6_HOME>/server/default/conf/gatein/configuration.properties
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:
- Locate the following properties inside the configuration file:
gatein.jcr.datasource.drivergatein.jcr.datasource.urlgatein.jcr.datasource.usernamegatein.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.jdbcDrivergatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name}gatein.jcr.datasource.username=sagatein.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 parametergatein.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.OracleDrivergatein.jcr.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInJcrgatein.jcr.datasource.username=<ORACLE USERNAME>gatein.jcr.datasource.password=<ORACLE USER PASSWORD>
- 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. - Remember to copy the database JDBC driver (packaged as a JAR) to the library folder of your application server. In this way, GateIn can correctly use the existing database instance.
For Tomcat, you can copy the JDBC driver in this folder:
<TOMCAT6_HOME>/libFor JBoss 6 AS you can use this one:
<JBOSS6_HOME>/server/default/libFor JBoss 7 AS the following directory is available here:
<JBOSS7_HOME>/standalone/lib - 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/datagatein.jcr.data.dir=${gatein.data.dir}/jcrgatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/valuesgatein.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.
- Configure another database schema dedicated to the identity manager.
- The built-in properties' values for the database JDBC connection of the identity management are the following:
gatein.idm.datasource.driver=org.hsqldb.jdbcDrivergatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name}gatein.idm.datasource.username=sagatein.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.OracleDrivergatein.idm.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInIdmgatein.idm.datasource.username=<ORACLE USERNAME>gatein.idm.datasource.password=<ORACLE USER PASSWORD>
In the previous steps, we have configured the content storage of GateIn that will be used to create all the needed data structures (tables in the database and folders in the file system) for managing portal contents.
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.
The database connection used in GateIn is a standard JDBC connection that requires the usual parameters for configuration:
- JDBC driver class
- JDBC URL
- Username
- Password
Note
The driver class is the Java class of the DBMS driver that allows remote access to the database instance for managing JDBC connections.
The value for the JDBC URL must follow your specific DBMS conventions to locate the database instance remotely via JDBC.
The username and password are related to a specific users credentials that GateIn must use to access and manipulate contents in the database.
You also have the possibility to configure contents and indexes to increase performance during searching or creating contents. This is done by changing locations to machines with better hardware for both of the components.
A typical approach is to dedicate the local file system storage to the Apache Lucene indexes (gatein.jcr.index.data.dir) and a high-performance storage location for contents, setting a different value for the gatein.jcr.storage.data.dir property.
Note
Apache Lucene is an open-source text-search engine library used in many Enterprise products to create and manage content indexes. It supports execution of queries based on the Lucene Query Language, which is a very powerful query language that can search contents by ranking, phrase, and exact match. Lucene is licensed under Apache Software License Version 2.0.
For more information about Lucene, you can visit the project website at http://lucene.apache.org/.
In order to configure MySQL for the database storage of GateIn, you should edit the configuration file in a similar way for JCR, following the related conventions:
gatein.jcr.datasource.driver=com.mysql.jdbc.Driver
gatein.jcr.datasource.url=jdbc:mysql://<HOST>:<PORT>/gateInJcr
gatein.jcr.datasource.username=<MYSQL USERNAME>
gatein.jcr.datasource.password=<MYSQL USER PASSWORD>
For the identity manager you should have the following:
gatein.idm.datasource.driver=com.mysql.jdbc.Driver
gatein.idm.datasource.url=jdbc:mysql://<HOST>:<PORT>/gateInIdm
gatein.idm.datasource.username=<MYSQL USERNAME>
gatein.idm.datasource.password=<MYSQL USER PASSWORD>
Finally, remember to copy the MySQL JDBC driver library into the application server library folder in order to make the driver class available to GateIn.