Upgrading

Use this information for upgrading from a version of Alfresco Content Services to a later version, for applying a Service Pack, or for upgrading the search subsystem.

Before performing an upgrade or applying a Service Pack, make sure you check the recommended upgrade path and the prerequisites checklist. As a part of upgrade, you need to validate and test to ensure that Alfresco upgrade was successful.

For upgrading from a previous version of Alfresco Content Services to a later version, see Upgrading Alfresco Content Services [1].

Alfresco Content Services upgrade paths

When you upgrade Alfresco Content Services, it is recommended that you follow a structured upgrade path between versions.

The following diagram shows the upgrade paths for major versions:

The upgrade path recommendations are:

Direct upgrades to Alfresco Content Services 6.2 are supported from only 5.1.x and later, with the latest Service Pack applied.
Alfresco Content Services 6.2 introduces changes that require new releases of all modules. To upgrade to 6.2, you also need to update any of the module artifacts to which you are entitled. See Supported Platforms [8] for more details on the associated versions.
You must upgrade to Alfresco Search Services 1.4 before upgrading the repository to 6.2. See Upgrading Search Services [9] for more information.
- Upgrades from Alfresco Content Services 5.2 must first upgrade from Solr 4 to Search Services, and then upgrade to 6.2.
- Upgrades from Alfresco 5.1 need to first stop at 5.2 to upgrade search to Search Services, and then upgrade to 6.2.
See Upgrading from Alfresco Community Edition [10] for guidance on upgrades from Alfresco Community Edition.

Note: If you are upgrading from an earlier release that is not shown on this diagram, contact Alfresco Support for assistance.

Upgrading from Alfresco Community Edition

Any GA (General Availability) release of Alfresco Community Edition can be upgraded to the latest version of Alfresco Content Services that includes the same repository version family.

The following table shows the upgrade path for major versions:

From Community	To Enterprise
Alfresco Community Edition 201806 GA	Alfresco Content Services 6.0.0
Alfresco Community Edition 201901 GA	Alfresco Content Services 6.1.0
Alfresco Community Edition 201911 GA	Alfresco Content Services 6.2.0

Please contact Alfresco Support for upgrade advice that's specific to your environment.

Note: When migrating from Community to Enterprise it is advisable to validate the Community source version to Enterprise target version that you're planning, and whether that path has been tested, or if an alternative path is advised. In some cases, the latest version of Community may supersede the current Enterprise version, and may require that you wait until the next Enterprise version of the service pack line is available.

You can then follow the upgrade path to Alfresco Content Services to upgrade to the most current release. See Alfresco Content Services upgrade paths [12] for more information.

Upgrading Alfresco Content Services

Use this procedure to upgrade from a previous version of Alfresco Content Services using the distribution zip. The process involves a new installation of the Alfresco Content Services binaries and configuration, and an in-place upgrade of a copy of the repository.

In-place upgrade of the binaries and configuration is not recommended. Creating a new installation ensures that if anything goes wrong during the upgrade, the original (not upgraded) system is still intact and available for immediate restart.

These steps assume that you have an existing Alfresco Content Services installation (alfresco-v.1) with the following settings:

File Name	Properties
alfresco-global.properties	dir.root=/alfresco-v.1/alf_data db.url=url<v.1>
solrcore.properties	data.dir.root=/alfresco-v.1/solr/myindexes

Install the new version of Alfresco Content Services using the distribution zip.
1. Shut down your existing instance.
2. Back up your existing repository (alfresco-v.1) and the database. See Backing up and restoring the repository [13].
  
  Note: Back up any configuration overrides from the <extension> directory.
3. Install the new version (alfresco-v.2) into a different directory from the existing installation.
  For example, the new Alfresco installation will have the following settings:
```
In alfresco-global.properties:
dir.root=/alfresco-v.2/alf_data
db.url=url<v.2>

In solrcore.properties:
data.dir.root:/alfresco-v.2/solr/myindexes
```
Validate the new 6.2 installation to check that it is working correctly.
1. Configure the new installation with a new repository and database (not the existing one).
2. Start the server [14] and validate that the system works correctly.
For more information, see Validating the upgrade [15].
Apply all customizations to the new 6.2 installation.
1. Stop [16] the server.
2. Remove [17] any unwanted applications.
3. Modify [18] applications.
4. Install the required AMP files. See Installing an Alfresco Module Package [19].
5. Do not copy the files. Copy only the override settings so that you will not overwrite the new extension files in the upgraded version.
6. Start [14] the Alfresco server.
  Monitor the startup log messages for information on the status of the upgrade. If any issue(s) occur in the logs during startup, you need to rollback the whole repository to fix the issue(s) and then try again.
7. Fully test [20] the working and configuration of your customizations.
8. Stop [16] the server.
Restore production data.
1. Remove all the files and directories under the contentstore directory of the new installation. Also, delete the database.
2. Delete the files in the two Solr alfrescoModels directories, and the indexes in the two directories (solr/workspace/ and solr/archive/) of the new installation.
3. Restore the backup of the indexes, contentstore directory, files, and database from your previous installation into the new installation. See Restoring production data [21].
4. Start [14] the server.
  If any issue(s) occur in the logs during startup, you need to rollback the whole repository to fix the issue(s) and then try again.
If you are happy with the upgraded system, remove the old installation and repository.
[Optional] Perform this additional step only if you have configured multi-tenancy and are upgrading.
If upgrading to the latest version, your existing MT sample extension files are no longer relevant and must be deleted. It is also recommended that you backup your existing MT files.
1. Take a backup of the following three existing MT extension files and delete them from the existing MT extension directory:
  - alfresco/extension/mt/mt-context.xml to alfresco/extension/mt/mt-context.xml
  - alfresco/extension/mt/mt-admin-context.xml to alfresco/extension/mt/mt-admin-context.xml
  - alfresco/extension/mt/mt-contentstore-context.xml to alfresco/extension/mt/mt-contentstore-context.xml
[Optional] Perform this step if you are working in a clustered environment:
1. Shut down all nodes in the cluster.
2. Perform steps 1 to 5 on each additional node in turn, ensuring that each node starts fully before restarting the next one.
  You need to copy the database once only as it is upgraded by the first node that is upgraded. The other nodes detect it has been upgraded and skip the database upgrade step.
  
  CAUTION:
  In a clustered environment, when the cloned nodes are restarted with a cluster license, the nodes may try to join the existing production cluster and point to a cloned database instead of the production cluster database. This can lead to corrupted data.
  Cause: It occurs because the cloned node contains the cluster id from production and tries to join that cluster.
  
  Solution: To avoid the problem you should ensure any cloned nodes required for upgrade testing are network isolated from the production nodes.

Validating an upgrade

Once you have upgraded, follow these steps to validate the new installation.

Restart the Alfresco Content Services server.
The configuration overrides ensure the server immediately directs data to the appropriate locations.
Monitor the startup log messages for information on the status of the upgrade.
Validate the new installation using a blank repository.
Configure the new installation with a new repository (not the existing one).
Verify the database connection details and data folder locations are set according to the environment in which the server is running.
Start Alfresco Content Services and validate the system works correctly.
Shut down Alfresco Content Services.
When you are certain the new installation is thoroughly validated, remove the old installation and repository.

Testing an upgrade

Testing an upgrade checks that Alfresco Content Services is successfully upgraded and is working as expected after the upgrade.

Test and familiarize after upgrading

You have successfully upgraded. Now test that the core features that you intend to use work as expected.

Here are some of the tips to help you familiarize yourself.

Note: We recommend that you create one or two test sites for testing purpose and put all your test data in those sites. After finishing the tests, you can delete the test sites in order to clear your database.

Check if the roles users had in the previous version are still valid in the new upgraded version.
Check if your data or document in the previous version are available in the new upgraded version.

Test the Alfresco Content Services server after customizing an upgrade

There are a number of tests that you can perform after customizing an upgrade.

Make sure that the server is up and running.
Make sure that the errors in the alfresco.log file. are checked and understood.

Test and familiarize after upgrading and configuring

You have successfully upgraded and configured Alfresco Content Services. Now make sure that the features and customizations you have added are operational.

Here are some of the tips to help you test your customizations.

Check if the users or groups created previously, still exist.
Check if all the dashboards created previously, still exist.
Check if the folders in the document library that were created prior to the upgrade, still exist.

Test and familiarize after upgrading in a cluster

You have successfully upgraded and configured Alfresco Content Services in a distributed/clustered environment. Now make sure that the features and customizations you have added are operational.

Here are some of the tips to help you test your customizations.

Check that various components are communicating with each other.
For a clustered upgrade, check if one node is down, check if the request is forwarded to the next available node.

Test and familiarize after upgrading and configuring in a cluster

You have successfully upgraded and configured Alfresco Content Services in a distributed/clustered environment. Now make sure that the features and customizations you have added are operational.

Here are some of the tips to help you test your customizations.

Check if the users or groups created previously, still exist.
Check if all the dashboards created previously, still exist.
Check if the folders in the document library that were created prior to the upgrade, still exist.
Check if clustering is working properly by running the cluster validation tool [23] in the Admin Console.

Restoring production data

Use this information to restore production data.

The dir.root directory is defined in the alfresco-global.properties file. By default, this directory is named alf_data and is located within the directory where Alfresco Content Services is installed.

Restore the backup into the new repository.
If Solr is being used, put the following directories from your backup to the dir.root directory on a new instance.
- contentstore directory
- solr/workspace directory (optional)
- solr/archive directory (optional)
- contentstore.deleted directory
Some of the above mentioned directories are optional. This is because if the indexes are not copied over from the previous installation, Solr will query Alfresco Content Services and rebuild its index in background after start up. It may take more time to rebuild indexes on large repositories. Applications will be accessible during the reindex process.
Point the new deployment to the old database using the db.* properties in the alfresco-global.properties file by providing the JDBC URL, database name, log in credentials, and any other relevant configuration options.
Remember to specify the relevant JDBC driver into your application server's classpath.