Chapter 3. Customizing your installation
Prev |  | Next

## Chapter 3. Customizing your installation

### Thomas Heute

`<theute@jboss.org>`

### Roy Russo

`<roy at jboss dot org>`

This section is intended to describe some customization features available in JBoss Portal. If it is not covered here, please view the FAQ chapter at the end of this document or the descriptor chapter ( Section 6.3, “JBoss Portal Descriptors” ) for further documentation on configuration and tuning JBoss Portal.

## 3.1. Changing the port

It is common to have a server running on the port 80 instead of the default port 8080.

It might be easier to use port forwarding than to change the port manually. Since port forwarding is not always possible, below are the instructions to change the port number manually.

To change it, you need to edit the file `$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml` and change the port value of the HTTP Connector.

You can also change the value of the SSL port, by default it is set to 8443. To activate support for HTTPS, please refer to the appropriate chapter of the JBoss AS guide. You might also want to refer to Tomcat's SSL configuration how-to for more details.

Please refer to Section 14.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.

Now you can restart JBoss and use the new port that you defined. On systems like Linux, you need privileges to be able to run a server on a port lower than 1000, starting JBoss on the port 80 as a regular user will not work. For testing purposes, you can start JBoss AS as root but this setup is not recommended if the server is public as it could lead to security breaches of your system.

## 3.2. Changing the context path

By default, the "main" page of JBoss portal will be accessible at `http://localhost:8080/portal/index.html` . You may want to change that either to a different name or to `http://localhost:8080/index.html` .

### Note

By default, Tomcat holds on to the root context '/'. You may need to either remove `$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war` or add a `jboss-web.xml` file (declaring another context-root other than '/') under `ROOT.war/WEB-INF` directory for the below changes to take effect on restart.

    <?xml version="1.0"?>
    <jboss-web>
       <context-root>/tomcat-root</context-root>
    </jboss-web>

You can accomplish this, with either a deployed jboss-portal.sar or before you build from source:

- Binary method:

  1. Open JBOSS_INSTALL_DIRECTORY/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml

         <?xml version="1.0"?>
         <jboss-web>
            <security-domain>java:jaas/portal</security-domain>
            <context-root>/portal</context-root>
            <replication-config>
               <replication-trigger>SET_AND_GET</replication-trigger>
               <replication-type>SYNC</replication-type>
            </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 to whatever you desire.

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

- Source method: Edit the file `$PORTAL_HOME/build/local.properties` (You can copy the file `$PORTAL_HOME/build/etc/local.properties-example` and modify it for your own settings.) and change `portal.web.context-root` to anything you want.

  Now clean the project (ant clean) then build JBoss portal (ant) and redeploy it for the context path changes to take effect. For build instructions, please see: Section 2.3, “Installing from Sources”

## 3.3. Forcing the DB dialect

If you encounter that the Hibernate dialect is not working properly and would like to override the default behavior, follow the instructions contained in this section:

### Note

Under most common circumstances, the auto-detect feature should work fine.

### 3.3.1. DB Dialect settings for Portal

You will need to modify all the `hibernate.cfg.xml` files in all the Portal modules you intend to use by uncommenting the following line in these files and using the appropriate dialect (see here for a list of supported dialects in Hibernate 3):

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

These files are found in `jboss-portal.sar/[module]/conf/hibernate/[directory]/hibernate.cfg.xml` where `[module]` is a module name and `[directory]` is a directory that may or may not be present.

### 3.3.2. DB Dialect settings for the CMS component

Modify `jboss-portal.sar/portal-cms.sar/conf/hibernate/cms/hibernate.cfg.xml` by uncommenting the following line in these files and using the appropriate dialect (see here for a list of supported dialects in Hibernate 3):

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

## 3.4. Setting up the email service

To be able to use the email service (for example to verify user emails when someone subscribes or for CMS workflow notifications) it has to be configured correctly. To configure it, go to `jboss-portal.sar/portal-core.sar/META-INF/jboss-service.xml`. In this file, the mail module is configured like this:

    <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>

Here you can specify a different SMTP server than localhost, then precise the SMTP username and SMTP password to use to send emails.

For example, to use GMail's 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>

### Note

If you have a 'standard' setup and a mail server installed (That's the case on most Linux distribution out of the box), it will work out of the box.

## 3.5. Setting up proxy settings

There are a couple of scenarios where you will 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 set up the proxy settings you will 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 unwrapping

JBoss Portal use the JBoss Microkernel for the service infrastructure. The JBoss Microkernel provides injection of services into other services, also known as wiring. Unfortunately it is only possible to inject dynamic proxies that talks to the MBeanServer due to the fact the Microkernel is JMX based. The overhead at runtime is minimal since the Microkernel implementation is highly optimized, however when it is used with Java 5 a noticeable bottleneck appears due to the fact that the implementation of the JMX API classes javax.management.* provided by the Java Platform performs synchronization. This does not happen 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 to unwrap the injected dynamic proxies and replace them by the real POJO services. This allows to remove the bottleneck with Java 5 and provide an extra boost of performances on JDK 1.4. By default that feature is enabled but it is possible to disabled it using command line arguments.

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

Prev | Up | Next
Chapter 2. Installation | Home | Chapter 4. Upgrading 2.4 - 2.6