Thursday, June 28, 2012

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% /

15 comments:

ProBasix Computing said...

Thank you for the step-by-step instructions. By far, it's the most detailed and thorough from what I know. I've spent the weekend following several recipes but so far I still don't have a working Alfresco install. After reading yours I thought I was onto something, however your instructions don't say where to copy the rest of the alfresco files after unzipping them, only the war files. I'm off to my next Google result but just wanted to let you know about the oversight. Cheers.

Stjepan Groš (sgros) said...

The rest of the files are not used, at least I didn't need them.

ProBasix Computing said...

I decided to try your instructions again from scratch, step-by-step, but they simply do not work. I'm using Scientific Linux 6.3 and Alfresco 4.0.e. As I follow your instructions everything seems to go without error but I just get a 404 at the end when I try to access the page:

HTTP Status 404 -

type Status report

message

description The requested resource () is not available.
Apache Tomcat/6.0.24

ProBasix Computing said...

Discovered a couple of noteworthy things:

1. You must access with the site with port 8080 and /share -- which actually gives me a login screen at http://mysite:8080/share

2. I have an empty alfresco database. It's there in phpmyadmin but there is nothing in it. I found instructions for building it with an older version of Alfresco by importing a db_setup.sql file, but the instructions assume an install in /opt which I don't have and I can't find the file anywhere in the leftovers of the tmp directory...

Stjepan Groš (sgros) said...

I assumed that the people know that when you install application into tomcat, then by default that application goes into some directory (i.e. alfresco, share) and in that case you access it using:

http://yourhost:8080/alfresco
http://yourhost:8080/share

Assuming you didn't recofigure tomcat, if you did - then you know where it is.

As for the database, you don't touch it, Alfresco will create it when it is started for the first time (and it has to have appropriate privileges to do so, i.e. the best is to grant all privileges to alfresco user defined in the database!).

Accorindg to what you wrote, you didn't start Alfresco but share (i.e. use the URL that has alfresco in it).

ProBasix Computing said...

Thanks for responding. I'm not new to linux but I am new to Alfresco and Tomcat. Your instructions:

"Now, start tomcat again and try to open the following URL in a Web browser: http://alfresco.example-domain.com/alfresco."

As I said in my earlier comment, this address (without the port) gets me nothing. Using http://mysite.com:8080/alfresco gets me a 404 error. Using http://mysite.com:8080/share gets me a log in page that will not let me log in. Opening the database in phpMyAdmin shows me the database is there but it is empty. The database user has ALL permissions.

Thanks for all your help. I'll try this again with Centos instead of Scientific Linux. There is obviously some difference between the two.

Stjepan Groš (sgros) said...

You are right, that URL was misleading. I changed URL to include port also.

As for your problem. I doubt that the problem is Scientific Linux. Your problem is not with the database, but it starts much earlier. Check that there is alfresco.war in webapps directory, that it has the same permissions and owner as share.war. Also, try to open URL and then look in catalina.out to see what tomcat reported as a problem.

Bill said...

Thank you for the step by step. I attempted to follow your instructions to a T, but I must have missed something. First followed your CentOS install (linked in this post) and then followed the instructions in this post.

I start Tomcat and browse to:
http://192.168.2.19:8080/alfresco/
I get an Error:
HTTP Status 404 -
type Status report
message
description The requested resource () is not available.
Apache Tomcat/6.0.24

So I got to the alfresco log and I see the following error:

13:17:05,062 WARN [org.hibernate.cfg.SettingsFactory] Could not obtain connection metadata
org.apache.commons.dbcp.SQLNestedException: Cannot load JDBC driver class 'org.postgresql.Driver'

So it looks like I must not have set db.driver or the db.url. I checked those and they are as specified. Any idea of what I might have done wrong? I checked and I can log in to mysql from the terminal using alfresco/alfresco.

Thanks for your help.

Bill

Stjepan Groš (sgros) said...

You mixed somewhere postgres and mysql. It clearly says it is trying to load postgres driver (org.postgresql.Driver) and not mysql one. Check again you settings... they have to be mixed somehwere...

JuHirvi said...

Thank you for an excellent tutorial. I like that you not only explain what to do but also why.

My installation is different in two respects. I use Alfresco 4.2.b, and Postgresql instead of MySQL.

I got the same symptoms reported here before: 404 error for the page /alfresco, and failed authentication at /share. The following steps got me a lot forward.

ESSENTIAL, to get rid of the error "Failed to create store root: ./alf_data/contentstore.deleted" in catalina.out:
Edit the file WEB-INF/classes/alfresco/repository.properties
# Change next lines
# old value
dir.root=./alf_data
# new value
dir.root=/var/lib/alf_data

Also, in the same file, update the database information (db.name etc.) with what you already have in alfresco-global.properties.

Move catalina.out log file somewhere else (so it wiill not confuse you later) and restart tomcat6 again. Now catalina.out will be smaller than before: 46k->40k :-)

The next error is "Schema auto-update failed".

The reason for the was that Java is too old. As it states in catalina.out:
Caused by: java.lang.NoClassDefFoundError: java/nio/channels/SeekableByteChannel

Alfresco 4.2 requires JDK 1.7, it says here:
http://wiki.alfresco.com/wiki/Alfresco_Community_4.2.a_Release_Notes

So simply do the following:
yum remove java-1.6.0-openjdk
yum install java-1.7.0-openjdk

Now there are still errors in catalina.out, but they are sensible: must configure ftp, ImageMagick, OpenOffice/LibreOffice, etc.

Maybe this will be helpful in doing that:
http://mwiki.yyovkov.net/index.php/Install_Alfresco_on_CentOS_6

JuHirvi said...

As an update to my previous comment. Editing WEB-INF/classes/alfresco/repository.properties does not seem to be necessary after all. In my installation, the original mistake was that alfresco-global.properties was not readable by tomcat.

You could add to your blog a reminder to check/change the permissions of alfresco-global.properties.

Unknown said...

i have tried following all the steps up to the point where you have to start tomcat6. unfortunately i get an error: [root@local init.d]# tomcat6 start
[root@local init.d]# /usr/sbin/tomcat6: line 30: /logs/catalina.out: No such file or directory

can somebody please tell me where did i go wrong

Stjepan Groš (sgros) said...

@Cajun

I have to be rude here. You are making a simplest, most basic mistake. Do you know what the PATH variable is? And how it is used to find and start a command, in this case tomcat6? You are making here at least ONE BIG mistake. Take a good look how I started tomcat 6 and how you are starting it.

Martin Skjöldebrand said...

Necroposting =)

I had the same problems as many others who left a comment. It turned out to be permission problems. Double and triple check your file systems permissions!

claytron said...

Great share. Thanks to your article, I am finally able to use MySQL with Alfresco.

About Me

scientist, consultant, security specialist, networking guy, system administrator, philosopher ;)

Blog Archive