Productively running multiple versions of Alfresco

How do you juggle multiple versions of Alfresco on your local machine? At any given time, I’ve got at least three versions running: The latest Enterprise release, the Enterprise head, and the Community head. If one or more active Optaros clients aren’t yet on the latest release, those older releases are running as well.

There’s always more than one way to skin a cat but here’s how I handle this problem. First, I want to use a single Tomcat instance, but I don’t want all of my Alfresco versions running at the same time. Second, I want to use the same MySQL instance running with version-specific databases to keep them separate. Third, I want separate, version-specific data directories.

The solution is to name your databases and all of your version specific directories with a naming convention, and then use shell scripts to delete and create soft links in the appropriate locations that point to the version specific directories. (If you are running Windows you can do symbolic links too–they are called Junctions).

In an Alfresco install there are four directories that you need to address:

  • The data directory
  • The web application directory
  • The shared extension directory
  • The virtualization server directory

Decide on a naming convention. For my databases, I use alfrescoXXn where XX is the version number and n is the network abbreviation (“c” for community, “e” for enterprise, etc.). So my database for 2.2 Enterprise would be alfresco22e. For directories, I use alfresco-X.X-nnnn. So, for example, the directories for Alfresco 2.2 Enterprise would be:

  • /home/jpotts/alfresco/alfresco-2.2-enterprise/data
  • /home/jpotts/alfresco/alfresco-2.2-enterprise/webapp
  • /home/jpotts/alfresco/alfresco-2.2-enterprise/extension
  • /home/jpotts/alfresco/alfresco-2.2-enterprise/virtual

When I want to switch between versions, I just call a shell script with the version as the argument. It takes care of deleting the existing links and creating the new:

echo Switching to $1...
echo Switching webapp...
rm $TOMCAT_HOME/webapps/alfresco
ln -s /home/jpotts/alfresco/alfresco-$1/webapp $TOMCAT_HOME/webapps/alfresco
echo Switching extension directory...
rm $TOMCAT_HOME/shared/classes/alfresco/extension
ln -s /home/jpotts/alfresco/alfresco-$1/extension $TOMCAT_HOME/shared/classes/alfresco/extension
echo Clearing Tomcat work directory...
rm -rf $TOMCAT_HOME/work/Catalina/localhost/alfresco
echo Clearing Tomcat temp directory...
rm -rf $TOMCAT_HOME/temp/*
echo Switching virtual tomcat directory...
rm $VIRTUAL_TOMCAT_HOME
ln -s /home/jpotts/alfresco/alfresco-$1/virtual $VIRTUAL_TOMCAT_HOME

Note that in this set up, the data directory and the Alfresco database don’t have to be dealt with directly because they are referenced by the custom-repository.properties file residing in the version-specific extension directory.

While you’re at it, why not make it easier to clear out the repository? Set up a “clean” script that cleans out your data directory and then runs the db_remove and db_setup SQL scripts. Remember that you’ll either need version specific copies of these scripts or you’ll need to modify them to accept the version-specific database as an argument.

With this setup in place, you can set up new versions, switch between versions, and start over with a clean repo quickly and easily.

19 comments

  1. anonymous says:

    Hello Jeff,
    Thanks for this very useful post. I was able to follow your post up to the extension folder. I am not clear as to what to move under virtual folder and from where. I am running Alfresco in XP and with using Junctions I was able to create “soft links” like in Unix. Thanks for exposing me with Junction concept. I am sure it is going to be very useful in future development efforts.

    Please clarify about virtual directory and its use. Thanks a bunch in advance.

    Regards,
    SKM

  2. jpotts says:

    SKM,

    That virtual directory is for the Alfresco WCM virtualization server. If you aren’t using the virtualization server you don’t need it.

    Glad you are finding junctions useful. I’m curious to know if Vista or Windows 7 supports directory aliases natively or, if not, if the junctions-add on works in those Windows versions. Maybe someone running those could comment.

    Jeff

  3. jpotts says:

    Yes, you can run multiple, independent instances of the Alfresco repository by running the Alfresco WAR on different instances of Tomcat. It’s just a matter of proper port configuration.

    For Alfresco Share, you can run multiple instances of the Alfresco Share WAR (in differently named web app contexts) within the same instance of Tomcat (and across multiple Tomcats and/or machines, if you want). You can have the instances of Share point to the same Alfresco repository or different repositories depending on what you’re trying to do.

    Then, of course, there’s clustering, in which you run multiple instances of the Alfresco WAR, usually across different machines, but have them act like one logical repository.

    Jeff

  4. jpotts says:

    No problem. You probably already knew this, but I should probably mention that if you are running multiple instances of Alfresco, in addition to Tomcat ports, you’ll also need multiple databases and content directories. You’ll specify those in the alfresco-global.properties file.

    Jeff

  5. pierlugi says:

    hi jeff

    Your Blog is much better than Alfresco Forums!!!

    I’m interested in those your words

    “For Alfresco Share, you can run multiple instances of the Alfresco Share WAR (in differently named web app contexts) within the same instance of Tomcat (and across multiple Tomcats and/or machines, if you want). You can have the instances of Share point to the same Alfresco repository or different repositories depending on what you’re trying to do.”

    Hoc can i manage to do that? I tried simply to rename share.war in newName.war but it did not work.

    Thanks in advance

  6. jpotts says:

    You should be able to run multiple Share webapps within the same tomcat without a problem. If you are having problems with that, let me know what specific problem you are having and I’ll try to help.

    You should also be able to run Share on a different Tomcat instance without a problem.

    You can run Share on a completely different machine from Alfresco, but there are some configuration changes you have to make so that Share knows the host where the repository is running. Here is some documentation on running Share on a different server: http://docs.alfresco.com/3.4/index.jsp?topic=%2Fcom.alfresco.Enterprise_3_4_0.doc%2Ftasks%2Fshare-tomcat-deploy.html

  7. pierluigi says:

    well as i said i rename the share.war in newname.war

    then i start tomcat

    localhost:8080/share work perfectly
    localhost:8080/newname gives immediately an exception

    org.springframework.web.util.NestedServletException: Request processing failed; nested exception is java.lang.Exception: java.lang.NullPointerException
    org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:659)
    org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:552)
    javax.servlet.http.HttpServlet.service(HttpServlet.java:617)
    javax.servlet.http.HttpServlet.service(HttpServlet.java:717)
    org.alfresco.web.site.servlet.MTAuthenticationFilter.doFilter(MTAuthenticationFilter.java:74)
    org.alfresco.web.site.servlet.SSOAuthenticationFilter.doFilter(SSOAuthenticationFilter.java:301)

    And how can i manage the setting in share-config-custom.xml: soes this file affect only share.war or both wars?

    Thanks in advance

  8. jpotts says:

    Try creating a “newname” directory under webapps and expanding the share.war manually, then starting up Tomcat. I just did that locally and it worked fine.

    If you put share-config-custom.xml in /WEB-INF/classes/alfresco/web-extension in your webapp instead of /shared/classes, you should be able to have a share-config-custom.xml that affects only a specific Share webapp.

    Jeff

  9. pierluigi says:

    It WORKS!

    I did choose really the worst solution to my problem!!!!

    DO NOT RENAME WAR!

    Thank you very much Jeff

  10. Nick Taitano says:

    jpotts:

    I’m a new to Alfresco and I recently purchased the Alfresco developers guide to help me understand the system.

    My question is pertaining to upgrades. We are currently using a Tomcat installation on a BSD system and we’re running Alfresco version 3.4.c and we’re hoping to upgrade to the latest version.

    In my tomcat/webapps folder I have /Alfresco and /Share. I downloaded and expanded Share 4.0b and was able to deploy the new Share instance in tomcat. So right now, I have the following:

    /alfresco – version 3.4.c
    /share – Production – version 3.4.c
    /share4b – Testing new Share

    How would I go about running multiple instances of the alfresco repository? I understand I must create a new mysql database, put the new information in the alfresco-global.properties file, specify a new alf_data directory as well.

    How will the new ‘share4b’ site know to use the new repository? I apologize if my terminology or general idea of Alfresco is summit convoluted
    but again, I’m starting from scratch and would like a better understanding of the upgrade procedures.

    I appreciate any help you can provide. Excellent site, btw.

  11. Cheers says:

    Hi Jeff,

    i created alfresco-4.0c directory in my webapps folder, i extract the share.war manually, but when write this url: http://localhost:8081/alfresco-4.0c the browser response this message:

    HTTP Status 404 – /alfresco-4.0c/

    type Status report

    message /alfresco-4.0c/

    description The requested resource (/alfresco-4.0c/) is not available.

    What’s wrong? Thanks a lot!

  12. jpotts says:

    Silverio,

    You need two WARs. The first one is alfresco.war. That contains the core repository and the Alfresco Explorer web client. The second is share.war. That contains only the Alfresco Share web client. I would extract alfresco.war into “alfresco” and share.war into “share”. If you extract alfresco.war into something different, you’ll have to do some Share configuration because it needs to communicate with the repository, and it expects the app to be called “alfresco”.

    Jeff

  13. jpotts says:

    Nick,

    You should test Share with the same version of the Alfresco repository. So if you are testing Share 4.0.b it should be against Alfresco 4.0.b.

    The safest/easiest way to run multiple instances of Alfresco is to:
    1. Create a separate alf_data directory.
    2. Create a separate database
    3. Use separate tomcat instances or at least separate web applications

    I have many different versions of Alfresco on my machine and I use a script to switch between them. This blog post talks about how that works. It was written a long time ago, but it all still applies. One big difference is that the properties file is now called alfresco-global.properties. That file is where you specify the data directory path, the database name, the database user, and the database password.

    In your case you are upgrading so you’ll want to test your upgrade first. To do this, dump the database then tar up your alf_data directory. Then create a new database and load it with the dump you created. Create a new alf_data directory for your new version and un-tar the old data directory into it. Edit alfresco-global.properties to point to the test database and alf_data directory. DOUBLE CHECK THIS. You do NOT want to start up Alfresco with the new WARs on a test server and have them inadvertently point to the production database and data directory. If everything is set appropriately, drop the new alfresco.war and share.war files into a test tomcat instance and restart. This will give you a chance to test the upgrade including any customizations or extensions you may have made. (In fact, if you have made any, there will be the obvious step of merging those with the new configuration files which may have changed since the old version).

    If everything tests out okay and you are ready to do this in production, all you have to do is shut down, merge the config and other customizations, drop in the new WARs, then restart.

    Hope this helps,

    Jeff

  14. Cheers says:

    Hi jeff,

    thanks for the reply,

    i create the folder alfresco4-0c in my webapps folder and i create alfresco folder and share folder in alfresco4-0c and extract the .war files, but i have the same error.

    What’s wrong?

    Thanks a lot

  15. jpotts says:

    You should have a webapps folder which contains “alfresco” and “share”. In my case, similar to what is explained in the blog post, I symlink the alfresco and share directories to another directory where my exploded WARs live. So here is what my $TOMCAT_HOME/webapps directory looks like:

    jpotts-alfresco-mbp:webapps jpotts$ pwd
    /opt/apache/tomcat/apache-tomcat-6.0.32/webapps
    jpotts-alfresco-mbp:webapps jpotts$ ls -la
    total 16
    drwxr-xr-x@ 9 jpotts admin 306 Feb 3 16:13 .
    drwxr-xr-x 17 jpotts admin 578 May 27 2011 ..
    drwxr-xr-x@ 13 jpotts admin 442 Sep 8 16:03 ROOT
    lrwxr-xr-x 1 jpotts admin 54 Feb 3 16:13 alfresco -> /Users/jpotts/alfresco/webapps/alfresco-3.4d-community
    drwxr-xr-x@ 45 jpotts admin 1530 Feb 2 2011 docs
    drwxr-xr-x@ 6 jpotts admin 204 Feb 2 2011 examples
    drwxr-xr-x@ 8 jpotts admin 272 Feb 2 2011 host-manager
    drwxr-xr-x@ 9 jpotts admin 306 Feb 2 2011 manager
    lrwxr-xr-x 1 jpotts admin 51 Feb 3 16:13 share -> /Users/jpotts/alfresco/webapps/share-3.4d-community

    Jeff

  16. Dan Wentworth says:

    Great thread!
    I would like to have multiple Alfresco Tomcat WebServers (dedicated resources)with Apache facing outward with a reverse proxy mod_jk acting as a gateway. This is primarily due to limitations found in MultiTenancy. Specifically CIFS. However I am having difficulty understanding how to reassign the CIFs port in Alfresco. I am currently working with a single instance with port reassignments as a proof of concept. Any help would be greatly appreciated.

Comments are closed.