Keeping it Small and Simple


Alfresco on Debian: using MySQL

Filed under: Alfresco — Tags: , , , , — Lorenzo E. Danielsson @ 16:44

Yesterday I blogged about how to perform the most basic possible installation of Alfresco on a Debian system. That setup included using Hypersonic SQL as the database backend. Eventually you will want to migrate to using MySQL instead. Let us look at how to set it up.

I am assuming that you have grabbed the Alfresco Tomcat bundle (the community version). I am also assuming that you are running Debian Etch or beyond (if you are running experimental and things don’t work, that’s your mess to sort out). You should also have MySQL installed and up and running. I have MySQL 5.0.45 here and that works fine.

Setting it up

Before you start, make sure the Alfresco server is not running. Shut it down if it is. Then you need to run an SQL script that will create the MySQL database for Alfresco to use. Do this (as root):

# cp /opt/alfresco/extras/databases/mysql
# mysql --user root -p < db_setup.sql

You should be prompted for the password of the MySQL root user. If you don’t have a password for the root user, you should leave out the -p option. Of course, you are already aware of the security implications of not having a password set, so I won’t go over that here. Your server, your choice.

Next, you need to edit two files located in /opt/alfresco/tomcat/shared/classes/alfresco/extension. The first one is where you need to comment out the lines relating to HSQL and uncomment the MySQL ones.
Here is the part of the file that needs to be modified with the changes made.

# HSQL connection

# MySQL connection (This is default and requires mysql-connector-java-5.0.3-bin.
jar, which ships with the Alfresco server)

The other file that needs to be edited is Again, un-comment the line that relates to MySQL and comment out the one relating to HSQL. Look at the very top of the file and you will find the lines to modify.

# HSQL dialect

# MySQL dialect (default)

If this was a completely new Alfresco installation and you have never run it before you should be good to go. Start the Alfresco server and wait. It does take a little longer to start Alfresco when you are using MySQL. You could follow along by doing:

# tail -f /opt/alfresco/alfresco.log

That will give you Alfresco’s log output in the terminal.

If it doesn’t work

If the Alfresco server has been started at least once before migrating to MySQL, Alfresco will probably not start. You will be able to start Tomcat, but the Alfresco application will not be available. If this is the case, look inside the log file and you should find a few lines like this:

Caused by: More than one root node i
n index: 2

This fix for that, which is available here is:

  1. # cd /opt/alfresco
  2. # ./alfresco stop
  3. # rm -rf alf_data/lucene_indexes
  4. # cd tomcat/webapps/alfresco/WEB-INF/classes/alfresco
  5. # vim

Make the following changes to the file:

# The index recovery mode (NONE, VALIDATE, AUTO, FULL)

# Change the failure behaviour of the configuration checker

Now you can start Alfresco again. Hopefully it will work. If it doesn’t, stop Alfresco again, drop the database and re-create it, remove the /opt/alfresco/alf_data/lucene-indexes directory again and start. Then it *should* work.

Once you have been able to start Alfresco successfully and gone to http://localhost:8080/alfresco to confirm that it is indeed working, you can revert the changes that you made in /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/classes/alfresco/ If you don’t, Alfresco will attempt a full index recovery every time you start Alfresco.

The best option is probably that you configure Alfresco to use MySQL instead of HSQL before you start it the first time. That way you should not have any issues (at least I never have).

Other thing that could go wrong

Occasionally you see error messages like this one in your log file: Cannot bind to URL [rmi://localhost:50500/alfresco/jmxrmi]:
 javax.naming.NameAlreadyBoundException: alfresco/jmxrmi [Root exception is java
.rmi.AlreadyBoundException: alfresco/jmxrmi]

They will show up if you try to start Alfresco when its already running. But there are a few other circumstances as well. One is if you shut it down and restart it without giving it enough time to fully shut down. You can do:

# ps ax | grep java

to see if there are any java processes related to Tomcat and/or Alfresco still alive. If you find any, give them a minute or two to terminate.

While you are trying to migrate to MySQL, it sometimes happens that some processes refuse to close (I have waited for over twenty minutes without them croaking). In that case, just use ps to find the PID of the process and manually kill it.

For example, suppose I find this:

# ps ax | grep java
11180 pts/0    Sl     0:40 /usr/lib/jvm/java-6-sun/bin/java -Xms128m -Xmx512m -server -XX:CompileCommand=exclude,org/apache/lucene/index/IndexReader$1,doBody -XX:CompileCommand=exclude,org/alfresco/repo/search/impl/lucene/index/IndexInfo$Merger,mergeIndexes -XX:CompileCommand=exclude,org/alfresco/repo/search/impl/lucene/index/IndexInfo$Merger,mergeDeletions -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file=/opt/alfresco/tomcat/conf/ -Djava.endorsed.dirs=/opt/alfresco/tomcat/common/endorsed -classpath :/opt/alfresco/tomcat/bin/bootstrap.jar:/opt/alfresco/tomcat/bin/commons-logging-api.jar -Dcatalina.base=/opt/alfresco/tomcat -Dcatalina.home=/opt/alfresco/tomcat org.apache.catalina.startup.Bootstrap start
11362 pts/0    R+     0:00 grep java

The process with PID 11180 is an Alfresco process. If I have waited long enough for this to terminate, but it isn’t, step in and be the executioner:

# kill 11180


Migrating Alfresco to MySQL involves a little more work than just using HSQL, but not much more. It really isn’t that complex, just that it can be a bit frustrating when you keep trying to get it up and running and it keeps refusing. But just monitor you log file and you should be okay.

Next time I’ll look at how to set Alfresco using only the WAR file, into your own Tomcat installation. This is a good idea if you already have Tomcat installed. There are a few additional things you will have to do if you use your own Tomcat installation instead of the bundled one. But, on the other hand, using our own gives us the opportunity to experiment with Alfresco on Tomcat 6.


Setting up Alfresco on Debian (Tomcat bundle)

Filed under: Alfresco — Tags: , , , — Lorenzo E. Danielsson @ 23:09

I have been playing around a lot with Alfresco of late. I’ll write some posts about what I have learned up to now, just in case it helps somebody out there.

Before we begin, here is what I’m using:

  • Debian Etch. For most part, these instructions should work on any Linux system.
  • Sun Java 6 (packages from Sid repository)


In this post I am going to use the Alfresco Tomcat bundle, which is available here. I will start by using all the defaults, which will use Hyperonic SQL as a backend database. This may not be a good idea in the “real world”, but is acceptable for testing. Most importantly, we should make sure that works before moving on.

Once you have downloaded Alfresco, you need to extract it. Perform the following (as root):

# mkdir /opt/alfresco
# cd /opt/alfresco
# tar zxf /home/lorenzod/dl/alfresco-community-tomcat-2.1.0.tar.gz

Of course, you will need to change the path in the last line to wherever you downloaded Alfresco to. If everything went well, ls should give you the following files (and directories):


Starting the server

Before you can start the Alfresco server, you need to set JAVA_HOME if you have not already done so. On my system, I did the following:

# export JAVA_HOME=/usr/lib/jvm/java-6-sun

(Check to make sure where your JDK is installed.) To save yourself from having to type this over and over again, add that line to file such as /etc/profile. That way JAVA_HOME will automatically be set for you.

Now you should be able to start Alfresco. Type (still as root):

# ./ start

Hopefully you will see this message:

Using CATALINA_BASE:   /opt/alfresco/tomcat
Using CATALINA_HOME:   /opt/alfresco/tomcat
Using CATALINA_TMPDIR: /opt/alfresco/tomcat/temp
Using JRE_HOME:       /usr/lib/jvm/java-6-sun

If, on the other hand, you get this message:

Neither the JAVA_HOME nor the JRE_HOME environment variable is defined
At least one of these environment variable is needed to run this program

Then JAVA_HOME hasn’t been set properly. Go back and follow the instructions, properly this time. Once Alfresco is up and running, open a browser and go to http://localhost:8080/alfresco if you are browsing from the same machine that you installed Alfresco to, or http://your-server:8080/alfresco if you are browsing from a different machine.

If that doesn’t work, try http://localhost:8080 to make sure Tomcat itself is up. Depending on your hardware, it make take a while for Alfresco to fully pull itself up, so give it a little time and try again. Otherwise look at the log file (/opt/alfresco/alfresco.log), something you should do even if Alfresco does run properly.

Once you see the Alfresco dashboard in your browser, you can click around a little to familiarize yourself with the interface. At the top you will see a login link. Click there and you can log in. The only user that exists by default is admin with password admin.

Peeking at the log file

When you look at the log file there are some errors and warnings that you might see. I will try to explain them as we go along.

With the current set-up the only error you are likely to see is:

21:31:17,079 ERROR [org.alfresco.smb.protocol.netbios] NetBIOSNameServer setup e
rror: Address already in use

This indicates that you already have Samba running. This will prevent Alfresco’s own CIFS server from starting. To prevent this, stop the Samba server before running Alfresco. Note that this error will not prevent Alfresco itself from running, but you will not be able use its CIFS server.

Shutting down the server

To shut down Alfresco, go to /opt/alfresco and type ./alfresco stop. If anything goes wrong during shutdown, there may be some running Java processes on the system. Use ps to locate them, and kill them manually. Normally you shouldn’t have any problems shutting Alfresco down.


As you have seen, getting Alfresco up and running on Debian is not difficult. Next time, I will show you how to migrate the database to MySQL, and some of the common issues you are likely to encounter along the way.


Alfresco: Sending mails with Gmail

Filed under: Alfresco — Tags: , , , , — Lorenzo E. Danielsson @ 12:04

I’ve been struggling with this for some time, in part no doubt, due to my limited knowledge of JavaMail. But, I always make up for lack of (knowledge, intelligence, experience) with pure stubbornness. Anyways, just thought I’d record it here, since it seems there are others struggling with it as well.

I had set up a Gmail account that I wanted to use to with an Alfresco installation. Here is some basic information (not that I think it matters).

  • Server: Debian Etch (odd packages from lenny and sid)
  • Alfresco: Alfresco Tomcat Community 2.1.0
  • JDK 6: package from Sid (aptitude search/show it to get the gory details)

There are exactly two files you need to edit to get STMP with Gmail to work. They are both located in /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/classes/alfresco (assuming that you installed Alfresco in /opt/alfresco.

The first is Open in your favorite vi clone and search for mail: Modify to look like this:

# Email configuration =
mail.port = 465
mail.transport.protocol = smtp
mail.username =
mail.password= asecretpassword
mail.smtp.auth = true
mail.smtp.socketFactory.port = 465
mail.smtp.socketFactory.class =
mail.smtp.socketFactory.fallback = false
mail.smtp.timeout = 25000
mail.smtp.starttls.enable = true

There, half the job is done. You will obviously need to modify the username and password (no will not work).

Now vi core-services-context.xml, find the section on mail (you can search for MAIL to find it quickly). Modify it to look as follows.

<!—                        —>
<!— MAIL SERVICE           —>
<!—                        —>

<bean id="mailService" class="org.springframework.mail.javamail.JavaMailSenderImpl">
  <property name="host">
  <property name="port">
  <property name="protocol">                            
  <property name="username">
  <property name="password">
  <property name="defaultEncoding">

  <property name="javaMailProperties">
      <prop key="mail.smtp.auth">${mail.smtp.auth}</prop>
      <prop key="mail.smtp.socketFactory.port">${mail.smtp.socketFactory.port}</prop>
      <prop key="mail.smtp.socketFactory.class">${mail.smtp.socketFactory.class}</prop>
      <prop key="mail.smtp.socketFactory.fallback">${mail.smtp.socketFactory.fallback}</prop>
      <prop key="mail.smtp.timeout">${mail.smtp.timeout}</prop>

You should now be set.

Test it

  1. Create a user for yourself if you haven’t already done so. Make sure you entered a valid email address in the email field (modify user if you didn’t).
  2. Select an existing space or create a new one. View space details.
  3. Find the option Manage Space Users and select it
  4. Invite a user. Select your user, and whatever role you want. Make sure you say Yes to sending an email to the user.
  5. When you are done and click finish, your user should have been added as a space user. If Alfresco freezes for a long time here then something is wrong and you need to go back and fix things.
  6. Check your personal email. There should be a mail from your Alfresco email user.

Good you are done, go and collect your money. Buy yourself a beer. And buy one for me too!

Blog at