Installing Alfresco Community Edition on minimal CentOS...

In this post I'm going to describe how to install Alfresco Community Edition 4.0d starting with a minimal CentOS 6 installation. This will be a two part post after which I'm going to describe how to integrate Alfresco with FreeIPA for authentication and authorization purposes. The goal of the installation is to use as much as possible software available in CentOS. The reason for doing so is that update process is easier, i.e. you only have to do yum update instead of manually downloading and installing updated software.

Environment and Configuration Parameters

I assume that you have CentOS installation ready. If not, then install it, and if you need some info on how to do it, look at this post. Furthermore, I assume that Alfresco should reside within Intranet, i.e. local network. The reason is that there is no need for Alfresco to be accessible from the Internet and thus it doesn't have to be in DMZ. I'll assign IP address 172.16.1.3 to this host. The FQDN of the host will be alfresco.example-domain.local. Now, if you have working DNS you should put this name into DNS, but it's not necessary, i.e. you can put it into /etc/hosts file of any host that will access Alfresco (including Alfresco itself) and that will do for now.

Alfresco needs a relational database. I'm going to use MySQL database. Furhtermore, I'll assume that this database is on the same host as Alfresco. This will allow me to restrict access to database. Unfortunately, standard JDBC driver for MySQL doesn't support access to database via Unix socket, so database has to be accessible via network stack. I'm going to restrict it to loopback interface.

Note that I started with the following state of disk usage:

# df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             7,0G  944M  5,7G  15% /

Prerequisite software installation

As for the prerequsite software you have to install the following packages (all of them shipped with CentOS):

• java-1.6.0-openjdk - unless you explicitly specify which java you want to be installed, gcc's version will be used and that one won't work with Alfresco.
• tomcat6 - servlet container that will run Alfresco. It is mandatory to install this package. This, along with dependencies, will be 129M to download and will take about 382M disk space.
• mysql-server - this is a package that holds server part of MySQL database.
• mysql-connector-java - JDBC connector that will allow Alfresco to access MySQL database.
• unzip - so that you can unpack Alfresco archive (which is distributed as a zip file)

So, install it using yum. This will download 168M which will expand into 503M. Afterwards, this is the state of disk usage:

# df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             7,0G  1,6G  5,1G  24% /

Configure MySQL database

We also have to prepare MySQL database, i.e. you have to do the following steps:

1. Configure database to use UTF-8 by default.
2. Configure it to listen only on loopback interface.
3. Start database and set root password.
4. Create alfresco database.
5. Create alfresco user and assign it a password.
6. Configure system to start MySQL database during the boot process.

The first two steps are done by editing /etc/my.cnf file. Integrate the following lines with the already existing content (i.e. to existing sections add missing lines, if the section doesn't exist in my.cnf file add it along with all its lines):

[client]
default-character-set=utf8

[mysql]
default-character-set=utf8

[mysqld]
bind-address=127.0.0.1
character-set-server = utf8
collation-server = utf8_unicode_ci
init-connect='SET NAMES utf8'
character-set-server = utf8

Note that MySQL has to listen on loopback because JDBC doesn't allow connection via Unix socket, at least not without tweaks to Alfresco code itself.

Step 3 (i.e. set root password) is done by starting MySQL server and then setting password:

/etc/init.d/mysqld start
/usr/bin/mysqladmin -u root password 'new-password'

String 'new-password' replace with your password (and keep quotes, they prevent shell from interpreting any special character in password you might have!). You should be careful with this password as it is very critical peace of information!

Step 4 and 5 (create alfresco database and user) are done using mysql tool. So, first start this tool:

# mysql -u root -p
Enter password: <type here root password>
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 3
Server version: 5.1.61 Source distribution

Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

and now create database:

mysql> create database alfresco;
Query OK, 1 row affected (0.00 sec)

and grant alfresco user all permissions on the database:

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

The word PASSWORD should be replaced with a password. Again, this one is critical since all the data will be accessible if someone gets hold on that password. And, while you are at that, remove test database as it is not necessary and might even present security threat:

mysql> drop database test;
Query OK, 0 rows affected (0.00 sec)

That's it as far as mysql client is concerned. So, leave it using exit keyword.

Finally, we should configure system to start MySQL database on each boot. This is easily done with:

chkconfig mysqld on

OK, so much about database. One more thing before going to Alfresco installation. You have to configure tomcat so that it loads MySQL connector when starting, otherwise Alfresco won't be able to connect to database! To to that, open file /etc/tomcat6/catalina.properties and search for line "shared.loader=". Add to that line string /usr/share/java/mysql-connector-java.jar, i.e. it shoud look now like this:

shared.loader=/usr/share/java/mysql-connector-java.jar

Save the file and exit and that's it. Now on to Alfresco itself.

Alfresco Installation

First, go to Alfresco download site and download Community edition, i.e. download file alfresco-community-4.0.d.zip. Then, unpack it (using unzip tool) into a temporary directory:

mkdir tmp

cd tmp

unzip ../alfresco-community-4.0.d.zip

<unzip progress output>

You'll have now few new directories. From directory web-server/webapps move files alfresco.war and share.war into tomcat webapps directory, i.e. into /var/lib/tomcat6/webapps. From now on, I'm going to reference that directory as $WEBAPPS, to shorten a bit typing. Now, start wait a minute and then stop tomcat server. This is so that it unpacks alfresco and share war archives:

/etc/init.d/tomcat6 start
/etc/init.d/tomcat6 stop

In case you receive ERROR message trying to stop tomcat, wait a bit more and then try again. Namely, until tomcat finishes initialization you can not stop it.

Note also that tomcat writes its logs into /var/log/tomcat6. You should monitor that directory when starting tomcat. More specifically, watch catalina.out file. Furthermore, the tip, I remove all log files before starting tomcat again so that it doesn't clutter new log messages with the old ones. Of course, I'm doing that only during installation phase. Later, it is very good idea to keep the logs around!

Go now into directory  $WEBAPPS/alfresco/WEB-INF/classes. There, you'll see file alfresco-global.properties.sample. Copy this file into alfresco-global.properties and change permissions to a more restrictive values:

cp alfresco-global.properties.sample alfresco-global.properties
chmod 600 alfresco-global.properties

and open it in editor. In there do the following:

1. Immediately at the beginning uncomment lines  dir.root and dir.keystore. Set dir.root to a directory where Alfresco will store data. I used /var/lib/alf_data (which of course, should be created manually!) but any value with enough storage will do. Also, change the owner of that directory to tomcat and restrict access permissions so that only user tomcat can enter into that directory (use permissions 700). dir.keystore should be set to $WEBAPPS/alfresco/WEB-INF/classes/alfresco/keystore.
2. Uncomment lines db.username and db.password and set correct value for password (username is alfresco so that shouldn't be necessary to change). This password in plain text is the reason you had to change permissions of the file.
3. Find MySQL section, and in particular lines there db.driver and db.url and uncomment them. Change the value of db.driver to com.mysql.jdbc.Driver.

Now, open file log4j.properties that is in the same directory as the previous file, i.e. $WEBAPPS/alfresco/WEB-INF/classes. Find there the following line:

log4j.appender.File.File=alfresco.log

And change it to:

log4j.appender.File.File=/var/log/tomcat6/alfresco.log

This line specifies where Alfresco will do its logging. The obvious place is the same directory where tomcat places its logs. Do the same change in file $WEBAPPS/share/WEB-INF/classes/log4j.properties.

Now, start tomcat again and try to open the following URL in a Web browser: http://alfresco.example-domain.com:8080/alfresco. After a bit of wait you should be presented with a guest Alfresco home page. You can then logout and login as admin (U: admin/P: admin). Note that if you can not connect, the reason is firewall on Alfresco server. Temporarily turn off the firewall with:

/etc/init.d/iptables stop

and then try again.

Don't forget to configure system so that tomcat is started after each reboot. Anyway, this is the first part of the installation. There are some more tweaks you should do that I'm going to describe in the following post. For the end of this post let me show the disk usage:

# df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             7,0G  2,1G  4,6G  31% /