Depending on your needs, there are several different methods to install JBoss Portal. Pre-configured clustered versions (JBoss Portal Binary (Clustered)) are available from the JBoss Portal Downloads page. Clustered versions of JBoss Portal must be deployed in the JBOSS_INSTALLATION_DIRECTORY/server/all/deploy/ directory. All JBoss AS instances must reference the same datasource. See Section 2.3.2.2, “Operating System Environment Settings” for details on how to configure JBoss Portal for clustering.
An environment variable, JBOSS_HOME, is configured in Section 2.3.2.2, “Operating System Environment Settings”. References to $JBOSS_HOME assume this to be your JBOSS_INSTALLATION_DIRECTORY.
This is the easiest and fastest way to get JBoss Portal installed and running. The JBoss Portal and JBoss AS bundle contains JBoss AS, JBoss Portal, and the embedded Hypersonic SQL database. To install the JBoss Portal and JBoss AS bundle:
Get the bundle: the bundle is available from the JBoss Portal Downloads page. Bundles use the JBoss Portal + JBoss AS naming convention.
Extract the bundle: extract the zip archive. It does not matter which directory is used. On Microsoft Windows, the recommended directory is C:\jboss-version-number.
Start the server: change into the JBOSS_PORTAL_INSTALLATION_DIRECTORY/bin/ directory. On Microsoft Windows, execute run.bat. On Linux, run the ./run.sh command. To specify a configuration to use, for example, the default configuration, append the -c default option to the run.bat or ./run.sh commands.
Log in to JBoss Portal: using a Web browser, navigate to http://localhost:8080/portal to open the JBoss Portal homepage. Log in using one of the two default accounts: username user, password user, or username admin, password admin.
SQL Errors
Tables are automatically created the first time JBoss Portal starts. When deployed for the first time, JBoss Portal checks for the existence of the initial tables, which have not been created yet. This causes errors such as the following, which can safely be ignored:
WARN [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002 ERROR [JDBCExceptionReporter] Table not found in statement ... WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist
The binary package typically consists of the jboss-portal.sar/ directory, documentation such as the JBoss Portal User Guide and the JBoss Portal Reference Guide, and a set of pre-configured Datasource descriptors that allow JBoss Portal to communicate with an external database. This installation method is recommended for users who already have JBoss EAP or JBoss AS installed, or those who need to install JBoss Portal in a clustered environment.
The binary download is available from the JBoss Portal Downloads page. Look for the JBoss Portal Binary package. Once the binary zip file has been downloaded and extracted, the folder hierarchy will look similar to the following:
 |
Files contained in this download will be used in later sections. Download and extract the JBoss Portal binary zip file before proceeding.
Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS installed. Customers who have access to the JBoss Customer Support Portal (CSP) should download and install JBoss EAP 4.2. Customers who do not have access to the JBoss CSP are advised to use JBoss AS. For JBoss AS installation instructions, please refer to the JBoss AS Installation Guide.
Use the JBoss EAP and JBoss AS zip file
Only use the JBoss EAP and JBoss AS zip file versions. DO NOT ATTEMPT to deploy JBoss Portal on the installer version of JBoss EAP or JBoss AS.
A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an embedded Hypersonic SQL database that JBoss Portal can use; however, this is only recommended for developer use. The following databases are recommended for production use, and have had test suites run against them: MySQL 4, MySQL 5, Microsoft SQL Server, PostgreSQL 8, Oracle 9, and Oracle 10. JBoss Portal can use any database that is supported by Hibernate.
To configure a database to use with JBoss Portal:
Create a new database: this guide assumes that the new database will be called jbossportal.
Grant access rights for a user to the jbossportal database: JBoss Portal needs to create tables and modify table data. Grant access rights to a desired user to the jbossportal database. Configure the same username and password in the Datasource descriptor.
Deploy a RDBMS JDBC connector: a RDBMS JDBC connector is required for JBoss Portal to communicate with a database. Copy the connector into the $JBOSS_HOME/server/default/lib/ directory. For example, a RDBMS JDBC connector for MySQL can be download from http://www.mysql.com/products/connector/j/. For the correct RDMBS JDBC connector, please refer to the database documentation.
The JBoss Portal binary download that was extracted in Section 2.2.1.1, “Getting the Binary”, contains pre-configured Datasource descriptors for the more popular databases. Datasource descriptors are provided for the MySQL 4, MySQL 5, PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found in the setup subdirectory where the JBoss Portal binary was extracted to:
 |
Copy the Datasource descriptor that matches your database into the $JBOSS_HOME/server/configuration/deploy/ directory, where configuration is either all, default, minimal or production. The production configuration only exists on JBoss EAP, and not JBoss AS. For example, if you are using the all configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/all/deploy/ directory.
After the Datasource descriptor has been copied into the deploy directory, make sure the username, password, connection-url, and driver-class are correct for your chosen database. Datasource descriptor files can be deployed to test before being used in production. The following is an example Datasource descriptor for the PostgreSQL database:
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>PortalDS</jndi-name>
<connection-url>jdbc:postgresql:jbossportal</connection-url>
<driver-class>org.postgresql.Driver</driver-class>
<user-name>portal</user-name>
<password>portalpassword</password>
</local-tx-datasource>
</datasources>
For further details about Datasource descriptors, please refer to the JBoss JDBC Datasource wiki page.
To start JBoss EAP or JBoss AS and deploy JBoss Portal:
Datasource descriptor: if you have not done so already, change into the setup subdirectory where the JBoss Portal binary was extracted to. Copy the correct Datasource descriptor file (*-ds.xml) you modified in the previous steps into the $JBOSS_HOME/server/configuration/deploy/ directory.
Start the server: change into the $JBOSS_HOME/bin/ directory. On Microsoft Windows, execute run.bat. On Linux, run the ./run.sh command. To specify a configuration to use, for example, the default configuration, append the -c default option to the run.bat or ./run.sh commands.
Log in to JBoss Portal: using a Web browser, navigate to http://localhost:8080/portal to open the JBoss Portal homepage. Log in using one of the two default accounts: username user, password user, or username admin, password admin:
SQL Errors
Tables are automatically created the first time JBoss Portal starts. When deployed for the first time, JBoss Portal checks for the existence of the initial tables, which have not been created yet. This causes errors such as the following, which can safely be ignored:
WARN [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002 ERROR [JDBCExceptionReporter] Table not found in statement ... WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist
The JBoss Portal source files can be obtained from the JBoss Portal Downloads page. The source files download uses a JBoss Portal Source Code naming convention. As well, the sources can be obtained from SVN:
the latest source files of the 2.6 branch: http://anonsvn.jboss.org/repos/portal/branches/JBoss_Portal_Branch_2_6
the latest sources: http://anonsvn.jboss.org/repos/portal/trunk/
Several modules have been extracted from the JBoss Portal SVN repository. These modules have a different lifecycle and a different version scheme. The following is a list of modules used in JBoss Portal 2.6.4, and the locations of their source code:
JBoss Portal Common 1.1.0: http://anonsvn.jboss.org/repos/portal/modules/common/tags/JBP_COMMON_1_1_0
JBoss Portal Web 1.1.0: http://anonsvn.jboss.org/repos/portal/modules/web/tags/JBP_WEB_1_1_0
JBoss Portal Test 1.0.1: http://anonsvn.jboss.org/repos/portal/modules/test/tags/JBP_TEST_1_0_1
JBoss Portal Portlet 1.0.2: http://anonsvn.jboss.org/repos/portal/modules/portlet/tags/JBP_PORTLET_1_0_2
JBoss Portal Identity 1.0.2: http://anonsvn.jboss.org/repos/portal/modules/identity/tags/JBP_IDENTITY_1_0_2
After checking out the source from SVN, or after extracting the JBoss Portal Source Code zip file, a directory structure similar to the following will be created:
 |
If the source files were obtained from SVN, change into the trunk/src/ directory to see the directories from the above image. As well, there will be an empty thirdparty directory. This directory will contain files after building the JBoss Portal source code (Section 2.3.3, “Building and Deploying from the Sources”). For more information about the JBoss Portal SVN repository, and accessing different versions of the JBoss Portal codebase, please visit the JBoss Portal SVN Repo page on the JBoss Wiki.
Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS installed. Customers who have access to the JBoss Customer Support Portal (CSP) should download and install JBoss EAP 4.2. Customers who do not have access to the JBoss CSP are advised to use JBoss AS. For JBoss AS installation instructions, please refer to the JBoss AS Installation Guide.
Use the JBoss EAP and JBoss AS zip file
Only use the JBoss EAP and JBoss AS zip file versions. DO NOT ATTEMPT to deploy JBoss Portal on the installer version of JBoss EAP or JBoss AS. We are currently working on aligning the Application installer with JBoss Portal.
For build targets to work, you must configure a JBOSS_HOME environment variable. This environment variable must point to the root directory of the JBoss EAP or JBoss AS installation directory, which is the directory where the JBoss EAP or JBoss AS files were extracted to.
When using Microsoft Windows, this is accomplished by going to Start > Settings > Control Panel > System > Advanced > Environment Variables. Under the System Variables section, click New. Set the JBOSS_HOME environment variable to the location of your JBoss EAP or JBoss AS installation directory:
 |
To configure the JBOSS_HOME environment variable on Linux:
Add the following line to the ~/.bashrc file. Note: this must be configured while logged in as the user who will run JBoss EAP or JBoss AS:
export JBOSS_HOME=/path/to/jboss/installation/
Run the following command to enable the JBOSS_HOME environment variable:
source ~/.bashrc
JBoss EAP JBOSS_HOME Environment Variable
If you are running JBoss EAP, configure the JBOSS_HOME environment variable to point to the /path/to/jboss-eap-version/jboss-as/ directory.
During the first build, third-party libraries will be obtained from an online repository, so you must be connected to the Internet, and if you are behind a proxy server, you need to define your proxy server address and proxy server port number. If you are running Linux, add the following line to the $JBOSS_HOME/bin/run.sh file:
JAVA_OPTS=-Dhttp.proxyHost=<proxy-hostname> -Dhttp.proxyPort=<proxy-port>
Replace proxy-hostname with the proxy server's hostname, and proxy-port with the correct proxy server port number. If you are running Microsoft Windows, add the following line to the $JBOSS_HOME/bin/run.bat file:
set JAVA_OPTS=-Dhttp.proxyHost=<proxy-hostname> -Dhttp.proxyPort=<proxy-port>
Replace proxy-hostname with the proxy server's hostname, and proxy-port with the correct proxy server port number.
To build and deploy JBoss Portal from the sources, change into the JBOSS_PORTAL_SOURCE_DIRECTORY/build/ directory, where JBOSS_PORTAL_SOURCE_DIRECTORY is the directory where the JBoss Portal source code was downloaded to. Then, Microsoft Windows users need to run the build.bat deploy command, and Linux users need to run the ./build.sh deploy command.
At the end of the build process, the jboss-portal.sar file is copied into the $JBOSS_HOME/server/default/deploy/ directory:
 |
Portal Modules
The previous steps install a bare version of JBoss Portal. In previous versions, several additional modules were deployed as well, but this has since been modularized to provide greater flexibility. To deploy additional modules, see the Portal's module list for more information. To deploy all modules at once, change into the build directory. If you are running Linux, run the ./build.sh deploy-all command. If you are running Microsoft Windows, run the build.bat deploy-all command.
To build the clustered version on Linux Operating Systems:
Change into the JBOSS_PORTAL_SOURCE_DIRECTORY/build/ directory, and run the following command:
./build.sh main
Change into the JBOSS_PORTAL_SOURCE_DIRECTORY/core/ directory, and run the following command:
./build.sh deploy-ha
After the ./build.sh deploy-ha command completes, the jboss-portal-ha.sar file is copied into the $JBOSS_HOME/server/all/deploy/ directory.
To build the clustered version on Microsoft Windows, repeat the previous steps, replacing ./build.sh with build.bat.
A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an embedded Hypersonic SQL database that JBoss Portal can use; however, this is only recommended for developer use. The following databases are recommended for production use, and have had test suites run against them: MySQL 4, MySQL 5, Microsoft SQL Server, PostgreSQL 8, Oracle 9, and Oracle 10. JBoss Portal can use any database that is supported by Hibernate.
To configure a database to use with JBoss Portal:
Create a new database: this guide assumes that the new database will be called jbossportal.
Grant access rights for a user to the jbossportal database: JBoss Portal needs to create tables and modify table data. Grant access rights to a desired user to the jbossportal database. Configure the same username and password in the Datasource descriptor.
Deploy a RDBMS JDBC connector: a RDBMS JDBC connector is required for JBoss Portal to communicate with a database. Copy the connector into the $JBOSS_HOME/server/default/lib/ directory. For example, a RDBMS JDBC connector for MySQL can be download from http://www.mysql.com/products/connector/j/. For the correct RDMBS JDBC connector, please refer to the database documentation.
The JBoss Portal binary download that was extracted in Section 2.2.1.1, “Getting the Binary”, contains pre-configured Datasource descriptors for the more popular databases. Datasource descriptors are provided for the MySQL 4, MySQL 5, PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found in the setup subdirectory where the JBoss Portal binary was extracted to:
|
Copy the Datasource descriptor that matches your database into the $JBOSS_HOME/server/configuration/deploy/ directory, where configuration is either all, default, minimal, or production. For example, if you are using the production configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/production/deploy/ directory. The production configuration only exists on JBoss EAP installations, and not JBoss AS.
After the Datasource descriptor has been copied into the deploy directory, make sure the username, password, connection-url, and driver-class are correct for your chosen database. Datasource descriptor files can be deployed to test before being used in production. The following is an example Datasource descriptor for the PostgreSQL database:
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>PortalDS</jndi-name>
<connection-url>jdbc:postgresql:jbossportal</connection-url>
<driver-class>org.postgresql.Driver</driver-class>
<user-name>portal</user-name>
<password>portalpassword</password>
</local-tx-datasource>
</datasources>
For further details about Datasource descriptors, please refer to the JBoss JDBC Datasource wiki page.
To start JBoss EAP or JBoss AS and deploy JBoss Portal:
Datasource descriptor: if you have not done so already, change into the setup subdirectory where the JBoss Portal binary was extracted to. Copy the correct Datasource descriptor file (*-ds.xml) you modified in the previous steps into the $JBOSS_HOME/server/configuration/deploy/ directory.
Start the server: change into the $JBOSS_HOME/bin/ directory. On Microsoft Windows, execute run.bat. On Linux, run the ./run.sh command. To specify a configuration to use, for example, the default configuration, append the -c default option to the run.bat or ./run.sh commands.
Log in to JBoss Portal: using a Web browser, navigate to http://localhost:8080/portal to open the JBoss Portal homepage. Log in using one of the two default accounts: username user, password user, or username admin, password admin:
SQL Errors
Tables are automatically created the first time JBoss Portal starts. When deployed for the first time, JBoss Portal checks for the existence of the initial tables, which have not been created yet. This causes errors such as the following, which can safely be ignored:
WARN [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002 ERROR [JDBCExceptionReporter] Table not found in statement ... WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist