Domain mode configuration - GateIn Portal 3.8

GateIn Portal and Domain mode in AS7

Domain mode feature of JBoss AS7 allows to manage multiple server instances from a single control point.

GateIn Portal can be configured to work with domain mode but under some limitations that we are going to describe:

GateIn configuration

GateIn Portal configuration is located into several files.

Some configuration elements (i.e. required datasources) are defined inside the AS7 server instance configuration file but others portal specific are defined in separate files.

These files are grouped in a folder, by default, in the standalone configuration, this folder is located at $JBOSS_HOME/standalone/configuration/gatein/ .

Working in Domain mode requires to define where GateIn configuration will be placed for each server instance.

GateIn Portal defines several variables as system properties level that can help to define the path of the external configuration files.

These variables are:

exo.conf.dir
gatein.conf.dir
gatein.portlet.config

We can adopt several strategies to indicate where GateIn Portal configuration will be located in Domain mode:

(a) Configuration defined per server instance:

This strategy defines configuration variables per server instance.
This can be done inside the host.xml file used, for example:

<server name="server-one" group="main-server-group">
  <system-properties>
    <property name="exo.conf.dir" value="${jboss.home.dir}/standalone/configuration/gatein"/>
    <property name="gatein.conf.dir" value="${jboss.home.dir}/standalone/configuration/gatein"/>
    <property name="gatein.portlet.config" value="${jboss.home.dir}/standalone/configuration/gatein"/>
  </system-properties>
</server>

Note that

${jboss.home.dir}/domain/servers/myinstance/configuration/gatein

has to be created, domain mode will not create this folder for you.

If we create manually a server instance using AS7 console or CLI tool we should add these properties manually to allow GateIn Portal loads succesfully, for example:

images/author/download/attachments/78709287/server-properties.png

When gatein.conf.dir variable is set up via system properties it must be commented from GateIn Portal configuration.properties file

(b) Configuration shared per a group of servers:

Using this strategy we need to predefine a folder that will host the GateIn configuration per all server instances.

Next step will be define configuration variables at server-group level inside a domain.xml file.

For example:

<server-group name="main-server-group" profile="full">
  <jvm name="default">
    <heap size="1303m" max-size="1303m"/>
    <permgen max-size="256m"/>
  </jvm>
  <socket-binding-group ref="full-sockets"/>
  <system-properties>
    <property name="exo.conf.dir" value="${jboss.home.dir}/standalone/configuration/gatein"/>
    <property name="gatein.conf.dir" value="${jboss.home.dir}/standalone/configuration/gatein"/>
    <property name="gatein.portlet.config" value="${jboss.home.dir}/standalone/configuration/gatein"/>
  </system-properties>
</server-group>

We can also use AS7 or CLI tool to create a server group with variables defined as system properties, for example:

images/author/download/attachments/78709287/server-group-properties.png

When gatein.conf.dir variable is set up via system properties it must be commented from GateIn Portal configuration.properties file

Portal Extensions and Portal Containers

Portal Extensions and Portal Containers mechanisms are functionalities that make it possible to overrride portal services and resources allowing a powerful way to personalize GateIn Portal.

These specific elements are packged as .war or .ear archives but they are deployed into a special folder located at

${jboss.home.dir}/gatein/extensions

Portal Extensions and Portal Containers are not hot-deployable. There is a special GateIn service in charge to load these element at startup from extensions folder.

Portal Extensions and Portal Containers cannot be deployed via domain mode mechanism, they need to be deployed manually at file system layer.

Portal applications can be deployed using domain mode mechanism as well as other JEE application.

There are also two additional variables that can be used to personalize per a server instance or server group where to find the main portal container (gatein.ear) or their extensions:

gatein.deploy.dir, with default value $JBOSS_HOME/gatein
gatein.extensions.dir, with default value $JBOSS_HOME/gatein

Domain mode example

GateIn comes with a ready made domain.xml / host.xml demo configuration (profiles 'default' and 'full') for a single-host domain mode setup with two different GateIn instances.

Demo domain configuration establishes two instances that listen on different ports. The one on port 8080 provides WSRP integration and Mobile support. The other one, listening on port 8330, provides Mobile support, but does not provide WSRP integration. This way we have two different portal instances.

Setting up the demo configuration is easy. Simply run the following shell script:

$JBOSS_HOME/bin/demo-domain-setup.sh

Then run GateIn in domain mode instead of standalone mode:

$JBOSS_HOME/bin/domain.sh

This command will start up a host controller process that in this case also serves as a domain controller. This process containes a domain management console at http://localhost:9990/console. It uses domain.xml and host.xml configuration files from $JBOSS_HOME/domain/configuration, and based on them it spawns two GateIn instances (two new JVM processes).

Console can be used to deploy a portlet application (i.e. simplest-helloworld-portlet.war) to both GateIn instances.

The demo configuration shows how gatein.extensions.dir system property can be used to assign different extensions directories to different servers in order to allow different portals to coexist on the same host.

The first server - 'server-one' - uses the default extensions directory location ($JBOSS_HOME/gatein/extensions). For the second one - 'server-two' - we specify an alternative extensions location in host.xml.

The demo configuration also makes two copies of gatein configuration directory ($JBOSS_HOME/standalone/configuration/gatein) - one for each server.

Setting up a domain scenario step by step

In this example we are going to describe steps to set up a domain in a more complex scenario.

Test environment

For this scenario we will count with the following machines:

Machine name	IP address	Description
MachineA	192.168.1.17	Domain controller
MachineB	192.168.100.10	Host controller with GateIn instances
MachineC	192.168.100.20	Host controller with GateIn instances

Domain controller - machineA

[1] Create a Management user which will be used by host controllers to connect to main domain controller.

$JBOSS_HOME/bin/add-user.sh

username: gateinhc / password: gateinhc123. (don't forget final dot '.' char, it is part of the password)

Use this user to allow remote connections of host controllers:

<secret value="Z2F0ZWluaGMxMjMu" />

[2] Change name in $JBOSS_HOME/domain/configuration/host-master.xml from "master" to "machineA".

<host name="machineA" ...

[3] Add GateIn Portal system configuration properties at server-group level:

<server-group name="main-server-group" profile="full"><server-group name="main-server-group" profile="full">
  <jvm name="default">
    <heap size="1303m" max-size="1303m"/>
    <permgen max-size="256m"/>
  </jvm>
  <socket-binding-group ref="full-sockets"/>
  <system-properties>
    <property name="exo.conf.dir" value="${jboss.home.dir}/standalone/configuration/gatein"/>
    <property name="gatein.conf.dir" value="${jboss.home.dir}/standalone/configuration/gatein"/>
    <property name="gatein.portlet.config" value="${jboss.home.dir}/standalone/configuration/gatein"/>
  </system-properties>
</server-group>

[4] Start domain controller on machineA:

$JBOSS_HOME/bin/domain.sh --domain-config=domain.xml --host-config=host-master.xml -Djboss.bind.address.management=192.168.1.17

Host controller - machineB and machineC

[5] Add host name $JBOSS_HOME/domain/configuration/host-slave.xml for machineB and machineC

<host name="machineB" ... <host name="machineC" ...

[6] Update server identities secret to allow connect to domain controller:

<host name="machineC" xmlns="urn:jboss:domain:1.4">

    <management>
        <security-realms>
            <security-realm name="ManagementRealm">
                <server-identities>
                    <secret value="Z2F0ZWluaGMxMjMu"/>
                </server-identities>

...

[7] Add domain controller username to remote configuration:

<remote host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}" username="gateinhc" security-realm="ManagementRealm"/>

[8] We are using ${jboss.home.dir}/standalone/configuration/gatein as common GateIn configuration for our domain, we need to comment gatein.conf.dir property from configuration.properties file as we are going to set up from system properties.

[9] Start host controller from machines B and C:

bin/domain.sh --host-config=host-slave.xml -Djboss.bind.address=192.168.100.10 -Djboss.bind.address.management=192.168.100.10 -Djboss.domain.master.address=192.168.1.17

bin/domain.sh --host-config=host-slave.xml -Djboss.bind.address=192.168.100.20 -Djboss.bind.address.management=192.168.100.20 -Djboss.domain.master.address=192.168.1.17