Table of Contents
Many IT organizations look to achieve a competitive advantage for the enterprise by improving business productivity and reducing costs. Today's top enterprises are realizing this goal by deploying enterprise portals within their IT infrastructure. Enterprise portals simplify access to information by providing a single source of interaction with corporate information. Although today�s packaged portal frameworks help enterprises launch portals more quickly, only JBoss Portal can deliver the benefits of a zero-cost open source license combined with a flexible and scalable underlying platform.
JBoss Portal 2.0 provides an open source and standards-based environment for hosting and serving a portal�s Web interface, publishing and managing its content, and customizing its experience. It is entirely standards-based and supports the JSR-168 portlet specification, which allows you to easily plug-in standards-compliant portlets to meet your specific portal needs. JBoss Portal 2.0 is available through the business-friendly LGPL open source license and is supported by JBoss Inc. Professional Support and Consulting. JBoss support services are available to assist you in designing, developing, deploying, and ultimately managing your portal environment. JBoss Portal is currently developed by JBoss, Inc. developers, Novell developers, and community contributors.
The JBoss Portal 2.0 framework and architecture includes the portal container and supports a wide range of features including standard portlets, single sign-on, clustering and internationalization. Portal themes and layouts are configurable. Fine-grained security administration down to portlet permissions rounds out the security model. JBoss Portal 2.0 includes a rich content management system and message board support.
JBoss Portal Resources:
The JBoss Portal team encourages you to use this guide to install and configure JBoss Portal. If you encounter any configuration issues or simply want to take part in our community, we would love to hear from you in our forums.
The following list details features found in this document's related release. Currently, this is JBoss Portal 2.0 Final. For a technical view of our features, view the Project Roadmap and Task List.
Technology and Architecture
Portal and Portal Container
Themes and Layouts
User and Group Functionality
Permissions Management
Content Management System
Message Boards
This document is intended for those using JBoss Portal. It details the default features found within the standard Portal distribution and adresses configuration issues found in each component. For developers wanting to develop and deploy custom portlets, create/deploy custom themes, or utilize the JBoss Portal API, there is a reference document available.
We would like to thank all the developers that participate in the JBoss Portal project effort.
Specifically,
Remy for his help with Tomcat configuration.
The Nodesk team that gave us our default theme.
Kev "kevs3d" Roast for supplying us with two working portlets that integrate esisting frameworks in to the portal: Sun JSF-RI and Spring MVC Portlet. These formed the base for our sample pack.
Swarn "sdhaliwal" Dhaliwal for supplying us with the Struts-Bridge, that will allow for existing struts applications to work with the Portal.
Contributions of any kind are always welcome, you can contribute by providing ideas, filling bug reports, producing some code, designing a theme, writing some documentation, etc... To report a bug please use our Jira system.
Here is a list of tested versions or reported as working by users, before reporting a problem please make sure that you are using a compatible version.
If you successfully installed JBoss portal on versions not listed here please let us know so we can add it here.
Currently we recommend ONLY using JBoss AS 4.0.2, or greater. Previous versions of JBoss Application Server are not supported, as JBoss Portal is configured to work with Hibernate3.
JBoss Portal employs Hibernate as an interface to RDBMS. Any DB supported by Hibernate will work with JBoss Portal.
MySQL is the database used for our testings, 4.0.22 is one version that has been fully tested.
There are a couple of archives that you will need to download in order to install JBoss Portal.
Of course you will need to install JBoss Application Server prior to install JBoss portal, if you didn't do so yet, please install JBoss 4.0.2 from Sourceforge.
You can download JBoss portal in different ways, packaged in binaries, sources or from the CVS.
You will need a database to store the data of the system, you can use any database supported by Hibernate. We have tested JBoss Portal on the following, but other should work just the same:
MySQLDB
Hypersonic DB
PostGreSQL
Oracle 10g
All databases supported by hibernate are support by JBoss Portal. Below is a generic ordered list of steps that should be followed on any DB:
Create a new Database. For MySQL we name it jbossportal.
Give access rights to whatever user with whatever password to this new database. For MySQL we create a user "portal" and give him a password "portalpassword", and grant him rights to the jbossportal DB.
As of JBoss Portal RC2, all database tables will be created for you at runtime. The only thing you need to make certain is that there is a database created, a working JDBC connector, and that the user/password combination works.
If you need a custom setup of JBoss AS, you should read the documentation about JBoss application server. In our case, we will use the default configuration shipped with JBoss AS 4.0.2.
At this stage you should have the jboss-4.0.2.zip or any other archive of the same version. First you need to setup JBOSS_HOME environment variable otherwise you won't be able to compile JBoss Portal. To do so go to Start > Settings > Control Panel > System > Advanced > Environment Variables, and add the JBOSS_HOME environment variable. Or do export JBOSS_HOME=/path/to/your/jboss/directory on a Unix-like system.
The downloaded archive contains the following files:
It is important that you configure the correct datasource file under /setup. There are a few already created for support of popular databases. You can also create your own. Please verify that the username, password, url, and driver-class are correct for your flavor of DB. You can deploy the datsource file by itself to test, in advance.
Copy/Move jboss-portal.sar, portal-forums.ear, and your configured portal datasource file to $JBOSS_HOME/server/default/deploy
First, build the sources and deploy them, go to jboss-portal-2.0/build and type sh build.sh deploy, you should read BUILD SUCCESSFUL at the end of the operation. This operation should have copired the jboss-portal.sar to your $JBOSS_HOME/server/default/deploy directory.
Make sure that JBOSS_HOME is still defined in the environment or it will not work.
Now you will need to build the datasource files for DB access. To do so go to jboss-portal-2.0/core and type sh build.sh datasource. It will create all the files under jboss-portal-2.0\core\output\resources\setup.
It is important that you configure the correct datasource file jboss-portal-2.0\core\output\resources\setup. There are a few already created for support of popular databases. You can also create your own. Please verify that the username, password, url, and driver-class are correct for your flavor of DB. You can deploy the datsource file by itself to test, in advance.
Before you deploy the application by itself, you will need to have the database deployment descriptor (portal-*-ds.xml) in the $JBOSS_HOME\server\default\deploy directory. To do so copy the correct portal-*-ds.xml file in to the /deploy directory.
You will also need to put the jar file of your database connector in $JBOSS_HOME\server\default\lib, if you have not already done so.
Now you can start JBoss AS by going into $JBOSS_HOME/bin and typing run. All database tables, cms directories, and initial content for each will be created/inserted during the startup process, if it does not exist.
Using your browser, navigate to http://localhost:8080/portal and you should see the portal.
It is common to have a server running on the port 80 instead of the default port 8080, to change that you will need to change it at two levels:
To change it at the server level, you need to edit the file $JBOSS_HOME/server/default/deploy/jbossweb-tomcat50.sar/server.xml and change the port value of the HTTP Connector to the same value as you defined in the portal.
Next, you will need to modify the web.xml descriptor in the CMSPortlet for it to be able to find the webDAV server. You can find more information about how to do this here.
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 you can log as root but is not recommended if the server is public as it could be a security breach in your system.
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.
Now you can rebuild JBoss portal and redeploy it tfor the context path changes to take effect.
If you would like to re-create the initial database tables, ie. start with a blank install, you can do it by following these steps:
Log in to the JMX-Console: http://localhost:8080/jmx-console/
Locate the portal hibernate mbean. From this screen, you can execute operations.
To drop the database tables and recreate them, first execute destroySchema(). Then execute, createSchema(). Finally execute createContent().
The database should now be restored to how it was on initial install and deployment.
If you encounter that the Hibernate dialect is not working properly and would like to override the default behaviour, you simply need to modify jboss-portal.sar/conf/hibernate/hibernate.cfg.xml. A list of supported dialects for Hibernate3, can be found here.
<?xml version='1.0' encoding='utf-8'?> <!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD//EN" "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> <hibernate-configuration> <session-factory name="java:portal/SessionFactory"> <property name="connection.datasource">java:@portal.datasource.name@</property> <property name="show_sql">false</property> <!-- Force the dialect instead of using autodetection --> <!-- <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property> --> <!-- Mapping files --> <mapping resource="org/jboss/portal/core/impl/role/RoleImpl.hbm.xml"/> <mapping resource="org/jboss/portal/core/impl/user/UserImpl.hbm.xml"/> <mapping resource="org/jboss/portal/core/impl/user/UserPref.hbm.xml"/> <mapping resource="org/jboss/portal/core/impl/user/UserPrefSet.hbm.xml"/> </session-factory> </hibernate-configuration>
Managing users using the user module consists in:
The following xml block is the standard configuration for the UserPortlet found in portal-core.war/WEB-INF/portlet.xml:
<portlet> <portlet-name>UserPortlet</portlet-name> <portlet-class>org.jboss.portal.core.portlet.user.UserPortlet</portlet-class> <supported-locale>en</supported-locale> <supported-locale>fr</supported-locale> <resource-bundle>Resource</resource-bundle> <supports> <mime-type>text/html</mime-type> <portlet-mode>VIEW</portlet-mode> </supports> <portlet-info> <title>User portlet</title> </portlet-info> <init-param> <description>Whether we should use ssl on login and throughout the Portal. 1=yes;0=no</description> <name>useSSL</name> <value>0</value> </init-param> <init-param> <description>Subscription mode</description> <name>subscriptionMode</name> <!-- <value>emailVerification</value>--> <value>automatic</value> </init-param> <init-param> <description>Domain of your website for email verification.</description> <name>emailDomain</name> <value>JBoss.com</value> </init-param> <init-param> <description>Email displayed in the TO field</description> <name>emailFrom</name> <value>jbossportal@example.com</value> </init-param> <init-param> <description>Default role of registered users</description> <name>defaultRole</name> <value>Users</value> </init-param> </portlet>
The following attributes can be modified in the xml descriptor:
Allows for user logins to be passed thru a SSL.
Set to zero to disable.
Set to 1 to enable. You must have SSL configured properly in tomcat for this to work.
The user can register and is automatically enabled
The user is disabled until he clicks on a link sent to his email address.
Your domain name or the name of your website for the email verification form text.
Email address that will appear in the "From" header when the email verification is sent.
Default role assigned to new users
The role portlet is dedicated to create and edit roles. A role will be used to grant different permission level to different portlets. A user can have several roles (for example he can be an administrator of a category of forum but only a reader on another category)
To create a new role, you just need to define a short name that will be used for reference, and a display name for displaying to the user, for example admin would be a good name for the display name Administrators, changing the display name will not affect the security rules
While editing a role, you just need to pick an exising role then change the display name.
The CMS Portlet displays content from the file store inside a portlet window, or, in the case of binary content, outside of the portlet window altogether.
As of JBoss Portal Beta 1, the CMSPortlet handles all requests for all content types.
The methodology of serving content within the CMSPortlet, allows for some beneficial features, like:
JBoss Portal uses Jakarta Slide as its WebDAV repository. This allows most web and file browsers to navigate to a shared repository and, given the proper rights, allows for modification of content.
Here is the default configuration for the CMS respository found under portal-core.war/WEB-INF/web.xml:
<?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> <context-param> <param-name>URL</param-name> <param-value>http://localhost:8080/webdav/files</param-value> <!-- Comment out for SSL communication between Portal and Webdav --> <!-- <param-value>http://localhost:443/webdav/files</param-value> --> <description>WebDAV server URL</description> </context-param> <context-param> <param-name>rootdir</param-name> <param-value>/files</param-value> <description>WebDAV Directory Root</description> </context-param> </web-app>
URL: This is the absolute URL for the webdav store. Comment out the appropriate param-value for SSL communication between the portal and webdav layer.
rootdir: specifies the base root directory for the WebDAV store. Under normal circumstances this should not be changed.
One additional item that is worth noting is that the slide store can be configured to access from a RDBMS using the Portal DataSource instead of the default filesystem store, by modifying portal-cms.sar/META-INF/jboss-service.xml.
<!-- The slide configuration using the database. Uncomment this and comment the above tx store for Database usage. --> <!-- <definition> <store name="j2ee"> <nodestore classname="org.apache.slide.store.impl.rdbms.J2EEStore"> <parameter name="datasource">@portal.datasource.name@</parameter> <parameter name="adapter">org.apache.slide.store.impl.rdbms.MySqlRDBMSAdapter</parameter> <parameter name="compress">false</parameter> </nodestore> <securitystore> <reference store="nodestore"/> </securitystore> <lockstore> <reference store="nodestore"/> </lockstore> <revisiondescriptorsstore> <reference store="nodestore"/> </revisiondescriptorsstore> <revisiondescriptorstore> <reference store="nodestore"/> </revisiondescriptorstore> <contentstore> <reference store="nodestore"/> </contentstore> </store> <scope match="/" store="j2ee"/> </definition> -->
To activate the DB store, uncomment the above configuration and comment the below information:
<!-- The slide configuration using the file system. --> <definition> ... </definition>
To create the proper DB tables, you will need to execute one the schema files found in this archive
The AdminCMS Portlet allows control over the content management system.
Viewing the AdminCMS Portlet is accomplished by logging in as an admin (admin/admin) and navigating to the admin page http://localhost:8080/portal/index.html?ctrl:id=page.default.admin
You should then be presented by a page that is similar to this:
It is important for a user to note the action icons used throughout the portlet and their meanings. The action options change depending on what type of resource the user is dealing with. All possible actions are listed here:
Additionally, there are icons that help describe the types of resources present on the page:
This section describes common actions a user can perform from within the AdminCMS Portlet.
A user can list directory contents by either clicking on the
icon, or clicking on the directory's "DisplayName". All
actions are possible from this screen.
Clicking on the icon or the "DisplayName" of a file brings up the File
Properties page.
The File Properties window displays all the possible actions available to perform on a file. It displays certain properties of the file: DisplayName, FileSize, Content-Type, Creation Date, and when it was last modified.
Version Information is also contained on this screen. It is important to note that the top-most version in the list is the current version that is "live". Editting an older version of a file and saving it, will auto-create a new version of the file and make it the current "live" version.
Clicking on the icon displays the copy file/directory dialog
window.
The copy resource window allows a user to copy files to any folder
on the system, as well as copy whole directory trees to any directory on
the system. A user can select which destination directory to copy the
resource to, by using the directory browser. Clicking the icon expands the directory tree. Clicking on the name
of the directory within the tree, sets it as the destination directory
for the copied resource.
Clicking on the icon displays the move file/directory dialog
window.
The move resource window allows a user to move files to any folder
on the system, as well as move whole directory trees to any directory on
the system. A user can select which destination directory to move the
resource to, by using the directory browser. Clicking the icon expands the directory tree. Clicking on the name
of the directory within the tree, sets it as the destination directory
for the moved resource.
Clicking on the icon displays the delete file/directory confirmation
window.
The delete resource confirmation window allows a user to delete a file, or a directory on the system. Note that deleting a directory, will delete the entire tree, so all directories under the deleted one, will also be deleted.
Clicking on the icon displays the create directory dialog
window.
The create directory resource window allows a user to create a directory under the one he originally clicked the icon in. On this window, a user can specify a name for the new empty directory.
Clicking on the icon displays the create file dialog window with the
embedded WYSIWYG editor and directory browser.
The create file window allows a user to create a text or HTML file
using the embedded WYSIWYG HTML editor. The editor is a fully-functional
HTML editor with a myriad of HTML functions. It also includes a preview
button and a source view
button.
An in-depth walk-through of the editor is beyond the scope of this
document. However, the editor does contain help pages within it, that
can be accessed by clicking the icon.
Clicking on the icon displays the upload file dialog window.
The upload file window allows a user to upload files to any
directory on the system. The upload process will work on files up to 1GB
and of all types. A user can select which destination directory to
upload the resource to, by using the directory browser. Clicking the
icon expands the directory tree. Clicking on the name
of the directory within the tree, sets it as the destination directory
for the uploaded resource.
Clicking on the icon displays the edit file dialog window with the
embedded WYSIWYG editor and directory browser.
The edit file window allows a user to edit a text or HTML file
using the embedded WYSIWYG HTML editor. The editor is a fully-functional
HTML editor with a myriad of HTML functions. It also includes a preview
button and a source view
button.
The portlet aims at attributing roles to a permission. Below is an example to setup permissions for the forums portlet.
At the very top, a domain can be specified. A domain is defined by the portlet, it can be the name of a portal for example. It gives the scope of the permissions. THe first screen gives you the top level privileges, usually it will show global permissions.
Defined roles gives the list of roles that has been defined for the corresponding permission while implied roles will show all the roles that are implied. For example in the forums, the admin role implies the add permission, defining the role "Admins" on the Admin permission, would show "Admins" in the implied roles of the add permission. Only defined roles can be removed so if a permission need to be restricted, the most permissive permission has to be removed before a less permissive one is added.
Under the global permissions, there is a list of sub-components for a finer grain permission definition. For example, the forums portlet gives the ability to define permissions on a single category. By clicking on the category, the following screen would show up:
The forums security model dictates that the global admin permission implies the category admin permission, and the global add permission implies the category read permission, with that in mind, the implied roles should make sense. If you select a sub-component, you can define an even finer-grain permission and the following screen will show up:
The forums portlet is a port of the phpBB forums as a Java portlet. It is packaged independently of the core, so you can easily use it or not depending on your own needs.
Above is the main window displayed by default to any user. It lists all the forums classified by categories. It is possible to see how many topics and posts where written for each forum and the date and user of the last post. All those categories and forums can be configured if the user has the correct privileges. The next image show the main administration interface available to users with the correct credentials.
User features:
Admin features:
If you are deploying from binary, just move portal-forums.ear in to your deploy directory.
If you are deploying from source:
To install forums, you need to go to the directory forums and type sh build.sh deploy it will create a file portal-forums.ear and copy it to $JBOSS_HOME/server/default/deploy. If JBoss is already running you have nothing to do but to go to a page where the forums should be displayed (see your configuration).
To have the mail notification working, make sure that you correctly configure the mail service with an existing SMTP account in the file: $PORTAL_HOME/core/src/resources/portal-server-war/WEB-INF/jboss-service.xml
In $FORUMS_HOME/src/resources/portal-forums-war/WEB-INF/portlet.xml you can configure the following options:
You can restrict access to the forums for certain roles, to do so edit the file $FORUMS_HOME/src/resources/portal-forums-war/WEB-INF/jboss-portlet.xml. You should see the existing part:
<scheme> <domain></domain> <item> <path>/</path> <permission> <permission-name>Add</permission-name> <role-name>Users</role-name> </permission> <permission> <permission-name>Admin</permission-name> <role-name>Admins</role-name> </permission> <!-- For non logged users --> <permission> <permission-name>Read</permission-name> <role-name></role-name> </permission> </item> </scheme>
This means that a user with role Users has the permission to add posts in forums, a user with role Admins has the permissions to Admin anything, while an anonymous user (not logged on), can only read.
If you want users to only view a category named "myCategory" to a certain role "myRole", here is an item that you can add:
<item> <path>/myCategory</path> <permission> <permission-name>ReadCategory</permission-name> <role-name>myRole</role-name> </permission> </item>