# JBoss Portal 2.0 Alpha

## User Guide

### Thomas Heute

`<theute@jboss.org>`

0.1

## Target Audience

Any user of JBoss Portal 2.0 Alpha should read this document, it explains features of the JBoss portlets and how to configure them.

## Acknowledgements

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.

## Chapter 1. Supported versions

### Thomas Heute

`<theute@jboss.org>`

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.

## 1.1. JBoss application server

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

## 1.2. Database

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

## Chapter 2. Installation

### Thomas Heute

`<theute@jboss.org>`

## 2.1. Getting the files

There are a couple of archives that you will need to download in order to install JBoss Portal.

### 2.1.1. JBoss Application Server

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.

### 2.1.2. JBoss portal

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`

### 2.1.3. Database

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

### 2.1.4. JDBC connector

The MySQL JDBC connector is available at http://dev.mysql.com/downloads/connector/j/3.0.html

## 2.2. Windows

### 2.2.1. Setting up your environment

#### 2.2.1.1. Database

##### 2.2.1.1.1. MySQL

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)`

#### 2.2.1.2. JBoss AS

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.

### 2.2.2. Deploying JBoss Portal

#### 2.2.2.1. From the binaries

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`

#### 2.2.2.2. From the sources

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.

### 2.2.3. Running Jboss Portal

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.

## 2.3. Linux

### 2.3.1. Setting up your environment

#### 2.3.1.1. Database

##### 2.3.1.1.1. MySQL

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)`

#### 2.3.1.2. JBoss AS

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).

### 2.3.2. Deploying JBoss Portal

#### 2.3.2.1. From the binaries

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`

#### 2.3.2.2. From the sources

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.

### 2.3.3. Running Jboss Portal

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.

## Chapter 3. User Portlet

### Thomas Heute

`<theute@jboss.org>`

## 3.1. Introduction

The user portlet is dedicated to create and manage users and their profiles.

## 3.2. Functionalities

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

## 3.3. Portlet configuration

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.

- `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

## Chapter 4. Role Portlet

### Thomas Heute

`<theute@jboss.org>`

## 4.1. Introduction

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)

## 4.2. Functionalities

### 4.2.1. Create a role

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

### 4.2.2. Edit a role

While editing a role, you just need to pick an exising role then change the display name, that's the only thing you can change.

## Chapter 5. CMS Portlet

### Roy Russo

`<roy @ jboss dot org>`

## 5.1. Introduction

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.

## 5.2. Functionalities

The CMS Portlet handles requests in the following order:

1. Request enters the CoreServlet.
2. Servlet parses request, calls for content and determines if content is text or binary.
3. If binary, serve binary content directly from the servlet level.
4. 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:

1. Search-engine friendly URLs: http://domain/files/company.html
2. No need to modify existing web page links. links to resources (images, web pages, pdfs, zips) can all be maintained as relative.
3. Serve binaries with simple urls independant of the portal: http://domain/files/products.pdf

## 5.3. Portlet Configuration

List of attributes that can be defined in the portlet.xml file:

1. `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

## Chapter 6. AdminCMS Portlet

### Roy Russo

`<roy @ jboss dot org>`

## 6.1. Introduction

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".

## 6.2. Functionalities

This section describes common actions a user can perform from within the AdminCMS Portlet.

### 6.2.1. Viewing Directories

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.

### 6.2.2. Viewing File Properties

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.

### 6.2.3. Copying Files/Directories

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.

### 6.2.4. Moving Files/Directories

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.

### 6.2.5. Deleting Files/Directories

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!

### 6.2.6. Creating Directories

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.

### 6.2.7. Creating Text/HTML Files

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!

### 6.2.8. Uploading Binary Files

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.

### 6.2.9. Editing Text/HTML Files

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!

## Chapter 7. Forums Portlet

### Thomas Heute

`<theute@jboss.org>`

## 7.1. Introduction

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.

## 7.2. Functionalities

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

## 7.3. Installation

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).

## 7.4. Security

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.