Configure JBoss Portal with Apache on Linux

Important Note:
This documents assumes that you are familiar with basic Linux tasks, including work in shell environment, changing files using "vi" editor and understanding of basic Apache concepts. Anyway, when in doubt, please contact your system administrator for assistance. My opinion is that many users who are able to install Linux on their PC should not have problems reading and using this document. It will help them install JBoss Portal quickly, hopefully under 30 minutes.

Part 1: Prepare Linux Server

It is recommended to configure JBoss to run in an unprivileged account. For example, you can create a new group and user account to run JBoss services. These are tasks to run as "root" user:

# create group - change group id as needed
groupadd -g 502 jboss
# create user - change user id as needed
useradd -u 502 -g jboss -c "JBoss Admin" jboss
# Allow sudo access as jboss user
# Replace username "johndoe" with your private account name
echo "johndoe ALL=(root) /bin/su - jboss" > /etc/sudoers

Also, you need to add host information to the "/etc/hosts" file, so that JBoss and Apache can resolve the host name:

# Example - you need to use FQDN as required
127.0.0.1 localhost.localdomain www.myportalsite.com

Part 2: JBoss Portal Install

Please note that you can use direct login to "jboss" account if password is set by "root" user. We recommend using sudo access as it is more secure. Now you can login as JBoss admin:

sudo su - jboss
Password: (enter your own password)

Once you are logged in, you can start product installation. It is required to download ANT and JDK in addition to JBoss Portal. There are different recommendations how to layout directories for multiple products - here is presented very simple way to manage product distribution download, program code and log files.

# Create directory structure
mkdir dist product logs
# download required software - JBoss Portal, ANT, JDK
cd ~/dist
# these steps are usually done using browser or FTP client
# 1. download JBoss Portal from www.jboss.org
# 2. download ANT from www.apache.org
# 3. download self extracting JDK 1.5 for Linux from java.sun.com
# this is required to run the installation script for JDK
chmod 755 jdk-1_5_0_14-linux-i586.bin

When you are finished with the download, you should see the following files (please note that versions will change so, as a rule of thumb, use the latest version for development purpose):

[jboss@www1 dist]$ ls -1
apache-ant-1.7.0-bin.zip
jboss-portal-2.6.3.GA-bundled.zip
jdk-1_5_0_14-linux-i586.bin

Now you can start the installation process:

cd ~/product
unzip ~/dist/jboss-portal-2.6.3.GA-bundled.zip
unzip ~/dist/apache-ant-1.7.0-bin.zip
~/dist/jdk-1_5_0_14-linux-i586.bin

# list the content of product directory
[jboss@www1 product]$ ls -1
apache-ant-1.7.0
jboss-portal-2.6.3.GA
jdk1.5.0_14

Once the installation is done, you need to configure environment, startup and shutdown scripts.

Part 3: Configure Environment and Scripts

Add the following lines to .bashrc file in "jboss" home directory:

export JBOSS_HOME=/home/jboss/product/jboss-portal-2.6.3.GA
export JAVA_HOME=/home/jboss/product/jdk1.5.0_14
export ANT_HOME=/home/jboss/product/apache-ant-1.7.0
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH

Create "jbstart" script in the home directory:

# this is jbstart script that allows JBoss running in the background
LOGFILE=~/logs/run.log
RUNOPTIONS="-b www.myportalsite.com"
cd $JBOSS_HOME/bin
nohup ./run.sh $RUNOPTIONS >$LOGFILE 2>&1 &

Create "jbstart" script in the home directory:

# this is jbstop script that shuts down JBoss
cd $JBOSS_HOME/bin
./shutdown.sh -s www.myportalsite.com -S

Make these scripts executable:

chmod 755 jbstart jbstop

Now you can logout and login again to make sure that environment is set correctly. Once you confirm that you have proper environment variables (JBOSS_HOME, ANT_HOME, JAVA_HOME and PATH), you can start the JBoss Portal server. Please note that it may take couple minutes for startup process to complete:

# Start JBoss and check log file
./jbstart
cd ~/logs
tail -f run.log
# if everything is OK you will get
20:38:36,891 INFO [Server] JBoss (MX MicroKernel) [4.2.2.GA (build:
SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 3m:25s:555ms

Verify the processes running as "jboss" user and you should see one java process running. Now you can test the shutdown script:

# Stop JBoss
cd ~
./jbstop
# verify processes couple times
ps -ef|grep jboss
# should be no Java processes listed after 20-30 seconds.

After both scripts are working correctly, you can start the JBoss Portal again and test access using http://www.myportalsite.com:8080/portal or similar URL. At this point, you can access Portal on port 8080. The next section will describe how to configure Apache proxy to run on port 80.

Part 4: Configure Apache Server

These steps need to run as root. You need to change main Apache configuration file by adding virtual server configuration and reverse proxy settings. If you do not feel comfortable making changes or experience problems, please contact Apache experts for advice.

# Apache configuration - add to /etc/httpd/conf/httpd.conf file

<VirtualHost *:80>
    ServerAlias www.myportalsite.com
    DocumentRoot /home/jboss/product/jboss-portal-2.6.3.GA/docs
    Options Indexes +FollowSymLinks
    ProxyPreserveHost On
    ProxyPass / http://www.myportalsite.com:8080/
    ProxyPassReverse / http://www.myportalsite.com:8080/
</VirtualHost>

Now you can restart Apache:

[root@www1 ~]# /etc/init.d/httpd stop
Stopping httpd:                                            [ OK ]
[root@www1 ~]# /etc/init.d/httpd start
Starting httpd:                                            [ OK ]

Part 5: Test Access to Portal Site

At this point, you should be able to access default portal page using URL that is similar to this one (based on your FQDN for the server):
http://www.myportalsite.com/portal

JBoss Portal comes preinstalled with two accounts "user/user" and "admin/admin". Unless it is purely for basic testing purpose, I would recommend the following:

Create your personal account using "User Porlet". It is quick, you need to provide username, password and email only. After account is created, you can login using "Login" link in the right upper corner of default portal page.
Login as admin/admin to:

Disable user/user account
Change admin password