Alfresco on Glassfish

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

This walkthrough was created for OpenSolaris, but where I can I've called out the differences for Windows and Linux. For OpenSolaris the b98 development build was used but it should work fine on the release version of 2008.05. Any testing on Windows was made with 32-bit XP with SP3

I've posted a shorter version on my blog for those who have previously tried to get it working but were just missing the vital ingredient.

Table of Contents

• 1 Initial Setup


• 2 Alfresco War file and configuration


• 3 The Glassfish specific deployment descriptor


• 4 Troubleshooting


• 5 Newer guide tested for Alfresco 3.4+ with GlassFish v3.1.1 on Windows x86

Initial Setup

I'm going to assume you are doing this as a non-root user. If you do this as root, just drop the pfexec statement from any commands you issue. If you are running on Linux then replace pfexec with sudo.

First install Glassfish and MySQL (OpenSolaris only):

$ pfexec pkg refresh
$ pfexec pkg install glassfishv2 
$ pfexec pkg install SUNWmysql5

Unlike with the best tutorials, I won't first remind you to turn your system on or not to install the packages if they are already installed.

For Windows: Download and Install the Java 6 SDK (jdk1.6), Glassfish v2 and MySQL 5.1.x

For Linux: Install the distro packages for the JDK and for MySQL. Download and install Glassfish v2

OpenSolaris has a Service Management feature called SMF. Currently when you install packages you have to register their services manually, so do the following to register the MySQL Service:

$ pfexec svccfg import /var/svc/manifest/application/database/mysql.xml

and then start the MySQL service:

$ pfexec svcadm enable mysql

This will do all of the work required to get MySQL up and running for the first time.

For Windows: MySQL for Windows can be installed as a Windows Service.

Now create a DB and a user to access it with. In OpenSolaris and Linux you can just run the command line client as follows (adjust paths accordingly for Linux):

$ /usr/mysql/50/bin/mysql -u root

For Windows: You can access the MySQL command line client from the MySQL start menu.

Use the MySQL command line client to run the following MySQL commands

mysql> create database alfresco;
Query OK, 1 rows modified (0.02sec) 

mysql> grant all privileges on alfresco.* to 'alfresco'@'%' identified by 'alfresco';
Query OK, 0 rows modified (0.00sec) 

mysql> grant all privileges on alfresco.* to 'alfresco'@'localhost' identified by 'alfresco';
Query OK, 0 rows modified (0.00sec) 

Now use the Glassfish asadmin command to setup a Glassfish domain. On OpenSolaris you can do this:

$ pfexec /usr/sbin/asadmin create-domain --adminport 4848 domain1

On Windows and Linux, the path to asadmin will vary but the rest of the command will be the same

You need a JDBC MySQL driver:

$ wget http://mysql.osuosl.org/Downloads/Connector-J/mysql-connector-java-5.1.6.tar.gz

The URL used for the MySQL JDBC driver is just one of many mirrors. You might be better off going to http://dev.mysql.com/downloads/connector/j/5.1.html and choosing where to get it from. For Windows you'll need to go to the URL in a browser.

Unpack this somewhere and copy mysql-connector-java-5.1.6-bin.jar to the Glassfish domain's lib directory. On OpenSolaris and Linux you can do the following, on Windows use Explorer:

$ pfexec cp mysql-connector-java-5.1.6-bin.jar /var/appserver/domains/domain1/lib

While you are doing this you may as well create an alfresco directory in the same place, you'll need it later.

$ pfexec mkdir /var/appserver/domains/domain1/lib/classes/alfresco

On Windows: For the previous step, find the domains\domain1\lib\classes directory of your Glassfish install and create a directory called alfresco

Alfresco War file and configuration

This testing was done with Alfresco labs 3b, it should work with other versions, but if it doesn't post a comment on my blog entry and I'll look into it.

Next we'll need the Alfresco War file, which you can probably get from here:

OpenSolaris and Linux

Windows

Once you have it, extract the bundle somewhere, you won't need it after the setup is finished.
You now need to setup the Alfresco bits that aren't contained in the WAR file. From the directory in which you unpacked the Alfresco bundle, copy the entire contents of the extensions directory to the directory you created earlier:

$ pfexec cp -r extensions/* /var/appserver/domains/domain1/lib/classes/alfresco

You don't want to copy over the extensions directory itself, just it's contents (extension and messages directories).

On Windows, you can use the Explorer to copy over the contents of the Extensions folder to the alfresco directory you created earlier

Alfresco needs somewhere to keep all of it's documents and indexes. This is usually named alf_data, if you don't specify a path to alf_data or the path doesn't exist it will create one for you... somewhere. Let's not leave things to chance and create one and then configure Alfresco to find it:

$ pfexec mkdir /var/alfresco/alf_data

On Windows I created and used C:\alf_data just adjust this to suit your setup

Now change directory to (or use Windows Explorer) the alfresco/extension directory you created with the copy that you did a couple of steps ago and modify the config files so that Alfresco can find alf_data and can find the database. The files that need changing are:

custom-repository.properties

custom-hibernate-dialog.properties

In custom-repository.properties do the following:

Uncomment the dir.root line and change it's path to /var/alfresco/alf_data

#dir.root=/srv/alfresco/alf_data

becomes:

dir.root=/var/alfresco/alf_data

or on Windows (note the use of a forward slash):

dir.root=C:/alf_data

Uncomment the db.username and db.password lines

#db.username=alfresco
#db.password=alfresco

becomes:

db.username=alfresco
db.password=alfresco

The last part of the file has sections for specific databases, by default it's setup to use Derby. Comment out the lines for derby and uncomment the lines for MySQL

db.driver=org.apache.derby.jdbc.EmbeddedDriver
db.url=jdbc:derby:data/derby_data/alfrescocreate=true
...
...
#db.driver=org.gjt.mm.mysql.Driver
#db.url=jdbc:mysql://localhost/alfresco

becomes

#db.driver=org.apache.derby.jdbc.EmbeddedDriver
#db.url=jdbc:derby:data/derby_data/alfrescocreate=true
...
...
db.driver=org.gjt.mm.mysql.Driver
db.url=jdbc:mysql://localhost/alfresco

In custom-hibernate-dialog.properties, comment out the line for Derby and uncomment the line for MySQL

The Glassfish specific deployment descriptor

Now for the fun bit. Go to the directory in which you unpacked the Alfresco bundle, create a directory called WEB-INF and in that create a file called sun-web.xml with the following contents:

<sun-web-app>
 <class-loader delegate='false'/>
 <property name='useMyFaces' value='true'/>
</sun-web-app> 

and then add that file to the alfresco.war file:

$ jar uvf alfresco.war WEB-INF/sun-web.xml
adding: WEB-INF/sun-web.xml(in = 316) (out= 236)(deflated 25%)

For Windows: You need to make sure that you have the Java JDK bin directory on the PATH.

You're now ready to start Glassfish and deploy alfresco.war to the Glassfish domain:

$ pfexec /usr/bin/asadmin start-domain domain1
$ /usr/sbin/asadmin deploy alfresco.war
Please enter the admin user name>admin
Please enter the admin password> 
Command deploy executed successfully

For Windows and Linux: again the path to the asadmin command will be different depending on your setup, but the rest of the command will be the same

Now you should be able to fire up a browser and connect to Alfresco at http://localhost:8080/afresco

Troubleshooting

Check that it's using the MySQL database that you created by connecting to MySQL through the mysql command and looking to see if the Alfresco database has a bunch of tables. Also check that the alf_data directory contains directories if it doesn't then it probably hasn't picked up the configuration from the domains/domain1/lib/classes/alfresco/extensions directory in your Glassfish installtion. Check that you've used the correct path and that the changes that you made to custom-repository.properties and custom-hibernate-dialog.properties are correct.

The sun-web.xml file has along line in it, if you cut and paste make sure that it doesn't get split across multiple lines.

The alfresco log file, alfresco.log will appear in the domains/domain1/config directory of your Glassfish installation. With the default Heap size of 512MB Alfresco logs an error in the log saying that the amount of heap (494MB is less than the 512MB recommended. You can change the JVM Heap size for the Glassfish instance via the Admin console.

Newer guide tested for Alfresco 3.4+ with GlassFish v3.1.1 on Windows x86

Proposed by Sebgymn

Below is my guide step by step created from scratch because I ran into problems with newer versions of Alfresco and Glassfish. This guide is tested for Alfresco 3.4 on Glassfish v3.1.1 on Windows. Despite I haven't tested personally, it will most probably also work on UNIX based systems.

1. Download and Install Glassfish Open Source Server from http://glassfish.java.net/downloads/3.1.1-final.html I have installed 'glassfish-3.1.1-windows.exe'.

I will reference glassfish installation directory as GLS (default: c:\glassfish3) and your domain name as DMN (default: domain1). GLSDMN reference means: GLS\glassfish\domains\DMN

2. Download Alfresco Community 3.4.a custom zip file from http://process.alfresco.com/ccdl/?file=release/community/build-3169/alfresco-community-3.4.a.zip

3. Extract the zip file under any folder. I will reference this folder as ALF.

4. Copy contents of ALF\web-server\shared\classes to GLSDMN\lib\classes

5. Rename alfresco-global.properties.sample to alfresco-global.properties

6. Open this file and configure it properly. My property file looks like this, but you will need to adjust it according to your setup. Note that dir.root value is explicitly given. Also note that alfresco.log will reside in GLSDMN\config folder.

dir.root=C:/glassfish3/alf_data

#make this false if your database tables has been created successfully. 
db.schema.update=true 

db.username=alfresco
db.password=alfresco
db.name=alfresco
db.driver=org.gjt.mm.mysql.Driver
db.url=jdbc:mysql://localhost/alfresco?useUnicode=yes&characterEncoding=UTF-8

index.recovery.mode=AUTO

alfresco.context=alfresco
alfresco.host=${localname}
alfresco.port=8080
alfresco.protocol=http

avm.rmi.service.port=50500
avmsync.rmi.service.port=50500
attribute.rmi.service.port=50500
authentication.rmi.service.port=50500
repo.rmi.service.port=50500
action.rmi.service.port=50500
wcm-deployment-receiver.rmi.service.port=50500
monitor.rmi.service.port=50500

7. Copy contents of ALF\web-server\lib to GLSDMN\lib folder. (Not ext, database or other directory). If there are more libraries that you need to use like other database connectors, put it under GLSDMN\lib folder also. For example, in previous versions of Alfresco, there is ALF\web-server\endorsed folder, you also need to copy the contents of it.

8. Create ALF\web-server\webapps\WEB-INF\sun-web.xml file.

9. Write the following lines to this file:

<sun-web-app>
 <class-loader delegate='false'/>
 <property name='useMyFaces' value='true'/>
</sun-web-app>

10. Make sure your Java JDK bin directory is on your PATH.

11. Open cmd, move to ALF\web-server\webapps\ dir

12. Enter command (If you want to apply some AMP packages to your WAR, do it before this step)

jar uvf alfresco.war WEB-INF/sun-web.xml

Output will be like:

adding: WEB-INF/sun-web.xml(in = 316) (out= 236)(deflated 25%)

13. Your Glassfish server should already be started after installation (Step 1). If not, navigate to GLS\bin folder with cmd, then issue command

asadmin start-domain

14. Goto http://localhost:4848 and select deploy application, then select alfresco.war under ALF\web-server\webapps, then select OK without modifying anything.

15. If deployment has errors, navigate to server(Admin Server) from left menu, then view log files.

16. If deployed successfully, navigate to http://localhost:8080/alfresco and try to login. You will get some error like this:

javax.faces.FacesException: Error calling action method of component with id loginForm:submit 
caused by: 
javax.faces.el.EvaluationException: Exception while invoking expression #{LoginBean.login} 
caused by: 
java.lang.RuntimeException: class configured for MessageDigest(provider: BC)cannot be found. 
caused by: 
java.security.NoSuchAlgorithmException: class configured for MessageDigest(provider: BC)cannot be found. 
caused by: 
java.lang.ClassNotFoundException: org.bouncycastle.jce.provider.JDKMessageDigest$MD4...

17. Stop glassfish by

asadmin stop-domain

18. Then, move (not copy) GLSDMN\applications\alfresco\WEB-INF\lib\bcprov-jdk15-1.45.jar file to GLSDMN\lib folder.

19. Start glassfish and you are done.

Note: You might also change -XX:MaxPermSize=192m to -XX:MaxPermSize=256m under Glassfish administration – Configuration – server-config – JVM Settings – JVM Options. Restart server for changes to be effective.

Note: alfresco.log file will contain some errors as

18:28:00,941 ERROR [org.apache.myfaces.shared_impl.config.MyfacesConfig] Both MyFaces and the RI are on your classpath. Please make sure to use only one of the two JSF-implementations. 

This is OK as far as I know.

InstallationGlassfish