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 26, Troubleshooting and FAQ.
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 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 Tomcat's SSL configuration how-to.
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.
Linux 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.
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:
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>
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:
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.
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.
To clean the project, make sure you are connected to the Internet, and change into the build/ directory. Run the ant clean command.
Rebuild and redeploy JBoss Portal. Refer to Section 2.3, “Installing from the Sources” for build instructions.
By default, 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 Tomcat context path to /tomcat-root:
<?xml version="1.0"?> <jboss-web> <context-root>/tomcat-root</context-root> </jboss-web>
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.
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.
To modify the DB dialect setting for the JBoss Portal CMS component:
Open the jboss-portal.sar/portal-cms.sar/conf/hibernate/cms/hibernate.cfg.xml file.
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.
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.
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.
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 systems, change into the $JBOSS_HOME/bin/ directory and run the following command:
sh run.sh -Dportal.kernel.no_proxies=false
On Microsoft Windows systems, run the following command:
run.bat -Dportal.kernel.no_proxies=false