BellaDati Technical Documentation : Installing BellaDati on GlassFish

Icon

This guide describes how to install BellaDati WAR on GlassFish. You can download it from the GlassFish download page. Please refer to the GlassFish quick start guide or the GlassFish documentation for more information about how to install GlassFish.

BellaDati supports GlassFish 3.1.2 and above. The instructions in this document refer to GlassFish 4 but apply similarly to older versions.

Icon

When you are using GlassFish 4.1, download the Java EE Web Profile.

Icon
The BellaDati WAR file is the BellaDati application packaged in a WAR archive. It must be deployed into an existing application server and needs to be connected to a data warehouse running on an existing database server.

Before You Begin

Please read the following important notes before you begin installing BellaDati on GlassFish:

  • Make sure you have the right version of Java. See Installing Java for more details.
  • Install GlassFish application server
  • Deploying multiple BellaDati WAR application in a single GlassFish application server is not supported. We do not test this configuration and updating any of the applications (even for point releases) is likely to break it.
  • We recommend not deploying any other applications in the same GlassFish container that runs BellaDati, especially if these other applications have large memory requirements or require additional libraries in GlassFish's lib sub-directory. Multiple applications in a container can impact stability as a crash in one application could make the entire container inaccessible. Additionally, in order to update or reconfigure any of the applications, you'll need to restart the whole container.

 

Watch the video tutorial and or follow guidelines below

1. Setup data warehouse

Please follow the instructions on the Setting up the PostgreSQL Database page.

2. Download and extract BellaDati WAR Archive

Download the BellaDati WAR distribution as a ZIP archive from the BellaDati download page and extract its content using a tool such as 7-Zip for Windows or Linux's GNU tar tools. Only one of the files in the ZIP archive is used for this setup - belladati.war.

(warning)  Avoid using Windows' built-in file extraction tool! This tool silently fails to extract files with long names. Other users have also reported problems with WinRAR.

(warning)  Avoid using Solaris' default tar utility! Please use GNU tar on this operating system to extract BellaDati, as GNU tar handles long file names better.

3. Configure BellaDati WAR

Since version 2.7.14 there is no special configuration change needed, however, there are several advanced settings (e.g. enforcing the SSL), which are configurable in application.properties only.

Icon

Configuration settings are explained in detail in the BellaDati WAR Configuration Overview.

4. Update Your GlassFish Installation's Libraries for BellaDati

Your GlassFish installation requires a JDBC driver allowing BellaDati to communicate with the database. To add this JDBC driver to GlassFish:

  1. Download the PostgreSQL JDBC driver (obtain version 9.0 or later of the JDBC 4 driver).
  2. Copy the PostgreSQL JDBC driver jar to the lib/ directory of your GlassFish server.

5. Configure GlassFish

5.1 Configure Memory Settings in GlassFish

BellaDati requires more memory than what GlassFish provides by default. This may lead to OutOfMemory errors when running BellaDati if these memory settings are not increased.

To increase the available memory, log in into the GlassFish Administration console (by default available at port 4848). Open the Application server's JVM Settings menu and click on JVM Options. Change the setting for -XX:MaxPermSize to 512m and -Xmx to 2048m and change -client to -server as shown in the screenshot below. If any of these options doesn't exist yet, create it. Please make sure you don't have set a -server and -client option at the same time.

If you are using the command line, execute the following commands instead:

$GLASSFISH_HOME/bin/asadmin create-jvm-options \"-Xmx2048m\"
$GLASSFISH_HOME/bin/asadmin create-jvm-options \"-XX:MaxPermSize=512m\"

For other environments and more information on memory settings, see the System Requirements and Recommended JVM Options.

5.2 Configure the GlassFish's JDBC resource

BellaDati uses JDBC resources which connect to the database subsystem. Although BellaDati can connect to the database directly using its own JDBC setup, we recommend using GlassFish's JDBC resources for better performance and more control over the database transaction management. You can set up the JDBC connection pool and JDBC resource following these steps:

5.2.1 Using GlassFish's Administration console

You can use the GlassFish's Administration console as described in the previous step:

1. Login to Administration console.
2. Open Resources->JDBC->Connection Pools and click the New button.
3. Fill the Name, Type and Database Vendor fields and click Next.

4. Specify the database pool settings. The defaults may be fine, but we recommend to set values as shown on the right (see table Recommended connection parameters).

5. In the property list, enter the values matching your system configuration for DatabaseName, User, Password and ServerName. Remove all other properties.

6. After the connection pool was created, select it on the left side and click on tab Advanced. Set Connection Settings and turn on Connection Validation using the settings shown on the right (see table Recommended connection parameters).

7. Open Resources->JDBC->Resources and click the New button.
8. For JNDI Name, enter the value from jdbc.resource in BellaDati's application.properties. As Pool Name, select the connection pool created during the previous steps.

9. Please test connection by Ping button on the top of page.

Recommended connection parameters

Resource Type

javax.sql. ConnectionPoolDataSource

Database Vendor

PostgreSQL

Pool Settings

Initial and Minimum Pool Size

8

Maximum Pool Size

200

Pool Resize Quantity

2

Idle Timeout

300s

Max Wait Time

60000ms

Connection Validation

Connection validation

required

Validate at most once in
240

Validation Method

table

Table Name

pg_tables

On Any Failure

not checked

Allow Non Component callers

not checked

5.2.2 Using the asadmin command

1. Start GlassFish
2. Create a JDBC connection pool:

$GLASSFISH_HOME/bin/asadmin create-jdbc-connection-pool \
--datasourceclassname org.postgresql.ds.PGConnectionPoolDataSource \
--restype javax.sql.ConnectionPoolDataSource --maxpoolsize 200 \
--isconnectvalidatereq=true --validationmethod table --validationtable pg_tables \
--property DatabaseName=belladati:User=belladati_dbuser:Password=password:ServerName=db_host belladati_jdbcpool

For DatabaseName, User, Password and ServerName, enter the values matching your system configuration.

3. Create a JDBC resource:

$GLASSFISH_HOME/bin/asadmin create-jdbc-resource --connectionpoolid belladati_jdbcpool jdbc/belladati_db

The jdbc/belladati_db corresponds to the parameter jdbc.resource from BellaDati's application.properties.

6. Deploying BellaDati into GlassFish

6.1 Using GlassFish's Administration console

You can use the Admin Console to deploy BellaDati into GlassFish.

  1. Log in to Administration console.
  2. Open Applications.
  3. Click on the Deploy button.
  4. Click Browse and select the belladati.war file.

6.2 Using the asadmin command

In order to deploy BellaDati, execute this command:

$GLASSFISH_HOME/bin/asadmin deploy --user admin /belladati.war

This command deploys the BellaDati WAR file under the /belladati context.

7. Run the Setup Wizard

Point your browser to http://localhost:8080/belladati. This starts the Setup Wizard, which will take you through BellaDati's setup procedure.