Prev |  | Next

## Chapter 3. Customizing your Installation

### Thomas Heute

### Roy Russo

This chapter describes how to customize the default installation. This includes the JBoss EAP or JBoss AS listening port, email and proxy settings, and database dialect settings. For further configuration details, refer to Section 6.3, “JBoss Portal Descriptors” and Chapter 27, Troubleshooting and FAQ.

## 3.1. Changing the Port

It is common for web services to run on port 80. By default, JBoss EAP and JBoss AS use port 8080. If you can not use port forwarding, it is recommended to change the port JBoss EAP or JBoss AS listens on. To change the default port, open the `$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml` file, and edit the `Connector port` value for the `jboss.web` service; however, this configuration only applies to Apache Tomcat:

    <Service name="jboss.web">

    <Connector port="8088" address="${jboss.bind.address}"

This example changes the default port to port 8088. The JBoss EAP or JBoss AS server must be restarted before the new port settings take affect.

The default SSL port is 8843. To enable HTTPS support, refer to the JBoss AS Guide. For further information, refer to the Apache Tomcat SSL configuration how-to.

Please refer to Section 15.3.1, “Considerations to use WSRP when running Portal on a non-default port or hostname” to update the WSRP service after having changed the port.

## Root User Privileges

Linux operating systems require root user privileges to run a service on a port less than 1024. Starting JBoss EAP or JBoss AS on port 80 as a non-privileged user will not work. Running JBoss EAP or JBoss AS as the root user could lead to security breaches.

## 3.2. Changing the Context Path

By default, the main JBoss Portal page is accessible by navigating to http://localhost:8080/portal/index.html. This can be changed to a different path, for example, http://localhost:8080/index.html. The context path can be changed when using the deployed `jboss-portal.sar/`, or before building from source. To change the context path when using the JBoss Portal binary package:

1. Open the $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml file. If this file does not exist, copy and save the following example:

       <?xml version="1.0"?>
       <jboss-web>
          <security-domain>java:jaas/portal</security-domain>
          <context-root>/portal</context-root>
          <replication-config>
             <replication-trigger>SET</replication-trigger>
          </replication-config>
          <resource-ref>
             <res-ref-name>jdbc/PortalDS</res-ref-name>
             <jndi-name>java:PortalDS</jndi-name>
          </resource-ref>
       </jboss-web>

2. Edit the `<context-root>` element with the desired context path:

       <context-root>/testing</context-root>

   Using this example, the main JBoss Portal page would be reached by navigating to http://localhost:8080/testing.

To change the context path when building from source:

1. Change into the directory where the `JBoss Portal Source Code` ZIP file was extracted to, or where the source from SVN was checked out to. Copy the `build/etc/local.properties-example` file and save it as `build/local.properties`.

2. Open the `build/local.properties` file and edit the `portal.web.context-root` option with the desired context path:

       # Context root for the portal main servlet
       portal.web.context-root=/testing

   Using this example, the main JBoss Portal page would be reached by navigating to http://localhost:8080/testing.

3. To clean the project, make sure you are connected to the Internet, and change into the `build/` directory. Run the `ant clean` command.

4. Rebuild and redeploy JBoss Portal. Refer to Section 2.3, “Installing from the Sources” for build instructions.

### 3.2.1. Changing the context-root

By default, Apache Tomcat holds on to the root context, /. You may need to remove the `$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war/` directory, or add a `jboss-web.xml` file, which declares another context-root other than /, under the `$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war/WEB-INF/` directory, for the above changes to take affect. The following is an example `jboss-web.xml` file, which changes the Apache Tomcat context path to `/tomcat-root`:

    <?xml version="1.0"?>

    <jboss-web>

       <context-root>/tomcat-root</context-root>

    </jboss-web>

## 3.3. Forcing the Database Dialect

This sections describes how to override the Database (DB) dialect settings. Under most circumstances, the auto-detect feature works. If the Hibernate dialect is not working correctly, override the default behavior by following the instructions in this section.

### 3.3.1. Database Dialect Settings for JBoss Portal

All `hibernate.cfg.xml` files in all JBoss Portal modules you intend to use need to be modified. The `hibernate.cfg.xml` files are found in the `jboss-portal.sar/`module`/conf/hibernate/`directory`/` directory, where `module` is the module name, and `directory` is a directory that, depending on the module, may or may not exist.

To modify these files to force the DB dialect, un-comment the following line from each `hibernate.cfg.xml` file in each JBoss Portal module you intend to use, so that it looks like the following:

    <!-- Force the dialect instead of using autodetection -->

    <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>

Note: this example is for a PostgreSQL database. If you use another database, you need to modify `org.hibernate.dialect.PostgreSQLDialect` to reflect the correct database. For a list of supported dialects, refer to the dialects list on the Hibernate website.

### 3.3.2. DB Dialect Settings for the CMS Component

To modify the DB dialect setting for the JBoss Portal CMS component:

1. Open the `jboss-portal.sar/portal-cms.sar/conf/hibernate/cms/hibernate.cfg.xml` file.

2. Un-comment the following line, so that it looks like the following:

       <!-- Force the dialect instead of using autodetection -->
       <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>

Note: this example is for a PostgreSQL database. If you use another database, you need to modify `org.hibernate.dialect.PostgreSQLDialect` to reflect the correct database. For a list of supported dialects, refer to the dialects list on the Hibernate website.

## 3.4. Configuring the Email Service

If you have a standard setup and a mail server installed, the email service should work without any extra configuration. Most Linux distributions have a mail server installed by default. The email service, for example, can be used to verify a user's email address when a user subscribes, or for CMS workflow notifications.

The email service is configured using the `$JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml` file. The following is an example of the section which is used to configure the email service:

    <mbean

    code="org.jboss.portal.core.impl.mail.MailModuleImpl"

    name="portal:service=Module,type=Mail"

    xmbean-dd=""

    xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">

    <xmbean/>

    <depends>jboss:service=Mail</depends>

    <depends>portal:service=Module,type=IdentityServiceController</depends>

    <attribute name="QueueCapacity">-1</attribute>

    <attribute name="Gateway">localhost</attribute>

    <attribute name="SmtpUser"></attribute>

    <attribute name="SmtpPassword"></attribute>

    <attribute name="JavaMailDebugEnabled">false</attribute>

    <attribute name="SMTPConnectionTimeout">100000</attribute>

    <attribute name="SMTPTimeout">10000</attribute>

    <attribute name="JNDIName">java:portal/MailModule</attribute>

    </mbean>

A different SMTP server (other than localhost) can be configured, along with a SMTP username and an SMTP password. The following is an example configuration that uses the Gmail SMTP server:

    <mbean

    code="org.jboss.portal.core.impl.mail.MailModuleImpl"

    name="portal:service=Module,type=Mail"

    xmbean-dd=""

    xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">

    <xmbean/>

    <depends>jboss:service=Mail</depends>

    <depends>portal:service=Module,type=IdentityServiceController</depends>

    <attribute name="QueueCapacity">-1</attribute>

    <attribute name="Gateway">smtp.gmail.com</attribute>

    <attribute name="SmtpUser">username@gmail.com</attribute>

    <attribute name="SmtpPassword">myPassword</attribute>

    <attribute name="JavaMailDebugEnabled">false</attribute>

    <attribute name="SMTPConnectionTimeout">100000</attribute>

    <attribute name="SMTPTimeout">10000</attribute>

    <attribute name="JNDIName">java:portal/MailModule</attribute>

    </mbean>

Using this example, replace `username@gmail.com` and `myPassword` with your correct Gmail username and password.

## 3.5. Configuring proxy settings

There are a couple of scenarios where you need your proxy to be correctly defined at the JVM™ level so that you can access documents from Internet. It could be to get the thirdparty libraries if you decided to build JBoss Portal from the sources, to access RSS feeds or weather information in the samples portlet we provide or for your own needs.

To configure the proxy settings, you need to know the proxy host and the port to use. Then, add them when starting Java.

Usually setting up JAVA_OPTS environment variable to `-Dhttp.proxyHost=YOUR_PROXY_HOST -Dhttp.proxyPort=YOUR_PROXY_PORT` is enough.

## 3.6. Disabling Dynamic Proxy Un-wrapping

JBoss Portal uses the JBoss Microkernel for the service infrastructure. The JBoss Microkernel provides injection of services into other services, otherwise known as wiring. Due to the Microkernel being JMX™ based, it is only possible to inject dynamic proxies that talk to the MBeanServer. The overhead at runtime is minimal since the Microkernel implementation is highly optimized; however, when it is used with Java 5, a noticeable bottleneck occurs due to the fact that the implementation of the JMX API classes, javax.management.*, provided by the Java Platform, perform synchronization. This does not occur under JDK™ 1.4, since those classes are implemented by JBoss MX.

JBoss Portal services use a special kind of Model MBean called JBossServiceModelMBean, which allows the un-wrapping of injected dynamic proxies, and replaces them with Plain Old Java Object (POJO) services. This removes the bottleneck when using Java 5, and also provides a performance boost on JDK 1.4. By default this feature is enabled, but it is possible to disable. To do this on Linux operating systems, change into the `$JBOSS_HOME/bin/` directory and run the following command:

    sh run.sh -Dportal.kernel.no_proxies=false

On Windows, run the following command:

    run.bat -Dportal.kernel.no_proxies=false

Prev |  | Front page | Next