Table of Contents
Any user of JBoss Portal 2.0 Alpha should read this document, it explains features of the JBoss portlets and how to configure them.
We would like to thank all developers that participate in the JBoss Portal project effort, Remy for his help and the Nodesk team that gave us that nice theme.
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 versions.
If you successfully installed JBoss portal on versions not listed here please let us know so we can add it here.
This is really important that you only use the JBoss version supported, for now we only support JBoss 4.0.0
- JBoss 4.0.0
MySQL is the database used for our testings, 4.0.22 is one version that has been fully tested. There is no reason why any other MySQL database would not work so give it a try.
- MySQL 4.0 (4.0.22 is known to be supported along with the connector 3.0.16)
- MySQL 4.1 (4.1.7 is known to be supported along with the connector 3.0.16)
- PostgreSQL (not tested)
- Oracle (not tested)
- Any database supported by Hibernate 2 should work
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 get JBoss 4.0.0 http://sourceforge.net/project/showfiles.php?group_id=22866&package_id=16942 from Sourceforge.
You can download JBoss portal in different ways, packaged in binaries or sources or from the CVS.
- Packaged: From the JBoss portal project page
- CVS: cvs co -r JBoss_Portal_2_0_0_alpha jboss-portal-2.0
You will need a database to store the data of the system, you can use any database supported by Hibernate. In this document we will consider that you are using MySQL, you can download it at http://www.mysql.com
The MySQL JDBC connector is available at http://dev.mysql.com/downloads/connector/j/3.0.html
If you didn't do so already you will need to create a MySQL database. For testing you will want to create a database called "jbossportal", with a user called "portal" and a password "portalpassword". Here are the explanations to do so. If you are familiar with Mysql, feel free to create this database and user yourself and skip this part.
Get the binaries from http://dev.mysql.com/downloads/mysql/4.0.html, unpack them and install them according to the MySQL documentation
Note
You should change the root password by typing: C:\mysql\bin> mysqladmin -u root password 'myN3wPassw0rd'Now you can log on MySQL by typing: C:\mysql\bin> mysql -u root -p (if you didn't set a password just press enter when it asks for one or don't put the -p option)
Create the jbossportal database: (you can change the name if you want)
In the MySQL console type:
mysql> CREATE DATABASE jbossportal;The output should be:
Query OK, 1 row affected (0.01 sec)Add a user (pick any name if you don't like portal as username:
mysql> GRANT ALL PRIVILEGES ON jbossportal.* TO 'portal'@'localhost' IDENTIFIED BY 'portalpassword' WITH GRANT OPTION;The output should be:
Query OK, 0 rows affected (0.00 sec)If you need a custom setup of JBoss AS, you should read the documentation about JBoss application server. Here we will use the standard configuration shipped with JBoss AS 4.0.0. At this stage you should have the jboss-4.0.0.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.
The downloaded archive contains the following files:
- portal-core.sar
- portal-forums.ear
- portal-ds.xml
- cms-content.zip
- setup.ddl
The first step is to setup the default data for the portal, this is done in 2 steps. First you have to execute the content of the file setup.ddl in the database.
>mysql -u portal -p mysql> use jbossportal Database changed mysql> source setup.ddl Query OK, 0 rows affected, 1 warning (0.06 sec) ... Query OK, 1 row affected (0.00 sec) mysql> exit Bye
The second step is to unarchive the content of the file cms-content.zip into the directory $JBOSS_HOME/server/standard/data, this setup the default content of the CMS. If this is the first time you use that JBoss instance, the directory data should not exist, in that case you have to create it. Normally you should have the following structure for the CMS:
[$JBOSS_HOME/server/standard/data] +-portal +-webdav +-store +-work
Now it is time to deploy the rest in JBoss. Just copy the files portal-core.sar, portal-forums.ear and portal-ds.xml into the directory $JBOSS_HOME/server/standard/deploy
Like a real open source programmer you want to do it by yourself. Now it is time to build JBoss Portal, go to jboss-portal-2.0/build and type sh build.sh, you should read BUILD SUCCESSFUL at the end of the operation.
Warning
Make sure that JBOSS_HOME is still defined in the environment or it will not work.Now you will need to build the DDL file to be able to create the required tables in your database. To do so go to jboss-portal-2.0/core and type sh build.sh ddl. It will create the file jboss-portal-2.0\core\output\resources\setup\setup.ddl.
To feed your database just type the following line and enter portalpassword as password when asked (or whatever you used while setting up your database): C:\mysql\bin> mysqladmin -u portal -p jbossportal < jboss-portal-2.0\core\output\resources\setup\setup.ddl then you should populate the database to create two users, one with login user and password user who is a regular user and one administrator with admin as username and admin as password. To do so type the following command: root# mysql -u portal -p jbossportal < jboss-portal-2.0\core\output\resources\setup\setup.sql
Before you deploy the application by itself, you will need to have the database deployment descriptor (portal-ds.xml) in the $JBOSS_HOME\server\standard\deploy directory. To do so just create that file with the following content (you can also copy this file from jboss-portal-2.0\core\src\resources\setup\portal-ds.xml):
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>PortalDS</jndi-name>
<connection-url>jdbc:mysql://localhost:3306/jbossportal</connection-url>
<driver-class>org.gjt.mm.mysql.Driver</driver-class>
<user-name>portal</user-name>
<password>portalpassword</password>
</local-tx-datasource>
</datasources>You will also need to put the jar file of your database connector in $JBOSS_HOME\server\standard\lib.
Copy $JBOSS_HOME\server\all\lib\jgroups.jar and $JBOSS_HOME\server\all\lib\jboss-cache.jar into $JBOSS_HOME\server\standard\lib
Warning
Make sure that JBOSS_HOME is still defined in the environment or it will not deploy.Finally, you can deploy JBoss Portal by going into the core directory and by typing build deploy. It will deploy JBoss Portal in the standard configuration of JBoss.
Note
During the deploy, the cms data are copied to your JBoss data directory, copying the portal.sar file is not enough if it is your first deployment.
Now you can start JBoss AS by going into $JBOSS_HOME/bin and typing run -c standard.
Warning
If the forums portlet is not installed, the link to the forums page will not work, see the forums portlet chapter of this document for the installation instructions.Using your browser, navigate to http://localhost:8080/portal and you should see the portal.
If you didn't do so already you will need to create a MySQL database. For testing you will want to create a database called "jbossportal", with a user called "portal" and a password "portalpassword". Here are the explanations to do so. If you are familiar with Mysql, feel free to create this database and user yourself and skip this part.
Note
To install Mysql, if you are using Debian:root# apt-get install mysql-server
root# apt-get install mysql-client
By default on Debian, networking access is forbidden you have to edit the file /etc/mysql/my.cnf and comment out (add a # at the beginning of the line) skip-networking, then restart the MySQL server by typing root# /etc/init.d/mysql restart.
Get the binaries from http://dev.mysql.com/downloads/mysql/4.0.html, unpack them and install them according to the MySQL documentation
Note
You should change the root password by typing: user# mysqladmin -u root password 'myN3wPassw0rd'Now you can log on MySQL by typing: user# mysql -u root -p (if you didn't set a password just press enter when it asks for one or don't put the -p option)
Create the jbossportal database: (you can change the name if you want)
In the MySQL console type:
mysql> CREATE DATABASE jbossportal;The output should be:
Query OK, 1 row affected (0.01 sec)Add a user (pick any name if you don't like portal as username:
mysql> GRANT ALL PRIVILEGES ON jbossportal.* TO 'portal'@'localhost' IDENTIFIED BY 'portalpassword' WITH GRANT OPTION;The output should be:
Query OK, 0 rows affected (0.00 sec)If you need a custom setup of JBoss AS, you should read the documentation about JBoss application server. Here we will use the standard configuration shipped with JBoss AS 4.0.0. At this stage you should have the jboss-4.0.0.tar.gz 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 type in a console: export JBOSS_HOME=/home/user/jboss-4.0.0 (Don't forget to change this path to your real path).
The downloaded archive contains the following files:
- portal-core.sar
- portal-forums.ear
- portal-ds.xml
- cms-content.zip
- setup.ddl
The first step is to setup the default data for the portal, this is done in 2 steps. First you have to execute the content of the file setup.ddl in the database.
>mysql -u portal -p mysql> use jbossportal Database changed mysql> source setup.ddl Query OK, 0 rows affected, 1 warning (0.06 sec) ... Query OK, 1 row affected (0.00 sec) mysql> exit Bye
The second step is to unarchive the content of the file cms-content.zip into the directory $JBOSS_HOME/server/standard/data, this setup the default content of the CMS. If this is the first time you use that JBoss instance, the directory data should not exist, in that case you have to create it. Normally you should have the following structure for the CMS:
[$JBOSS_HOME/server/standard/data] +-portal +-webdav +-store +-work
Now it is time to deploy the rest in JBoss. Just copy the files portal-core.sar, portal-forums.ear and portal-ds.xml into the directory $JBOSS_HOME/server/standard/deploy
Like a real open source programmer you want to do it by yourself. Now it is time to build JBoss Portal, go to jboss-portal-2.0/build and type sh build.sh, you should read BUILD SUCCESSFUL at the end of the operation.
Warning
Make sure that JBOSS_HOME is still defined in the environment or it will not work.Now you will need to build the DDL file to be able to create the required tables in your database. To do so go to jboss-portal-2.0/core and type sh build.sh ddl. It will create the file jboss-portal-2.0/core/output/resources/setup/setup.ddl.
To feed your database just type the following line and enter portalpassword as password when asked (or whatever you used while setting up your database): root# mysql -u portal -p jbossportal < jboss-portal-2.0/core/output/resources/setup/setup.ddl then you should populate the database to create two users, one with login user and password user who is a regular user and one administrator with admin as username and admin as password. To do so type the following command: root# mysql -u portal -p jbossportal < jboss-portal-2.0/core/output/resources/setup/setup.sql
Before you deploy the application by itself, you will need to have the database deployment descriptor (portal-ds.xml) in the $JBOSS_HOME/server/standard/deploy directory. To do so just create that file with the following content (you can also copy this file from jboss-portal-2.0/core/src/resources/setup/portal-ds.xml):
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>PortalDS</jndi-name>
<connection-url>jdbc:mysql://localhost:3306/jbossportal</connection-url>
<driver-class>org.gjt.mm.mysql.Driver</driver-class>
<user-name>portal</user-name>
<password>portalpassword</password>
</local-tx-datasource>
</datasources>You will also need to put the jar file of your database connector in $JBOSS_HOME/server/standard/lib.
Copy $JBOSS_HOME/server/all/lib/jgroups.jar and $JBOSS_HOME/server/all/lib/jboss-cache.jar into $JBOSS_HOME/server/standard/lib
Warning
Make sure that JBOSS_HOME is still defined in the environment or it will not deploy.Finally, you can deploy JBoss Portal by going into the core directory and by typing ./build.sh deploy. It will deploy JBoss Portal in the standard configuration of JBoss.
Note
During the deploy, the cms data are copied to your JBoss data directory, copying the portal.sar file is not enough if it is your first deployment.
Now you can start JBoss AS by going into $JBOSS_HOME/bin and typing ./run.sh -c standard.
Warning
If the forums portlet is not installed, the link to the forums page will not work, see the forums portlet chapter of this document for the installation instructions.Using your browser, navigate to http://localhost:8080/portal and you should see the portal.
Managing users using the user module consists in:
- Allowing a user to register a new profile with a login and password
- Allowing a user to log in the sytem and be recognized as member of user groups
- Allowing a user to update a profile with more information like his real name, instant messenger informations...
- Allowing an administrator to see the list of users, from there he can assign roles to a user
- Allowing as administrator to assign roles to a user
- Allowing a user to logout
Here is a list of attributes that you can define in the portlet.xml file:
- subscriptionMode
- automatic
The user can register and is automatically enabled
- emailVerification(Not yet implemented)
The user is enabled till the user open in his browser a link sent by email to the address he specified.
- automatic
- emailFrom
Email address that will appear in the "From" header when the system will send an email to a user
- defaultRole
Default role assigned to new users by default
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
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.
Note
All of your content resides under JBOSS_HOME/server/standard/data/portal/. You should not modify any of the directories/files under there, as it may cause the CMS portlet to not function properly.The CMS Portlet handles requests in the following order:
- Request enters the CoreServlet.
- Servlet parses request, calls for content and determines if content is text or binary.
- If binary, serve binary content directly from the servlet level.
- If text/html, pass request along to CMS Portlet where the content is retrieved, links are parsed and content is displayed.
The methodology of serving content outlined above, allows the CMS Portlet some beneficial features, like:
- Search-engine friendly URLs: http://domain/files/company.html
- No need to modify existing web page links. links to resources (images, web pages, pdfs, zips) can all be maintained as relative.
- Serve binaries with simple urls independant of the portal: http://domain/files/products.pdf
List of attributes that can be defined in the portlet.xml file:
- rootdir - Directory where all publicly accessible files are available from.
Remember, the default data for your store is contained in a zip file you should have received with the portal codebase. This should all be present under: JBOSS_HOME\server\standard\data\portal\webdav\store
The AdminCMS Portlet allows control over the content management system.
Viewing the AdminCMS Portlet is accomplished by navigating to the admin page http://localhost:8080/nukes/index.html?page=admin and clicking on the option labeled AdminCMS within the portlet window. Maximizing the portlet window has the same effect.
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:
- Launches HTML WYSIWYG Editor window for HTML files. Launches upload dialog windoe for binary type files.
- Opens the copy file/folder dialog window.
- Opens the move file/folder dialog window.
- Launches HTML WYSIWYG Editor window.
- Opens the create folder dialog window.
- Opens the upload file dialog window.
- Opens the delete confirmation dialog window.
- In the case of files, opens the file properties view. In the case of folders, opens the folder listing.
- Moves up the folder tree when clicked on.
- Expands directory tree.
Additionally, there are icons that help describe the types of resources present on the page:
- Denotes this resource as a binary file type.
- Denotes this resource as text/html or text/plain file types.
- Denotes this resource as a folder or "collection".
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.
Note
A user is not able to delete the homepage when in the content store's root directory. Nor is the user allowed to move above this directory.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.
Warning
Currently, there is no way to retrieve deleted files/directories! Deleting a file or directory is permanent!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.
Note
It is important to note here that when creating links to images or other resources within the system, as user must use the relative file path to that resource. ie: images/hello.gif. Keep in mind at all times that the document base is http://localhost/portal/ by default!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.
Note
It is important to note here that when creating links to images or other resources within the system, as user must use the relative file path to that resource. ie: images/hello.gif. Keep in mind at all times that the document base is http://localhost/portal/ by default!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 tropics 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:
- See the list of forums
- Post a new topic
- Read a topic
- Reply to an existing post
- Fast-reply to an existing post in the same page as the thread
- Create a new category of forum
- Edit the name of a category
- Delete a category and move the content to another category
- Create a new forum
- Edit the name and description of a forum
- Delete a forum and move the content to another forum
- Classify categories
- Classify forums
First you need to create the database structure, go to the forums directory and type sh build.sh ddl it will create a file forums/output/resources/setup/setup.ddl.
Feed your database with this file, you may also want to have some entries for testing if you do feed your database with this other file as well: forums/output/resources/setup/setup.sql. root# mysql -u portal -p jbossportal < forums/output/resources/setup/setup.ddl and root# mysql -u portal -p jbossportal < forums/output/resources/setup/setup.sql are the two commands you need to type if you are using MySQL
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/standard. 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).
You can restrict access to the forums for certain roles, when you define a rule, the first element of the pattern must be the category name while the second is the forum name. For example the following rule <<rule role="myrole" patterns="Category name:Forum name" level="add"/> will give add privilege to the role myrole on the forum called "Forum name" of the category called "Category name". You can also use regular expression like: <<rule role="myrole" patterns="Admin name:.*" level="add"/> to give add access to the entire category.