Upgrading Alfresco

The Situation

I am using Alfresco as a personal document archiving system for all my personal things. Everything that gets (snail-)mailed to me get scanned with my document scanner, which does OCR, page cutting, rotating and optimizing, and then uploaded to alfresco with pretty much one click. Well, one button (scanner), then I need to supply a file-name and finally the document is added via drag&drop to Alfresco. This system works great, even my wife uses it (frequently). The only thing that’s kept on paper are important documents like insurance policies and things like that.

As this is obviously a critical piece of our “digital lives”, it needs to be stable and somewhat up-to-date. I opt-out of going after every update and I seem to upgrade Alfresco only once a year, which works well for me. My Alfresco installation in shielded from the internet, that is, it’s on my private (non-internet connected) server, so bugs and exploits are of no concern here.

Now installing and running Alfresco is straightforward, consisting out of downloading, running and doing the setup and configuration wizard, period. But as some point, you do want to upgrade it. And this is where the fun starts.

Upgrading “their way”

There are so many instructions on how to upgrade Alfresco. They all basically boil down to:

  1. Backup all your data
  2. Delete your Installation
  3. Reinstall newer Version of Alfresco
  4. Restore your data

which seems odd for any piece of software in the year 2015, but who are we to judge free stuff. The problem is, or was at least for me, the lack of good information. Either the sites are obsoleted (for old Versions) or they refused to “hold my hand” during critical phases. I am not talking about “Backing up your data” – actually I am. Turns out even the real Alresco documentation says

[…] back up your database and content store (alf_data directory).

(s: http://docs.alfresco.com/4.0/tasks/upgrade-process.html)

Backing up a directory is easy, but what about the database? It refers to “your used database“, mh. I am using their own supplied embedded postgresql database, so what about that? No answer here.

Upgrading “my way”

Long story short. To Upgrade Alfresco 4.x to 5.x do this: First, my Alfresco is installed in “/docstore”, so replace all occurrences of “/docstore” with your Alfresco root directory. The following steps might look scare, but fear not.

First, get your postgresql login information that Alfresco uses:

egrep -i '(db.password|db.username)' /docstore/tomcat/shared/classes/alfresco-global.properties

After we got that, we stop Alfresco, but we keep the postgresql alive, so we can dump:

cd /docstore && ./alfresco.sh stop && ./alfresco start postgresql 

Now we need to dump the postgresql database, when asked for a password, enter the db.password from above. Be sure to use the same Username (-U) as the db.username:

cd /docstore/postgresql/bin/ && ./pg_dump alfresco -U alfresco > /root/alfresco.sql

Now, backup all the documents:

cd /docstore && tar -cf /root/alfresco.tar alf_data/contentstore alf_data/solr/workspace alf_data/solr/archive 

The scary part: Delete all of Alfresco, don’t forget the init.d script:

/etc/init.d/alfresco stop 
rm /etc/init.d/alfresco
cd /docstore && rm -rf * && sync
 … and reinstall the new version (be sure to have downloaded it, duh):
 Installed? Good, now we need to stop Alfresco again, but start the postgresql:
cd /docstore && ./alfresco stop ; ./alfresco postgresql start
Now we need to wipe the alfresco database in postgresql, don’t worry: We just need the namespace to be able to reimport it in the next step. First, let’s note the “new” database connection credentials:
egrep -i '(db.password|db.username)' /docstore/tomcat/shared/classes/alfresco-global.properties

with that, we can remove the namespace (be sure to supply the correct username/passwords):

cd /docstore/postgresql/bin
./psql -h localhost -U postgres -d postgres
  DROP DATABASE alfresco;
  CREATE DATABASE alfresco WITH owner = alfresco;
exit psql (ctrl+d) and we are good to import the dump, using the “new” credentials:
cd /docstore/postgresql/bin
./psql -U alfresco alfresco < /root/alfresco.sql
And restore your documents:
cd /docstore/alf_data
rm -rf contentstore solr4/*
tar -xf /root/alfresco.tar
In case of 4.x to 5.x Upgrade the solr directory got renamed, fix it:
mv solr solr4
You are nearly done, start Alfresco:
cd /docstore
./alfresco stop postgresql
./alfresco start
Yes, we stop postgresql first, as it is already running. It has new data, so a reload does not hurt. There is no need to replace the login information in the quote file


as the root login information is unchanged.

Last step, clean up:
rm /root/alfresco.tar  /root/alfresco.sql
If you had any troubles, don’t hesitate to drop me a line.


Touched base with Linux back in 1995, got hooked up on it ever since. I am using Linux for both private and office for two decades. Working as a System Administrator at a medium sized hosting company I get in touch with all kinds of trouble. All of which can be solved with Linux. In my blog I am sharing solutions to problems that I had to search for myself in hope that someone else out there might find them useful.