Chapter 5. Configuring JBoss Portal Domain Mode

5.1. Deployment Notes for Domain Configurations
5.2. Domain Configuration Variables
5.3. Individual Domain Configuration
5.4. Shared Domain Configuration
5.5. Domain Mode Quickstart
5.6. Multiple Node Domain Scenario
5.6.1. Environment Assumptions
5.6.2. Configure the Domain Controller (Machine A)
5.6.3. Configure Host Controller One (Machine B)
5.6.4. Configure Host Controller Two (Machine C)

5.1. Deployment Notes for Domain Configurations

Portal applications and Java Enterprise Edition applications can be deployed using the domain mode hot-deploy mechanism. Containers and Extensions must be moved into the deployment directory, and will be loaded when JBoss Portal initially starts.

See Also:

Report a bug

5.2. Domain Configuration Variables

JBoss EAP stores configuration elements relating to the application server itself in a separate directory location to JBoss Portal configuration files. The JBoss Portal configuration files are stored in the JBOSS_HOME/standalone/configuration/gatein/ directory. Configuring JBoss Portal to operate in domain mode requires the location of portal-specific configuration to be specified for each instance in a domain.
JBoss Portal provides system property variables that allow portal-specific configuration file paths to be defined once, and reused as variables in other configuration.
exo.conf.dir
Specifies the directory that contains the eXo standalone configuration information the domain server will use.
gatein.conf.dir

Important

When this parameter is defined in system properties, it must be commented or deleted from the configuration.properties file. Issues with server start will occur if this recommendation is ignored.
Specifies the directory that contains the portal standalone configuration the domain server will use.
gatein.portlet.config
Specifies the directory that contains the portlet standalone configuration the domain server will use.
gatein.deploy.config
Specifies the directory that contains the main portal container gatein.ear. The default value is JBOSS_HOME/gatein/.

Important

Portal containers can not be deployed using the domain mode mechanism. Containers must be manually deployed by moving the container into the specified directory. JBoss Portal loads containers on initial server start through a custom service specific to JBoss Portal.
gatein.extensions.config

Important

Portal extensions can not be deployed using the domain mode mechanism. Extensions must be manually deployed by moving the container into the specified directory. JBoss Portal loads extensions on initial server start through a custom service specific to JBoss Portal.
Specifies the directory that contains any portal extensions. The default value is JBOSS_HOME/gatein/extensions.

See Also:

Report a bug

5.3. Individual Domain Configuration

When configuring domain nodes for a managed domain, the configuration variables can be defined using shared domain configuration, or isolated to each server instance.
It is necessary to create the directory structure for domain mode support manually, as JBoss Portal does not support this operation mode by default. The expected domain mode directory structure is JBOSS_HOME/domain/servers/myinstance/configuration/gatein.

Example 5.1. Defining per-server domain configuration

This example describes the system property configuration required in the host.xml file for each server instance. 
<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>

If a domain server instance is manually created using the JBoss EAP management console or the command line interface, the domain configuration variables must be added to each server configuration's system properties to allow the domain instance to start successfully. For a comprehensive overview of management console operations, see the Management Interfaces chapter in the JBoss EAP Administration and Configuration Guide available from https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Enterprise_Application_Platform/6.1/html-single/Administration_and_Configuration_Guide/index.html.

See Also:

Report a bug

5.4. Shared Domain Configuration

When configuring domain nodes for a managed domain, the configuration variables can be defined using individual domain configuration, or shared amongst server groups.
It is necessary to create the directory structure for domain mode support manually, as JBoss Portal does not support this operation mode by default. The expected domain mode directory structure is JBOSS_HOME/domain/servers/myinstance/configuration/gatein.

Example 5.2. Defining shared domain configuration

This example describes the system property configuration required in the domain.xml file for the server group. 
<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>

Defining a server group and adding the domain configuration parameters described in Example 5.2, “Defining shared domain configuration” is also possible from the JBoss EAP management interface or command-line interface. For a comprehensive overview of management console operations, see the Management Interfaces chapter in the JBoss EAP Administration and Configuration Guide available from https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Enterprise_Application_Platform/6.1/html-single/Administration_and_Configuration_Guide/index.html.
Report a bug

5.5. Domain Mode Quickstart

To test the functionality of domain mode, a demonstration is available that features the following configuration highlights:
  • domain.xml/host.xml configuration.
  • Default and Full profiles.
  • Single-host domain with two JBoss Portal instances.
  • Shows how the gatein.extensions.dir configuration parameter is used to allow servers to coexist on the same host.
The demonstration establishes two instances of JBoss Portal that listen on different ports. The instance listening on port 8080 provides WSRP integration and mobile support, while the instance listening on port 8330 provides mobile support only.
One server instance uses the default extensions directory JPP_HOME/gatein/extensions and the second server instance uses an alternative extension location specified in the host.xml file. Both the servers coexist on the same host and a copy of the JPP_HOME/standalone/configuration/gatein directory is created for each server.

Task: Setup and Run the Domain Demonstration

Start the demonstration and use the management console to deploy a portlet application to both server instances.
  1. In a terminal, navigate to JPP_HOME/bin/.
  2. Run the demonstration setup script. 
    ./demo-domain-setup.sh
  3. Once the demonstration setup completes, run JBoss Portal in Domain mode to start the host controller. 
    ./domain.sh
  4. Open http://localhost:9990/console to verify the domain controller is running.
Report a bug

5.6. Multiple Node Domain Scenario

5.6.1. Environment Assumptions

This process describes how to configure a multi-host domain in detail. The machines provisioned as part of this process are described below. Familiarize yourself with the information, because it will be referenced through the configuration steps.
Machine_A
The domain controller, which has an IP address of 192.168.1.17.
Machine_B
A host controller with JBoss Portal instances, which has an IP address of 192.168.100.10.
Machine_C
A host controller with JBoss Portal instances, which has an IP address of 192.168.100.20.

Next Step in Multiple Node Domain Scenario

Report a bug

5.6.2. Configure the Domain Controller (Machine A)

Previous Step in Multiple Node Domain Scenario

Configuring Machine_A

Configure and start the Machine_A domain controller.
  1. Run JPP_HOME/bin/add-user.sh and create a user with the following parameters:
    • User name: gateinhc
    • Password: gateinhc123. (including the trailing full-stop)
    The secret value Z2F0ZWluaGMxMjMu created is used to allow host controller remote connections. Take note of this value.
  2. Change the name of the machine in the JPP_HOME/domain/configuration/host-master.xml <host> element from master to Machine_A
  3. In domain.xml, add the domain configuration parameters inside the main-server-group block. 
    <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. Run the following command to start the domain controller on Machine_A.
    JBOSS_HOME/bin/domain.sh --domain-config=domain.xml --host-config=host-master.xml -Djboss.bind.address.management=192.168.1.17

Next Step in Multiple Node Domain Scenario

Report a bug

5.6.3. Configure Host Controller One (Machine B)

Previous Step in Multiple Node Domain Scenario

Configuring Host Controller One (Machine B)

Configure and start the Machine_B host controller.
  1. Change the name of the machine in the JPP_HOME/domain/configuration/host-slave.xml <host> element from slave to Machine_B.
  2. Update the <server-identities> block with the secret value created in Section 5.6.2, “Configure the Domain Controller (Machine A)” to permit the host machine to connect to the domain controller. 
    <host name="Machine_B" xmlns="urn:jboss:domain:1.4">
 
    <management>
        <security-realms>
            <security-realm name="ManagementRealm">
                <server-identities>
                    <secret value="Z2F0ZWluaGMxMjMu"/>
                </server-identities>
  3. Add the domain controller user name to the host-slave.xml <domain-controller> block. 
    <domain-controller>
  <remote host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}" username="gateinhc" security-realm="ManagementRealm"/>
</domain-controller>
  4. In the JPP_HOME/standalone/configuration/gatein/configuration.properties file for Machine_B, comment or delete the gatein.conf.dir property.
  5. Start Machine_B with the following command:
    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
Report a bug

5.6.4. Configure Host Controller Two (Machine C)

Configuring Host Controller Two (Machine C)

Configure and start the Machine_C host controller.
Completing this task provisions the last host controller, after which the domain is ready for use.
  1. Change the name of the machine in the JPP_HOME/domain/configuration/host-slave.xml <host> element from slave to Machine_C.
  2. Update the <server-identities> block with the secret value created in Section 5.6.2, “Configure the Domain Controller (Machine A)” to permit the host machine to connect to the domain controller. 
    <host name="Machine_B" xmlns="urn:jboss:domain:1.4">
 
    <management>
        <security-realms>
            <security-realm name="ManagementRealm">
                <server-identities>
                    <secret value="Z2F0ZWluaGMxMjMu"/>
                </server-identities>
  3. Add the domain controller user name to the host-slave.xml <domain-controller> block. 
    <domain-controller>
  <remote host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}" username="gateinhc" security-realm="ManagementRealm"/>
</domain-controller>
  4. In the JPP_HOME/standalone/configuration/gatein/configuration.properties file for Machine_C, comment or delete the gatein.conf.dir property.
  5. Start Machine_C with the following command:
    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
Report a bug