Monthly Archives: January 2013

Manually install Alfresco with Tomcat (3.4.7)

building-blocks

This article will be in two parts: Manual Alfresco Install and Upgrade Alfresco (3.4.7 to 4.1.2).

Why would you want to manually install Alfresco since you can get very good installation packages from them? Good question. Sometimes the installer may not work in your environment for various reasons or maybe you might want to manage the install in a more detailed and organized fashion. For anyone who is interested in how to do this, this article will tell you how.

For our manual Alfresco install, you’ll want to make sure you have the following ingredients:

  • OS can be Windows 2008 R2, RHEL 5 or Ubuntu 10.04
  • Tomcat 6.0.29 (I managed to get this version here: http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.29/bin/)
  • JDK 1.6.0_31
  • MySQL 5.1 or 5.5 is fine (or if you prefer, you can use either MS SQL, Oracle or Postgresql) with MySQL (or other supported database type) jdbc driver jar file.
  • Open Office 3.2 (I used 3.2.1 found here: http://www.openoffice.org/download/legacy/other.html)
  • SWFTools & ImageMagick (I was able to install this with yum on RHEL)

You may find with the 3rd party tools (ImageMagick, OpenOffice and SWFTools) it’s easiest to get them out of an installed image directory and place them in a side directory. If you copy over the entire subdirectories for ImageMagick, SWFTools and Open Office, you should have all dependencies there.

Make sure all those are installed. On my system I have these directories set up:

  • /tomcat/apache-tomcat-6.0.29_alf347 <- For reference, I’ll refer to this as $TOMCAT_HOME
  • /java/jdk1.6.0_31 <- I’ll refer to this as $JAVA_HOME

The server I have this on is my own and I run everything as root. Please know that these articles are more to help you understand the topic and these steps shouldn’t be taken too literally especially if you’re installing these on a production server. Hopefully, your environment and systems administrators will require that your installs are set up in a more security-sensitive manner and run as a non-privileged user.

At the very least, you’ll want to make sure that JAVA_HOME is set in your startup.sh (startup.bat for Windows) else you’ll encounter this error:

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

You can set JAVA_HOME by adding this line at the front of startup.sh and shutdown.sh in $TOMCAT_HOME/bin:

export JAVA_HOME=/java/jdk1.6.0_31

Afterwards, you can do: ./startup.sh (startup.bat in Windows). In a web browser, you can verify Tomcat is running by going to http://localhost:8080.

If you decide you want to be able to access and use the manager application you’ll need to make sure these entries are added inside the tomcat-users stanza in tomcat-users.xml ($TOMCAT_HOME/conf):

<role rolename="manager"/>
<user username="tomcat" password="tomcat" roles="manager"/>

Keep in mind this will require a restart of Tomcat. Once you’re satisfied that Tomcat is installed properly, turn it off by issuing:

# cd $TOMCAT_HOME/bin
# ./shutdown.sh

So, to get started with installing Alfresco manually we’ll need to create these directory structures:

$TOMCAT_HOME/shared/classes
$TOMCAT_HOME/shared/lib

Next, change the value of shared.loader property to $TOMCAT/conf/catalina.properties:

shared.loader=${catalina.base}/shared/classes

Copy the jdbc driver (in my case, mysql-connector-java-5.1.20-bin.jar) to $TOMCAT_HOME/lib.

Next, open the $TOMCAT_HOME/conf/server.xml file and make sure the connector section has URIEncoding=”UTF-8″ in it. By default, Tomcat uses ISO-8859-1 character encoding when decoding URLs that are received from a browser. This may cause problems when creating, uploading, and renaming files with international characters:

<Connector port="8080" protocol="HTTP/1.1" URIEncoding="UTF-8"
 connectionTimeout="20000"
 redirectPort="8443" />

Save the server.xml file.

Also, there is an issue with Alfresco Share document downloads on Tomcat with https(SSL) for Internet Explorer versions 7 and 8. With IE7 and IE8 you will see an error message if you try to download a document from Alfresco Share in Tomcat with https (SSL) enabled. To resolve this issue:

Open $TOMCAT_HOME/conf/context.xml file.
Add the following line to the context element:

<Valve className="org.apache.catalina.authenticator.SSLAuthenticator" securePagesWithPragma="false" />

Save this file.

Now with your web browser, go to the download sections (support.alfresco.com if you’re an Enterprise customer and http://wiki.alfresco.com/wiki/Community_file_list_3.4.d if you’re a Community user) and download 3.4.7 or 3.4.d. Your download format should be the war files in .zip format and NOT the normal installation packages (setup.exe or .bin files).

My downloaded file looks like: alfresco-enterprise-3.4.7.zip. Unzip the downloaded file. This should now show the following structure:

bin/ <- in this directory, there are a number of utilities

web-server/
– conf/ <- config and properties files
– endorsed/ <- third party jars
– lib/ <- driver file for postgresql
– shared/classes <- Alfresco global properties file and extensions subdirectory
– webapps/ <- .war files

Now, copy the alfresco.war and share.war from webapps to $TOMCAT_HOME/webapps/ directory.

Next, copy the shared/classes/alfresco-global.properties.sample file to $TOMCAT_HOME/shared/classes and rename it to alfresco-global.properties. Also copy the whole directory structure of shared/classes/alfresco to $TOMCAT_HOME/shared/classes like so:

cp -rfv alfresco $TOMCAT_HOME/shared/classes/.

At this point, it would be a good idea to create your MySQL database. Make sure that MySQL server is running:

  • CentOS/RHEL: service mysqld start
  • Ubuntu: service mysql start
  • Windows 2008: Open up services.msc and start the MySQL service.

Start the mysql client and do the following from the command line:

> CREATE DATABASE alf347 DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
> grant all privileges on alf347.* to 'alfresco'@'localhost' identified by 'alfresco';

In your filesystem, identify a good place to set up your Alfresco data directory. This can be anywhere on a disk that has plenty of space. In my case I have /srv/347tomcat/alf_data. Make sure you create this directory as you need it and ensure the user running Alfresco will have read/write access to it.

Now, open up $TOMCAT_HOME/shared/classes/alfresco-global.properties and add these settings:

root.dir=/srv/347tomcat/alf_data
# Alfresco and Share context
alfresco.context=alfresco
alfresco.host=${localname}
alfresco.port=8080
alfresco.protocol=http

share.context=share
share.host=${localname}
share.port=8080
share.protocol=http
# Database settings
db.username=alfresco
db.password=alfresco
db.driver=org.gjt.mm.mysql.Driver
db.url=jdbc:mysql://localhost/alf347?useUnicode=yes&characterEncoding=UTF-8
# Open Office Transformation Settings
jodconverter.officeHome=/opt/openoffice.org3/program
jodconverter.portNumbers=8101
jodconverter.enabled=true
# ImageMagick settings
img.root=/usr
img.dyn=${img.root}/lib
img.exe=${img.root}/bin/convert
swf.exe=/usr/bin/pdf2swf
# Index settings
index.subsystem.name=lucene
# If you have a big repository, it's ok to use AUTO here so that 
# reindexing doesn't take up a lot of time.
index.recovery.mode=FULL

Save alfresco-global.properties file. Add these lines now to startup.sh:

export ALF_HOME=.
export JAVA_OPTS='-Xms512m -Xmx1024m -Xss256k -XX:MaxPermSize=256m -XX:NewSize=2
56m -server'
export JAVA_OPTS="${JAVA_OPTS} -Dalfresco.home=${ALF_HOME} -Dcom.sun.management.jmxremote"

Save startup.sh.

Next, go to $TOMCAT_HOME/shared/classes/alfresco/web-extension. Change the name of share-config-custom.xml.sample to share-config-custom.xml. Edit this file and uncomment the first instance of this element:

<config evaluator="string-compare" condition="Remote">

If you’re using Enterprise instead of Community, create the license directory: $TOMCAT_HOME/shared/classes/alfresco/extension/license and place the license file there. Now you can run startup.sh from the command line. You should now have a working Alfresco install. You can do a simple smoke-screen test by logging in, creating a Share site, adding a test folder and a couple of documents to make sure it’s working as expected. In fact, it may be a good idea to create a number of sites with differing folder structures and a couple of simple rules/workflows. Once you upgrade, you can test all of these to make sure everything updated as they should.

Happy Installs!

When you’re ready to upgrade have a look here.

Cheers! – H.S.