Installing GlassFish on Ubuntu

Installing GlassFish on Ubuntu (last updated 2011-10-12)

This HOWTO explains one way of setting up GlassFish 3.0.1 under Ubuntu; it's how we do it where I work. When we upgrade to GlassFish 3.1.1 later this year, I'll update this file. Questions or suggestions for improvement can be addressed to shadowm at lyonlabs dot org.

Installing GlassFish
Fronting GlassFish with Apache
Setting up Database Connection Pools
Problems with Persistent Timers

Installing GlassFish

Download the installer from Oracle. I'd recommend using the full version (glassfish-3.0.1-unix.sh). Make sure you have a current JDK installed on your machine.
As root, run the installer. Install to directory /usr/share/glassfish-3.0.1. Make a note of the admin password you have selected. On the "Update Configuration" panel, select the checkboxes to install and enable the Install Update Tool.
Add the binaries directory of your new installation to the PATH. One way of doing this is to use a profile script in /etc/profile.d. Create a file there whose name ends in .sh, make it executable, and add this line:
```
export PATH=/usr/share/glassfish-3.0.1/glassfish/bin:$PATH
```
Log out and back in to make the change take effect.

Create a group and a user for GlassFish:

addgroup --system glassfish
adduser --system --shell /bin/bash --ingroup glassfish glassfish

Add the following lines to /etc/security/limits.conf to increase the maximum number of open files for the user that Glassfish will run as:
```
glassfish soft nofile 32768
glassfish hard nofile 65536
```
You will also need to add this line in /etc/pam.d/su:
```
session required pam_limits.so
```
As root, in /usr/share, change the permissions of the newly-created GlassFish directory:
```
chown -R glassfish.glassfish glassfish
```
If you want to use your own domain name instead of the default domain1, become the glassfish user (as root, su - glassfish), then delete the default domain (asadmin delete-domain domain1) and create a new one (asadmin create-domain <domain-name>). You will be prompted for new admin and master passwords. If you will be installing on several machines, I suggest that you give your domain the same name as the hostname of the machine you are installing on; that way, you can use the same startup scripts on all machines, using $HOSTNAME for the domain.
Start the domain:
```
asadmin start-domain <domain-name>
```
Verify that GlassFish is running by opening a browser on localhost:8080. You should also be able to log in to the admin console on localhost:4848
In order for GlassFish to be able to start from a script, you will also need to create a file containing the domain and master passwords. The startup script given below expects to find a file named passwd.gf in the glassfish user's home directory; make sure it has glassfish:glassfish ownership and 600 permissions (i.e. readable and writable only by the glassfish user). This is the format of that file:
```
AS_ADMIN_PASSWORD=mypassword
AS_ADMIN_MASTERPASSWORD=mypassword
```
This is an init script to make GlassFish start at boot time. To use it, copy it to /etc/init.d, then enable it (for example with update-rc.d or bum). This script expects the domain name to be same as the hostname (see above); if that is not the case, edit accordingly. It also expects to find Java in /usr/lib; if you have it installed somewhere else, just change the JPS variable. The script writes to a log file that prints any startup errors, so create that first (as root):
```
touch /var/log/glassfish-3.0.1
chown glassfish.glassfish /var/log/glassfish-3.0.1
```
Verify that the script works by running it as root:
```
/etc/init.d/glassfish-3.0.1 start
```
You'll want to do some tuning before using GlassFish in production (these suggestions come from Jean-François Arcand's excellent blog). In Configuration / JVM Settings / JVM Options, replace these two options:
```
-client
-Xmx512m
```
with these:
```
-server
-XX:+AggressiveHeap -Xmx1400m -Xms1400m -Xss128k -XX:+DisableExplicitGC
```

Fronting GlassFish with Apache

Many people use Apache to handle redirects, SSL, &c., while leaving the heavy lifting to GlassFish. Here is one way to do this (the official version from Oracle can be found here):

Make sure you have installed the libapache2-mod-jk package in Ubuntu to get the Apache Tomcat connector module. This works because GlassFish and Tomcat share some common code (Tomcat was originally written at Sun, as the servlet reference implementation). There are reference guides for the jk.conf and workers.properties files given below.

Create a jk.conf file and put it to /etc/apache2/conf.d. It should start like this (mind the domain name):

<IfModule mod_jk.c>
  JkWorkersFile /usr/share/glassfish-3.0.1/glassfish/domains/<domain-name>/config/workers.properties
  JkLogFile /var/log/apache2/mod_jk.log
  JkLogLevel error
  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
  JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
  JkRequestLogFormat "%w %V %T"
  JkMountCopy all
</IfModule>

You'll also need to tell Apache to forward any traffic for your GlassFish-hosted web app; it's also a good idea to disallow access to the WEB-INF directory. If your app's context is /myapp, add lines like this to the file:

JkMount /myapp/* ajp13
<Location "/myapp/WEB-INF/">
  deny from all
</Location>

Create a workers.properties file in your GlassFish domain's config directory (referenced in the above file) that looks like this:

worker.list=ajp13
worker.ajp13.type=ajp13
worker.ajp13.host=localhost
worker.ajp13.port=8009
# load balancing only: worker.ajp13.lbfactor=50
connection_pool_size=10
connection_pool_timeout=600
worker.ajp13.socket_keepalive=False
# make same as GlassFish:
worker.ajp13.socket_timeout=30

Copy the ajp13 files to GlassFish's lib directory (/usr/share/glassfish-3.0.1/glassfish/lib). Here are the three files, in a tarball.
Enable the AJP protocol by adding the following JVM option in GlassFish's admin app (Configuration / JVM Settings / JVM Options):
```
-Dcom.sun.enterprise.web.connector.enableJK=8009
```
Restart Apache and GlassFish; the GlassFish welcome page that was visible at localhost:8080 should now be visible at localhost. If you could access your app at e.g. localhost:8080/myapp/index.html before fronting with Apache, you should be able to access it without the :8080 now.

Setting up Database Connection Pools

Here are the steps to set up a connection pool for a PostgreSQL database:

Put the latest Postgres JDBC driver to the lib/ subdirectory of the GlassFish install (/usr/share/glassfish-3.0.1/glassfish/lib).
In the admin client, navigate to Resources / JDBC / Connection Pools, and create a new pool named after the database. Set the resource type to javax.sql.DataSource; leave the database vendor field blank.
On the next panel, the datasource classname must be org.postgresql.ds.PGSimpleDataSource (i.e. not org.postgresql.Driver, which is what you would use for straight JDBC).
At the bottom of the page is an area to enter additional properties; you must enter values for serverName, databaseName, user, and password.
After saving, select the entry for this pool and click the "Ping" button. You should see a message saying "Ping Succeeded."
Create a new entry pointing to the pool under Resources / JDBC / JDBC Resources. The name must start with jdbc/.

If you are using EJBs with JPA, your persistence.xml should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" 
  xmlns="http://java.sun.com/xml/ns/persistence" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
  http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
  <persistence-unit name="your-PU-here" transaction-type="JTA">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <jta-data-source>jdbc/your-resource-here</jta-data-source>
    <exclude-unlisted-classes>false</exclude-unlisted-classes>
    <properties>
    </properties>
  </persistence-unit>
</persistence>

For those using MySQL, the datasource class name is com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource. The necessary properties are user, password, and URL; the format for URL is:

jdbc:mysql://<hostname>:3306/<databasename>

Problems with Persistent Timers

We've had no end of problems with EJB timers in Glassfish 3.0.1 (we use the @Schedule annotation for this). Sometimes, whether redeploying or just restarting GlassFish for whatever reason, the timers would not start again. Eventually, we learned that timers are persistent by default. The next step was to investigate how GlassFish was restoring these timers, which led us to this URL (visit it on the machine running GlassFish):

http://localhost:8080/ejb-timer-service-app/timer

On a machine that should have eight timers (eight @Schedule annotations in the app's code), we saw one machine with 31 persistent timers, and one with 35! Clearly something was amiss. I'm not sure whether this is a bug in GlassFish (and of course, 3.1.1 has been released since then), although I did send a dump of the timer database to someone at Oracle. Which brings us to the next interesting information: how to directly examine and alter the JavaDB database containing persistent timer statistics. Note that to connect to this database, you must either stop GlassFish or copy the directory containing the database somewhere else (and adjust the connect statement below).

These are the steps we followed: (adjust for where you've installed GlassFish and which user owns it):

su - glassfish
export DERBY_HOME=/usr/share/glassfish-3.0.1/javadb
$DERBY_HOME/bin/ij
connect 'jdbc:derby:/usr/share/glassfish-3.0.1/glassfish/domains/<domain-name>/lib/databases/ejbtimer';
select * from EJB__TIMER__TBL;

Once you're connected, number of records in EJB__TIMER__TBL should equal the number of @Schedule annotations in your code. In our case, we saw many duplicated entries. We didn't feel we could afford the time to diagnose the issue, and there was no real reason for the timer jobs to be restored if they had passed their expiration time while GlassFish was not running, so we just prepared a build with persistent=false in all the @Schedule annotations, and deleted all the records from the timer table before deploying it. Now we consistently see eight non-persistent timers, and that number doesn't change even after redeploys, GlassFish restarts, or bringing GlassFish down hard and restarting it.