Installing Alfresco (4.1.1) with JBoss (EAP 5.1.1)

With your Alfresco install you may have decided that Tomcat as an application server is not robust enough. You can opt for WebSphere, WebLogic and even JBoss if you feel you require the extra functionalities. This article addresses how to install Alfresco with JBoss.

First, you’ll need the JBoss installer. I had to get mine at access.redhat.com. Keep in mind though, Alfresco still only supports 5.1.1 EAP (enterprise version of JBoss). My installer looks like this file: jboss-eap-installer-5.1.1.jar.

I also went out and got the Java JDK 1.6.0_33 to use with this. For this installation I used Alfresco Enterprise 4.1.1. You’ll want to get the .ear file for this instead of the usual .zip file you get for Tomcat.

So, getting started, install the JDK to the directory of your choice. I have to install a number of different versions of Java, Alfresco, Tomcat and JBoss so I tend to have a top level directory with each of those names and then install the particular version beneath it. My installation of Java and JBoss look this respectively:

  • /java/jdk1.6.0_33
  • /jboss/jboss-eap-5.1

Install JBoss is fairly simple. You simply run the following:

# <path_to_jdk1.6.0_33>/bin/java -jar jboss-eap-installer-5.1.1.jar

To make it simple, I’ll refer to JBOSS_HOME as my jboss directory:

/jboss/jboss-eap-5.1/jboss-as

Follow the instructions and install it. Next, put alfresco-enterprise-ear-4.1.1.zip into a tmp directory and unzip it. You’ll also have to “unzip” the resulting alfresco-enterprise-ear.4.1.1.ear. If you need to, you can change the .ear extension to .zip to get the unzip to work.

Copy the alfresco-global.properties.sample file from the temporary directory to the <JBOSS_HOME>/server/default/conf directory as alfresco-global.properties minus the .sample on the end.

Make sure you refer to this article on how to set up your repository. Remember that you’ll need to create a database, modify it for Alfresco use and set up a directory to use for your contentstore and indexes. Edit the parameters in the alfresco-global.properties.sample file to suit your environment. Save the alfresco-global.properties in the conf dir.

Here are my settings. Please adjust to reflect your environment. Make sure these lines are added in your alfresco-global.properties file:

dir.root=/srv/4119jboss/alf_data
dir.license.external=/jboss/jboss-eap-5.1/jboss-as/server/default/conf/alfresco/extension/license
db.username=alfresco
db.password=alfresco
ooo.exe=/alfresco/4119/openoffice/program/soffice.bin
ooo.enabled=false
ooo.port=8100
img.root=/alfresco/4119/common
img.dyn=${img.root}/lib
img.exe=${img.root}/bin/convert
swf.exe=/alfresco/4119/common/bin/pdf2swf
swf.languagedir=/alfresco/4119/common/japanese
jodconverter.enabled=true
jodconverter.officeHome=/alfresco/4119/openoffice
jodconverter.portNumbers=8100
db.driver=org.gjt.mm.mysql.Driver
db.url=jdbc:mysql://localhost/alf4119jboss?useUnicode=yes&characterEncoding=UTF-8
index.subsystem.name=lucene
index.recovery.mode=FULL
alfresco.context=alfresco
alfresco.host=${localname}
alfresco.port=8080
alfresco.protocol=http
#
share.context=share
share.host=${localname}
share.port=8080
share.protocol=http
alfresco.rmi.services.host=0.0.0.0

Copy the alfresco.war and share.war file from the tmp directory to the <JBOSS_HOME>/deploy directory
Copy database jdbc driver to <JBOSS_HOME>/server/default/lib
Add URIEncoding=”UTF-8″ to Connector stanzas for 8080 and 8009 in both of these files:

  • <JBOSS_HOME>/server/default/deploy/jbossweb.sar/server.xml
  • <JBOSS_HOME>/server/all/deploy/jbossweb.sar/server.xml

JBoss by default can have a lot of debug entries in the logs. To squelch this a bit, edit the <JBOSS_HOME>/server/default/conf/jboss-log4j.xml file to reduce the huge debug log output:

<root>
 <priority value="INFO" />
 <appender-ref ref="CONSOLE"/>
 <appender-ref ref="FILE"/>
</root>

Add these log settings to the <JBOSS_HOME>/server/default/conf/jboss-log4j.xml file:

<category name="org.jboss.logging.Log4jService$URLWatchTimerTask">
 <priority value="INFO"/>
</category>
<category name="org.jboss.system.server.Server">
 <priority value="INFO"/>
</category>
<category name="org.jboss">
 <priority value="WARN"/>
</category>
<category name="net">
 <priority value="WARN"/>
</category>
<category name="org.alfresco">
 <priority value="WARN"/>
</category>
<category name="org.alfresco.repo.policy">
 <priority value="WARN"/>
</category>
<category name="org.springframework">
 <priority value="WARN"/>
</category>
<category name="org.hibernate">
 <priority value="WARN"/>
</category>
<category name="org.hibernate.cache.ReadWriteCache">
 <priority value="ERROR"/>
</category>
<category name="org.hibernate.cache.EhCacheProvider">
 <priority value="ERROR"/>
</category>
<category name="org.hibernate.engine.StatefulPersistenceContext.ProxyWarnLog">
 <priority value="ERROR"/>
</category>
<category name="org.apache.myfaces">
 <priority value="ERROR"/>
</category>
<category name="org.jbpm.jpdl.xml.JpdlXmlReader">
 <priority value="ERROR"/>
</category>

Save this file and next, edit the <JBOSS_HOME>/server/default/deployers/ejb3.deployer/META-INF/jpa-deployers-jboss-beans.xml file, and then change the hibernate.bytecode.provider=javassist line to hibernate.bytecode.provider=cglib.

For example:

<entry>
 <key>hibernate.bytecode.provider</key>
 <value>cglib</value>
</entry>

Add these to your <JBOSS_HOME>/bin/run.sh file near the top:

export JAVA_HOME=/alfresco/4119/java
JBOSS_CLASSPATH="/jboss/jboss-eap-5.1/jboss-as/server/default/conf"

Then, after this line:

JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv4Stack=true"

add these:

JAVA_OPTS="$JAVA_OPTS -Xms512m -Xmx1024m -XX:MaxPermSize=512m"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote -Dalfresco.home=."

Edit the filtered packages list.

Open the <JBOSS_HOME>/server/default/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml file, and then locate the filteredPackages property of the WarClassLoaderDeployer bean.

Open the <extension>\war-deployers-jboss-beans.xml.fragment.sample file.
This sample file contains a WarClassLoaderDeployer bean definition fragment for use when configuring JBoss.

Copy the full WarClassLoaderDeployer bean from the sample file.
In the war-deployers-jboss-beans.xml file, paste the sample bean fragment over the WarClassLoaderDeployer bean. The bean definition contains the filteredPackages list that is required for Alfresco. This list is on one line and must not contain any breaks.

Save the <JBOSS_HOME>/server/default/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml file.

Now, the moment of truth. Go to JBoss Server <JBOSS_HOME>/bin and do:

# ./run.sh -b 0.0.0.0  <- This will allow JBoss to bind to all ip addresses. 
*Change it to suit your environment if needed.

The alfresco.log file will be generated wherever you start it. So if you are in <JBOSS_HOME>/bin you should see it there. You can “tail” the file and follow along. Work through any issues. Try to access it like you would any other Alfresco install (http://<hostname>:<port>/share) and voila! Success! Hopefully 😉

Cheers! -H.S.

Upgrade Alfresco – 3.4.7 to 4.1.2

As you would expect, we get a lot of questions about upgrade issues about 2-3 weeks following a service pack release. Fortunately, going from one SP to another or even an upgrade to a new major release calls for pretty much the same process. In a nutshell it usually looks like:

  1. Verify your new Alfresco version will work with your hardware, OS and database server. If necessary, upgrade those components to supported versions. You can check this by using the Alfresco Environment Validation Tool (http://code.google.com/p/alfresco-environment-validation/downloads/list <- make sure you get the version 4.0 — this should work for 4.1.2 as well).
  2. Install a clean, vanilla installation of your newest version in a separate directory (ideally on a newer server if possible).
  3. Verify this install works as expected out of the box without adding old data just yet.
  4. Turn off the new Alfresco.
  5. Replace the new contentstore data with the old contentstore data.
  6. Create a new database of the same type as your old one and restore your old database to this one.
  7. Verify new Alfresco settings point to this restored database.
  8. Verify index.recovery.mode is set to FULL if using Lucene.
  9. Install your new version’s license to the new Alfresco license directory.
  10. Add your customizations.
  11. Start Alfresco. Work through any issues.
  12. Verify new Alfresco upgrade, uninstall old Alfresco if desired.

Running the Environment Validation Tool (EVT)

Download the 4.0 tool by clicking on this link (http://alfresco-environment-validation.googlecode.com/files/Alfresco4.0-evt-1.01.zip). Unzip the file.
Simply running the command ./evt.sh will reveal these options:

usage: evt[.sh|.cmd] [-?|--help] [-v] [-V|-vv]
 -t databaseType -h databaseHost [-r databasePort]
 [-d databaseName] -l databaseLogin [-p databasePassword]
where: -?|--help - display this help
 -v - produce verbose output
 -V|-vv - produce super-verbose output (stack traces)
 databaseType - the type of database. May be one of:
 mysql, postgresql, oracle, mssqlserver, db2
 databaseHost - the hostname of the database server
 databasePort - the port the database is listening on (optional -
 defaults to default for the database type)
 databaseName - the name of the Alfresco database (optional -
 defaults to 'alfresco')
 databaseLogin - the login Alfresco will use to connect to the
 database
 databasePassword - the password for that user (optional)

The tool must be run as the OS user that Alfresco will run as. In particular
it will report erroneous results if run as “root” (or equivalent on other
OSes) if Alfresco is not intended to be run as that user. Before running, ensure Alfresco is not running! Open evt.sh and make sure this is added at the beginning:

#!/bin/sh
export JAVA_HOME=/java/jdk1.6.0_31
$JAVA_HOME/bin/java -Djava.ext.dirs=lib EVT $*

You can then run it like so:

./evt.sh -v -t mysql -h localhost -r 3306 -d alf347 -l alfresco -p alfresco > evt.out

You can then look through evt.out for warnings and failures. My initial warnings were the following. Below each one I’ll address them:

Validating Operating System
 OS : Linux .......................................PASS
 Distribution : RHEL release 5.8 ..................WARN!
 Reason : Unsupported Linux distribution
 Ramification : Alfresco may function sufficiently well for development purposes but must not be used for production
 Remedy : Install a supported OS
 For more information: http://www.alfresco.com/services/support/stacks/
 : http://www.alfresco.com/services/subscription/supported-platforms/4-x.pdf

The supported platforms doc do mention 5.5 being the supported version but if you’re on the same major version but slightly higher minor version, there should be no problem and these setups are usually supported.

Validating Server Hardware
 CPU Clock Speed : 2261Mhz .....................................WARN!
 Reason : CPU clock speed of 2261Mhz is slower than that recommended for test or production use (2500Mhz)
 Ramification : Alfresco will perform well for development purposes but this server should not be used for other purposes
 Remedy : Upgrade the server to one with more modern CPUs (CPU clock speed of at least 2500Mhz)
CPU Count : 2 sockets, 2 cores ..........................PASS
 Installed RAM : 2048MB ......................................PASS

If this is a production install, you will want to have a higher clock speed. However, I’m running this on an ESX guest. This will be ok for our purposes of testing and development.

Validating Network
 Local Hostname : localhost.localdomain .......................PASS
 IP Address : 127.0.0.1 ...................................WARN!
 Reason : IP address for hostname localhost.localdomain is in the localhost address range (127.*.*.*)
 Ramification : Alfresco cannot be clustered
 Remedy : Fix the server's network configuration and/or the DNS configuration

Again, in a production environment, you’ll need to set up a hostname that resolves to the network adapter you’re going to use — especially if you’re planning on clustering Alfresco. You can simply add a hostname to your /etc/hosts file and to your environment’s DNS server.

Validating 3rd Party Apps
 Can fork OpenOffice : no ..........................................WARN!
 Reason : Unable to fork OpenOffice executable
 Ramification : Various document format transformations, as well as full text indexing of various document formats will be unavailable
 Remedy : Install OpenOffice v3.2 or greater and either ensure it is in the PATH or configure Alfresco to point to the fully qualified path of the OpenOffice executable ('soffice')
 For more information: http://download.openoffice.org/
 : http://wiki.alfresco.com/wiki/Setting_up_OpenOffice_for_Alfresco

You’ll simply want to make sure that soffice.bin is in the path if you don’t set the path explicitly in alfresco-global.properties. If you’re good here or don’t need soffice functionality, it’s ok to disregard.

Can fork ImageMagick : yes .........................................PASS
 ImageMagick Version : 6.2.8 .......................................WARN!
 Reason : Alfresco requires ImageMagick v6.5 or greater
 Ramification : While Alfresco will start correctly, various image transformations may not function correctly
 Remedy : Install ImageMagick v6.5 or greater
 For more information: http://www.imagemagick.org/

You will want to upgrade ImageMagick. On RHEL/CentOS/Ubuntu it’s relatively simple to build ImageMagick from source and then point the settings in alfresco-global.properties to the right one. If you can confirm that you’re going to use the right version, it’s ok to disregard.

Validating Database
 Database Type : mysql ...recognised .........................PASS
 JDBC Driver Loaded : yes .........................................PASS
 Database Connectivity : connected ...................................PASS
 Scrollable Result Sets: true ........................................PASS
 JDBC Driver Version : 5.1 .........................................PASS
 MySQL Version : 5.0.95 ......................................WARN!
 Reason : Unsupported MySQL version
 Ramification : Alfresco may not function correctly on this version
 Remedy : Install MySQL 5.5 with at least patchlevel 16
 For more information: http://dev.mysql.com/downloads/mysql/
Default Storage Engine: MyISAM ......................................WARN!
 Reason : InnoDB should be the default storage engine, but is not
 Ramification : None. Since v3.3, Alfresco will force the use of InnoDB for the Alfresco tables regardless of the default engine
 Remedy : Reconfigure MySQL to use the InnoDB storage engine as the default

You’ll definitely want to upgrade MySQL to the appropriate version if you’re in production. For development and testing, this is usually not an issue. Using InnoDB is a must for production environments also.

Case Sensitivity Level: unknown .....................................WARN!
 Reason : Unable to determine identifier case sensitivity level
 Ramification : Backups of the Alfresco database may be OS specific
 Remedy : Manually validate that MySQL is configured to use case-insensitive identifiers; specifically, ensure that lower_case_table_names=1 in the MySQL configuration
 For more information: http://dev.mysql.com/doc/refman/5.5/en/identifier-case-sensitivity.html
Auto-inc Lock Mode : unknown .....................................WARN!
 Reason : Unable to determine InnoDB auto-increment lock mode
 Ramification : Alfresco may perform poorly under heavy write load due to excessive blocking in MySQL
 Remedy : Manually validate that MySQL is configured with InnoDB auto-increment lock mode 2; specifically, set innodb_autoinc_lock_mode=2 in the MySQL configuration
 For more information: http://dev.mysql.com/doc/refman/5.5/en/innodb-auto-increment-handling.html

… later you may see this one …

System Encoding : utf8 ........................................PASS
 Unsafe for binlog : OFF .........................................INFO
 Reason : innodb_locks_unsafe_for_binlog should be set to ON
 Ramification : Alfresco may not function correctly under certain circumstances
 Remedy : Correct the value of innodb_locks_unsafe_for_binlog and rerun this test
 For more information: http://dev.mysql.com/doc/refman/5.5/en/innodb-parameters.html#sysvar_innodb_locks_unsafe_for_binlog

You should have these two set in your production environments /etc/my.conf:

character-set-server=utf8
collation-server=utf8_general_ci
default-storage-engine=innodb
lower_case_table_names=1
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=ON

You will see this one if you haven’t made any changes to open file descriptors allowed for your OS:

OS Architecture : 64 bit ......................................PASS
 File Descriptors : 1024 ........................................FAIL!!
 Reason : Alfresco requires at least 4096 file descriptors
 Ramification : While Alfresco will start correctly, you will likely see errors during indexing of content into the search engine
 Remedy : Increase the number of file descriptors available to Alfresco

As with the others, in a production environment fixing this is crucial. However, for testing and development purposes it’s not so important unless you plan to do some very intensive testing. To remedy this, please do the following:

Edit /etc/security/limits.conf and add the following settings:

alfresco soft nofile 4096
alfresco hard nofile 65536

Save limits.conf and run sysctl -p from the command prompt.

This sets the normal number of file handles available to the alfresco user to be 4096. This is known as the soft limit. As the alfresco user, set a system-level setting for Linux, up to the hard limit, using the following command:

# ulimit -n 8192

If you’re using root to run Alfresco in a test environment, change the alfresco user to root or “*” in /etc/security/limits.conf.

Once you’ve determined that you are safe to upgrade into your environment, your next step is to upgrade to the highest fixpack for your current version. In our case (we have 3.4.7 installed if you remember), we’ll need to upgrade to 3.4.11. Our path will look like this:

3.4.7  ->  3.4.11  ->  4.1.2

So, go ahead and download the 3.4.11 version and follow the instructions from the last article on how to install it to its own directory. Don’t forget to create a new database and reference your new alfresco-global.properties to it. The same goes for your alf_data directory (dir.root).

Once you have 3.4.11 up and running and you’ve verified that it’s working as it should, it’s time to do cold backups of your data from 3.4.7.

  1. Turn off Tomcat from 3.4.11.
  2. Make sure there are no Alfresco processes running.
  3. Back up the 3.4.7 database by issuing: mysqldump -u alfresco -palfresco alf347 > alf347.sql
  4. Back up /srv/347tomcat/alf_data/contentstore directory.

Now, prepare the 3.4.11 data areas for a restore of data from 3.4.7. Drop and create new 3.4.11 database by issuing these commands within the MySQL command line interface:

mysql> drop database alf3411;Query OK, 84 rows affected, 2 warnings (0.08 sec)
mysql> create database alf3411 default character set utf8 default collate utf8_general_ci;

Query OK, 1 row affected (0.01 sec)

mysql> grant all privileges on alf3411.* to 'alfresco'@'localhost' identified by 'alfresco';

Query OK, 0 rows affected (0.00 sec)

Clear all data from 3.4.11’s contentstore directory and replace it with data from 3.4.7’s contentstore. Restore the 3.4.7 database to your 3.4.11 database from the system command line:

mysql -u alfresco -palfresco alf3411 < alf347.sql

Add the license file to 3.4.11 in $TOMCAT_HOME/shared/classes/alfresco/extension/license. After this, you can run startup.sh and view the logs.

You should see something like this:

INFO [org.alfresco.service.descriptor.DescriptorService] Alfresco started (Enterprise): Current version 3.4.11 (935) schema 4213 - Originally installed version 3.4.7 (572) schema 4205

And if you log in and click on the Alfresco logo, you should now see the version updated:

<insert screenshot>

If you’re able to see this, then the upgrade to the highest service pack was a success. To go from 3.4.11 you can do the same procedure with the 4.1.2 wars. This time however, use the data (both contentstore and database) from the 3.4.11 as your restore data to 4.1.2. Something to keep in mind for upgrades to 4.x from 3.x, is to ensure that Lucene is still used initially (later you can upgrade to Solr if you decide to but right now, it’s important to make sure your upgrade works with Lucene first). Make sure you have this setting in place:

index.subsystem.name=lucene

Then, make sure you follow the same steps as you did for installing/upgrading to 3.4.11.

Keep in mind you may have to reset the repository (both database and contentstore) and the license if you encounter issues with the upgrades. Try to think of the upgrades as migrations in a sense. If you do them properly (and the supported way), this method is really how they’re done with minimal issues.

Happy upgrading!

Cheers! -H.S.

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.

Alfresco Install with MySQL

Installing Alfresco can sometimes be like putting a puzzle together. Sigh.
Installing Alfresco can sometimes be like putting a puzzle together.

In order to help our customers with different issues, I have to install Alfresco a lot. We do have an ESX server that we can use, so in theory, we should be able to install Alfresco once and be done with it. In reality though, our customers’ versions of installed Alfresco can be anywhere between 3.x through 4.1.2 (currently) and with many different hotfix versions along the way. Occasionally we have the poor soul who is on an older and unsupported version (2.1 often shows up but we do support helping them upgrade at least to the 3.x series). So, it’s a good idea for me to be well-versed in being able to get Alfresco set up and running at a moment’s notice. It also helps to set up your environment in such a way that it makes it a snap to install additional versions.

For me personally, I prefer that Alfresco be installed on Linux (RHEL or Ubuntu is fine either way). I am so used to getting around in the *NIX world that now I find it just a little difficult to maneuver in Windows 2008. Although Mac is supposed to be a *NIX, it’s just not the same but that’s another story in itself (note: installing Enterprise on the Mac is not supported — but with a few steps it’s really a snap and really useful if you prefer to do development on a Mac). Either way, choose an OS you’re familiar with. You may want to refer to our Supported Platforms page to see which ones are supported for the version you’re wanting to install. Also, please be aware that on our main site, you probably will only be able to find the most recent Alfresco install package. You can however, visit here if you really want an older version.

You’ll need an RDBMS database server. For most, the easiest one to whip up is going to be MySQL. Keep in mind you can use Oracle, MS-SQL or PostgreSQL if you prefer. I’ll be providing instructions on how to set up your server with MySQL however. For the other database servers you’ll want to look up how to install them, create a database/schema and ensure the right privileges are in place for the database user. You’ll also want to locate the proper JDBC driver for your version as well as what the JDBC URL should look like. Links for docs on how to configure the other supported databases are below:

Moving on with the MySQL server install:

  • On RHEL, you can simply do: yum install mysql-server
  • On Ubuntu, you can do: apt-get install mysql-server-5.5 (If you’re not sure, just do apt-cache search mysql-server and the current version should be revealed)

Using the apt or yum tool will also install any necessary goodies that MySQL server depends on, if any.

On Windows, you can go to the MySQL website, download the latest 5.5 version and install it there. With Windows there is an advanced configuration wizard that comes with the installer. Make sure you run it so you can set up your MySQL root user password. With Linux, you’ll need to do a few extra things to get the root user set up. From the command line do:

# mysql -u root

This should get you to the MySQL command line. Here you can do this to set your MySQL root password:

> grant all privileges on *.* to 'root'@'localhost' identified by '<type your password here>' with grant option;

If you really do need remote access (and I wouldn’t do this unless you absolutely know what you’re doing), you can do this:

> grant all privileges on *.* to 'root'@'%' identified by '<type your password here>' with grant option;

This will allow you to connect to your MySQL server from a remote workstation using the root account.

Next, we’ll need to set up a database and grant privileges for it so that Alfresco can use it.

I prefer to use a naming convention like alf<version without dots>. It helps to keep track of the myriad Alfresco databases I now have. So if we’re installing 4.1.2 Alfresco, you can do this:

> create database alf412;
> grant all privileges on alf412.* to 'alfresco'@'localhost' identified by 'alfresco';

Of course, feel free to replace the database username and password to one that works with your environment and preferences.

So, now we have MySQL set up. It’s time to get Alfresco. You can go here for the latest versions:

Community
Enterprise

Keep in mind that the Enterprise trial is for 30 days. So you’re aware, compared to similar open source/community and enterprise softwares, Alfresco Community is to Alfresco Enterprise as Fedora is to RHEL. Not much of a difference really (beyond extra features) except that an enterprise version you can expect to pay for support for it while a community version will be supported by a forum or IRC channel.

My download looks like:

alfresco-enterprise-4.1.2-installer-linux-x64.bin

Keep in mind that all steps going forward work for either Community or Enterprise (except for licenses). So, from my command line I try this:

# ./alfresco-enterprise-4.1.2-installer-linux-x64.bin
*If you see a warning that you’re lacking the correct privileges to run it, do this before trying it again:
# chmod +x alfresco-enterprise-4.1.2-installer-linux-x64.bin

The install is pretty straight-forward with a few caveats:

  • Choose the Advanced install
  • Un-check the PostgreSQL (unless you really want to use the distributed PostgreSQL server — which you really don’t. Even if you prefer to use PostgreSQL, it’s better to install a local version in much the same way you did with the instructions given for MySQL above — it will make shuffling databases around a lot easier when you need to do upgrades). Otherwise make sure everything else is checked.
  • Select an install folder. My folder setup looks something like /alfresco/412. Like I said, I find that I need to install a few different versions. This makes it easy to manage and find.
  • JDBC URL for MySQL should look like: jdbc:mysql://localhost/<database name>?useUnicode=yes&characterEncoding=UTF-8
  • JDBC Driver for MySQL should be org.gjt.mm.mysql.Driver
  • Don’t change the Tomcat configs unless you know what you’re doing and have a good reason to change them.
  • The rest of it keep at default but do change them if you believe you need to do otherwise.

This will install Alfresco from a basic standpoint. No tables will be created yet. After the installation is done, do a Google search for MySQL jdbc driver (the one for PostgreSQL will already be provided). My jdbc driver looks something like:

mysql-connector-java-5.1.17-bin.jar

Make sure you put a copy of this in <alfresco_install>/tomcat/lib.

If you have an enterprise license, make sure you put that license in <alfresco_install>/tomcat/shared/classes/alfresco/extension/license. Note that you will have to create the license sub-directory in that path.

After all this, you’re ready to get started. For a startup I recommend you doing this:

# <alfresco_install>/alfresco.sh start

After a few seconds after startup it may be a good idea to watch the log:

# tail -f <alfresco_install>/alfresco.log

Alfresco should now install without any errors except for a Solr one that will look like:

ERROR [org.quartz.core.JobRunShell] Job DEFAULT.org.springframework.scheduling.quartz.MethodInvokingJobDetailFactoryBean#215b011c threw an unhandled Exception:
org.springframework.scheduling.quartz.JobMethodInvocationFailedException: Invocation of method 'run' on target class [class org.alfresco.module.org_alfresco_module_wcmquickstart.jobs.PublishQueueProcessor] failed; nested exception is org.alfresco.error.AlfrescoRuntimeException: 11220001 SOLR queries can not be executed while the repository is bootstrapping

This simply says that Alfresco can’t query Solr while Alfresco is bootstrapping. Once you’ve seen an entry like this one in alfresco.log, the install should be near the end:

INFO [org.springframework.extensions.webscripts.DeclarativeRegistry] Registered 525 Web Scripts (+0 failed), 809 URLs

… it’s usually ok to start up a web browser and aim it at http://<hostname>:8080/share. You can then log in with your admin username and password and have a look around.

A tip for Enterprise users: I would recommend copying the original alfresco.log file to another location or renaming it to something like alfresco.log.installed in case you need it to give to support for a look in case something goes wrong.

Hopefully this is helpful for someone who is an Alfresco novice. It also may help to have a look at docs.alfresco.com for help and guidance on the product. If you’re an Enterprise customer, remember it’s easy to get help. Simply go to http://support.alfresco.com and log a ticket. If you’re a Community user, there is http://forums.alfresco.com and even #alfresco on freenode.net if you’re into IRC. If you run into errors, it’s best to work from the top down in alfresco.log and solve them as you go. For an install like this though, it should be easy to solve almost all of them.

Cheers! — H.S.