Upgrading to AEM 6.0

In this section we cover upgrading an AEM 5.x installation to AEM 6.0:

For more information about upgrading and about the new Oak repository see the following subpages:

Upgrade overview

There are two distinct steps to doing a full upgrade:

  1. In-Place Upgrade: Drop in the new jar file in place of the original one in your <aem-install> directory, right next to your existing crx-quickstart directory) and launch it. This upgrades the system, but leaves the existing CRX 2 repository as-is.
  2. Migrating the Repository to Oak: Once the in place upgrade is complete, you can optionally migrate the existing CRX 2 repository to the new Jackrabbit Oak-based CRX 3 repository. 

In-Place Upgrade

Even though the upgrade process has been designed to be as simple as possible, any upgrade of a production environment is a significant task. For this reason, we recommend that you invest time in planning your upgrade throroughly. For guidance on this, see Planning Your Upgrade.

  1. Enable INFO logging for the error and upgrade logs. This can be done by:

     

    1. Going to AEM Configuration Manager located at http://localhost:4502/system/console/configMgr
    2. Pressing the + button under Apache Sling Logging Logger Configuration
    3. Creating new factory configuration that will log INFO events for upgrade.log and error.log. For more info, see Logging.
  2. Run the following maintenance tasks:

    This step is not mandatory but is recommended in order to ensure repository consistency before the upgrade.

  3. Remove the Geometrixx sample packages and users. For a complete list of all the Geometrixx packages, see Removing the Geometrixx Sites.

    In case this step is carried out, the error.log file will show messages related to the deleted Geometrixx users. These messages have no impact on the upgrade and should be ignored.

  4. Shutdown the AEM 5 instance.

  5. Replace the quickstart with the AEM 6 jar.

  6. Run the jar and wait for the upgrade to finish.

  7. Check that the upgrade was successful by confirming that:

    • The upgrade.log shows that the process was finished:

    *INFO* [FelixStartLevel] com.adobe.cq.upgradesexecutor.Activator UPGRADE FINISHED: 6 CodeUpgradeTasks executed (out of 6), total time about 32 seconds

    • error.log shows an "FrameworkEvent STARTED" event:

    *INFO* [FelixDispatchQueue] org.apache.felix.framework FrameworkEvent STARTED

    • Check that the value for System Start Level is 30 in the System Information console. The console can be reached at http://localhost:4502/system/console/vmstat
    • All the bundles and workflows are in place.

Hinweis

If you plan on running AEM 6 with a CRX 2 backend, you can simply run the jar at this point. However, note that for all upgrades from versions up to and including AEM 5.5 this needs to be explicitly stated via the "crx2" runmode option when the AEM 6.0 jar is first started. To do this, run the quickstart with the following command:

java -jar aem-quickstart.jar -r crx2

If the runmode is not specified, the AEM 6.0 instance will start with a new CRX 3 repository instead of the existing CRX 2 one.

Migrating the repository to OAK

Since AEM 6.0, the backend has moved to OAK in an effort to enhance scalability and performance of the content repository. For more info on the architectural concepts of Apache OAK, see Introduction to OAK.

Adobe provides a tool that can be used to migrate the repository to the new OAK implementation. It can be downloaded here:

* crx2oak-1.0.0.zip
CRX2OAK repository migration tool

There are two options for the storage backend used by Oak:

  • TarMK: A microkernel that uses the Tar persistence system for storage.
  • MongoMK: A microkernel that uses MongoDB for storage.

Migration Prerequistes

  • Minimum Required Java version: The migration tool only works with Java versions 7 and up.
  • Upgraded Instance: Before migrating, make sure you have performed an in-place upgrade to AEM 6.0 by following the procedure described above.

Migrating to TarMK

  1. Place the migration tool in the <aem-install> folder and run it with the following parameters:

    java -jar crx2oak.jar [source repository] [target repository]
            

    Code-Beispiele dienen lediglich zu Illustrationszwecken.

    Where:

    • The source is the CRX repository that needs to be migrated. If you are running it from within the <aem-install> folder, this would be crx-quickstart/repository.
    • The target is the resulting TarMK repository to be created.

    During the migration, the source repository should not be accessed by another client. The  configuration is read from the repository.xml file within the source directory.

    The target repository is the filesystem path to the new TarMK repository folder which will be created automatically if it does not exist.

    The command should look like this:

    java -jar crx2oak.jar crx-quickstart/repository oak-repository
            

    Code-Beispiele dienen lediglich zu Illustrationszwecken.

    In this example, the migrated TarMK repository will be created in a folder called oak-repository.

  2. After the migration has finished, backup the AEM 5 data store and the newly created AEM 6 node store by copying them outside the installation folder. The folders that need to be copied are:

    1. crx-quickstart/repository/repository/datastore
    2. oak-repository/segmentstore
  3. Delete the entire crx-quickstart folder.

  4. Re-create the crx-quickstart folder with additional configuration for setting the data store and node store for AEM 6:

    • Create the crx-quickstart/install folder.
    • In the install folder, create a file called org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.cfg
    • Edit the file and add these configuration options:

    path=./crx-quickstart/repository/datastore

    minRecordLength=4096

    • In the same folder, create a file called org.apache.jackrabbit.oak.plugins.segment.SegmentNodeStoreService.cfg
    • Add the following configuration option:

    customBlobStore=true

     

    Hinweis

    The above configuration example is valid for configuring AEM 6 with a File Data Store. For more info on other data store options and configurations, see Configuring Node Stores and Data Stores in AEM 6.

  5. Run the quickstart jar and stop it again after it has started.

  6. Move the data store and segment store to the new installation. In order to do this, you need to:

    1. Delete all the contents of crx-quickstart/repository
    2. Copy the datastore and segmentstore folders to crx-quickstart/repository
  7. Start AEM.

Migrating to MongoDB

  1. Make sure that MongoDB is installed and an instance of mongod is running. For more info, see Installing MongoDB.

  2. Copy the AEM 6 jar into a separate folder.

  3. In the new location, create the Data Store and Node Store configuration needed for the MongoDB migration:

    • Create the crx-quickstart/install folder.
    • In the install folder, create a file called org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.cfg
    • Edit the file and add these configuration options:

            path=./crx-quickstart/repository/datastore

            minRecordLength=4096

    • In the same folder, create a file called org.apache.jackrabbit.oak.plugins.document.DocumentNodeStoreService.cfg
    • Add the following configuration option:

            customBlobStore=true

  4. Start the AEM 6 jar with a MongoMK backend by running:

    java -jar cq-quickstart-6.0.0.jar -r crx3,crx3mongo -Doak.mongo.uri=mongodb://remoteserver:27017/aem-author
            

    Code-Beispiele dienen lediglich zu Illustrationszwecken.

    Where:

    • -r is the backend runmode. In this example, it will start with Mongo support.
    • -Doak.mongo.uri is used to specify the location of the Mongo server and the database name.

     

    Hinweis

    Both AEM and the repository migration tool use a MongoDB connection string to specify the location, the port and the name of the database that needs to be used. For more information on the synthax, see Connection String URI Format.

  5. Wait for the instance to start up, and then shut it down. After it has been shut down, prepare the migration by:

    • Deleting the contents of the crx-quickstart/repository folder
    • Deleting the aem-author Mongo database. This can be done from the Mongo shell, by running:

             use aem-author

             db.dropDatabase()

    • Moving the crx-quickstart/repository/repository/datastore folder from the AEM 5 installation to the AEM 6 folder.
  6. Run the crx2oak upgrade tool and wait for the process to complete:

    java -jar crx2oak.jar [source CRX 2 repository] mongodb://remoteserver:27017/aem-author
            

    Code-Beispiele dienen lediglich zu Illustrationszwecken.

  7. Restart AEM.

  8. Test your new installation.

Achtung

Any custom repository configurations (such as LDAP integration) will have to be recreated for OAK after the upgrade.

Using the helper script to migrate the repository

A helper script is also provided in the quickstart package in order to facilitate the use of the migration tool. It can be found in the archive provided above under the name crx2oak.sh

  • Usage for migrating to TarMK:

crx2oak.sh [repository location]

The repository location is the file system path to the CRX2 repository that needs to be converted to Oak.

Thus, a correct form to invoke the script would be:

crx2oak.sh /srv/cq/crx-quickstart/repository

  • Usage for migrating to MongoMK:

crx2oak.sh -m [location of Mongo database]

The location of the Mongo database must be specified in Connection String URI format.

Again, a correct way to invoke the script for a MongoMK migration is:

crx2oak.sh -m mongodb://serverhost:27017/aem-author

 

The script can be run with several optional parameters:

-s Starts a CQ instance after the migration.
-j Specifies a custom crx2oak.jar to use for the migration.
-q Specifies a custon quickstart.jar to use when building the initial crx-quickstart folder.
-p The port to use for CQ startup detection. Useful for instance when the quickstart is configured to start on a different port due to its name, e.g. cq-author-8080.jar.
-i Backs up the previous crx-quickstart folder by renaming it to crx2-quickstart and replaces it with the newly generated instance.
-l Indicates from where to copy a license.properties file into the current working directory in order to automatically start the instance used for migration; if a license.properties file exists in the current folder this option is not needed.
-h Shows usage information for the script.

Hinweis

The script will not work for setups with custom Data Store configurations. For such cases, please run crx2oak.jar manually, as described above.

Troubleshooting issues after the upgrade

  • Issues with starting and shutting down AEM after the upgrade: After upgrading to the CRX 3 backend, AEM sometimes fails to start or shut down properly on systems with Java 6 installed. To work around this, add the following parameters to the JVM when starting AEM:

         -XX:+UnlockDiagnosticVMOptions -XX:+UnsyncloadClass

  • Error messages: The following error messages will appear in the error.log file after the upgrade and can be safely ignored:

 

*ERROR* [OsgiInstallerImpl] org.apache.jackrabbit.vault.fs.impl.io.DocViewSAXImporter Error while applying access control content. javax.jcr.security.AccessControlException: Principal operators does not exist.
        

Code-Beispiele dienen lediglich zu Illustrationszwecken.

*ERROR* [OsgiInstallerImpl] com.adobe.granite.installer.factory.packages.impl.PackageTransformer Error while processing uninstall task.
com.day.jcr.vault.packaging.PackageException: org.apache.jackrabbit.vault.packaging.PackageException: Unable to uninstall package. No snapshot present.
        

Code-Beispiele dienen lediglich zu Illustrationszwecken.

​