In this article by Vandana Pal, author of Alfresco for Administrators, we will go deeper into the concepts of Alfresco. Upgrading Alfresco is a multistep process. Based on the customizations made and the new features available in Alfresco, you need to first decide the target version of Alfresco. On the basis of the currently installed version, there could be different paths to upgrade alfresco.

Upgrading Alfresco involves moving all the content (database, content store, and indexes) to the new version of it, and if there is any feature customization to made in Alfresco, it needs to be upgraded in order to make it compatible with new system. The final step involves validating the entire system and its data.

Now, let's go through all of the steps in detail.

(For more resources related to this topic, see here.)

Choosing an upgrade path

Alfresco's major versions include 2.x, 3.x, 4.x, and 5.0. 2.x is the oldest version, and 5.0 is the latest version available in Alfresco. Recently, Alfresco has stopped providing support for any version that's older than 4.x.

In general standard paths if your current Alfresco system is version 2.x, then you cannot directly upgrade to 4.x or 5.0 as there are major functionality changes. Alfresco recommends that you go to an intermediate stable version before upgrading to the final version.

Here are few samples to upgrade the different versions of Alfresco Enterprise:

Consider a situation where the current version is 2.x and the target version is 5.0. Now, here, you cannot directly upgrade Alfresco to v5.0. First, Alfresco needs to be upgraded to the stable version of 3.x, then to 4.x, and finally you can upgrade to 5.0.

Consider a situation where the current version is 3.x and the target version is 5.0. Here, again, you need to upgrade to 4.x first before you can upgrade to 5.0. As there are major changes in the database, index changes are to new Alfresco v5.0.

Before deciding on any particular path, it is very important to contact Alfresco's support to get information on the complete upgrade path.

Also, before you choose the target version to be upgraded, there are few important points that need to be considered:

Develop a proper understanding of the new features and changes that available in the latest version of Alfresco. For example, Alfresco explorer is deprecated in v.5.0, and if your end users use explorer to very large extent, then you might want to upgrade to the latest stable 4.x version.

Impact analysis of customizations that are made in the current version of Alfresco.

Decide your timeline for upgrade process.

Standard upgrade guidelines

Any upgrade that has standard guidelines needs to followed apart from any version you are currently upgrading. Let's go through each of the steps in details.

Preparing a checklist

Analyzing the current system and new target upgraded system is very important for any upgrade and planning purposes. The first step to do this should be to get details about the current infrastructure, such as the clustered environment, amount of customizations that have been made, important features that are used, data size, and so on.

The second step involves deciding which upgraded target version to use and understanding all the features that your current application has. Once you have these details, decide on the target version where Alfresco will be upgraded and identify all the software requirements and environment details from the Alfresco support stack. For example, when you upgrade to the latest version of Alfresco, you might have to change the JDK version, the application server needs to be upgraded, the system stack might need to changed, the Solr version may need to be upgraded, and so on.

Prepare a checklist of the new system requirements and the validation process.

Setting up and validating of new environment

Install the new Alfresco version on a separate sever from the production system. Validate whether the installation is performed correctly and has been documented.

If you have a distributed clustered environment, enable clustering and validate whether the application is working as expected. Don't use the production data yet, validate it with the blank database and content store first.

If your current Alfresco system has any code customizations or extensions deployed, make sure that all the code is compatible with the new version. Also, make sure that any configuration changes executed in the old system are also configured properly in the new Alfresco server.

Deploy all the customized code and configurations in the new Alfresco server and perform a regression test. Ensure that your existing application works properly with the new version of Alfresco. All these validations are very important prior to the upgrade.

The data upgrade process

Once you have validated whether the new Alfresco server is installed and configured properly, it is time to actually upgrade the data. Here are the steps that need to be performed to do this:

Back up the data you've collected from production, which will be used for the upgrade. You need to backup from the database, Content store repository, and indexes. This will be your snapshot of data that will then be upgraded to the latest version of Alfresco. Refer to following properties in their respective files to locate the data to be backed up:
```
dir.root=<Cotnent store location. Property configured in alfresco-global.properties>

db.url =<Database connection details. Property configured in alfresco-global.properties>

data.dir.root=<Solr Index location. Property configured in solrcore.properties for both workspace and archive indexes>

dir.indexes=<Lucene index path. Property configured in alfresco-global.properties>
```
Restore the database content-store and indexes on separate server. If we keep upgraded environment separate then production server can still be used and will not be impacted.

As discussed in the earlier steps on installation and validation, once the new version of the Alfresco server is completely tested with customized code and configurations, make sure that the server is stopped.

Configure the following properties in the alfresco-global.properties file with regard to the restored production database and content store that were discussed in step 2. Make sure that all your test data is wiped out in the new installation:
```
dir.root=<Restored content store location>

db.username=<Set correct alfresco database username>

db.password=<Alfresco database password>

db.name=<Database name>

db.url=<Full Database URL>
```

Point the Solr indexes to the newly restored indexes. Remove all the test data and model files that were created in the new installation. Configure the following properties for the Solr indexes in the alfresco-global.properties file. Also, make sure that all the old Solr configurations are also copied to the new instance:
```
   index.subsystem.name= <Set proper subsystem name>
```

Configure the following property in solrcore.properties to point to the new indexes for both the workspace and archive:
```
    data.dir.root=<Set the full path for the indexes>
```

If you are upgrading to Alfresco 5.0, there are few additional steps needed to upgrade the Solr version as Alfresco v5.0 uses Solr4. We will cover these details in the latter part of the article.

If you are upgrading from Alfresco prior to version 4.x, make sure that the following jbpm properties are set to true to enable the Jbpm engine. As seen in the latest version of Alfresco, the workflow engine is now changed to activiti, and then it is enabled by default:
```
    system.workflow.engine.jbpm.enabled=true
```

Start the Alfresco server and monitor the logs. These will provide you with details about the upgrade process. If you have a clustered environment, you can configure all the nodes with the same code and configurations. Start only one node. Later on, you can restart all the other nodes, and all of them will have upgraded data.

Once the upgrade is finished and the server starts properly, validate the upgraded server.

If the server is validated properly and all goes well, you can switch over to the new upgraded server and the old production server can be removed.

The Solr upgrade process for Alfresco 5

Alfresco supports only Solr4. It doesn't support Lucene or the older versions of Solr anymore. To completely the upgrade to Alfresco, a system has to recalculate all the indexes with the latest versions. In case the current system uses Lucene Indexes, the system needs to be upgraded to Solr before we can upgrade it to Solr4.

Let's go through the steps to upgrade Solr:

If the current repository uses Lucene indexes and is on an older version prior to Alfresco 4.x or on Alfresco 4.x, the first step you need to perform is to upgrade the system to Alfresco 4.x. Set up the new Solr1 and configure it to track all the recalculated indexes. For larger repositories, this can be long process.

Once your indexes are read on Solr in Alfresco 4.x the system is ready to be upgraded to Alfresco.

When you upgrade Alfresco 4.x to Alfresco, you will still be able to use the old Solr version and configure Sol4 to start tracking and recalculating the indexes.

During the upgrade process, copy all the Solr indexes from Alfresco 4 to the new installation of Alfresco 5 as discussed in the upgrade process. Make sure that Alfresco 5 is running properly with the older version of Solr.

Once the upgrade is finished, set up the new Solr4 instance on a separate server. It is not recommended that you have both the Solr servers on the same machine as the indexing process will consume a lot of memory and CPU resources.

Verify in the Alfresco admin console whether the search subsystem is still set to an older version of Solr.

Now, configure solrcore.properties located in workspace-SpacesStore/conf and archive-SpacesStore/conf in the new Solr4 installation to point it to the new Alfresco server and start tracking the indexes:

data.dir.root=<Index Directory location>

enable.alfresco.tracking=<Set to true to start the tracking>

alfresco.host=<Alfresco Server Host>

alfresco.port=<Alfresco Server Port>

alfresco.port.ssl=<Alfresco Server SSL Port>

alfresco.cron=<Cron expression to tracking Alfresco index>

You can monitor the indexing status of Solr4 using JMX or the monitor service of Solr at http://<Solr Server Host and Port>/solr4/admin/cores?action=SUMMARY&wt=xml.

Once Solr4 has indexed the complete repository and its report summary count matches the node count in the repository, switch the search subsystem from Solr to Solr4 using the Afresco Admin Console or by configuring the following property in the alfresco-global.properties file. Stop the older Solr version like this:
```
index.subsystem.name=solr4

dir.keystore=<New solr certificate location>

solr.port.ssl=<Solr SSL port>
```

Summary

In this article, we took a look at the different upgrading process for Alfresco in detail. We also talked about choosing an upgrade path, setting up a new environment, and the validation of a new environment.