Monthly Archives: February 2013

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.