Upgrading to AEM 5.6.1
Introduction
The basic procedure for upgrading to AEM 5.6.1 is straightforward: Simply stop your existing AEM nstance, replace the jar file (for standalone instances) or the war file (for application server instances) and restart.This in-place upgrade is described in the next section. It applies to the upgrade from the following version to AEM 5.6.1:
- CQ 5.2.1
- CQ 5.3
- CQ 5.4
- CQ 5.5
- AEM 5.6
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.
In Planning Upgrade:
This section provides information and guidelines for
planning and executing your upgrade to CQ 5.5; from initial preparation and
tests, through to implementation on your production environments.
As given in Image below,All steps has been mentioned to make
upgradation of CQ5.For More Information ,Go to the link in reference section of
this doc.
Known Issues for Upgrade to 5.6.1
- Deployment: A custom context path is reset to / during upgrade process. The path setting from etc/server.xml needs to be restored manually after upgrade.
- Workflow Models: References to sub-workflows in container steps are not updated and need to be adapted manually after upgrade.
- Portlet Component: Customers using the Portlet component with Portlet web apps hosted on CQSE need to switch to an Application Server WAR file deployment of CQ.
- Social Communities: Customers update from versions before 5.6 will need a migration tool which will be made available shortly on Package Share with documentation to follow on docs.day.com.
- Replication: After the upgrade is complete, replication may not function correctly until an additional restart is performed.
Inplace Upgrade from CQ 5.x and AEM 5.6
Preparation
1-Create a copy of the author and publish instances. For
example, with the CRX
backup tool.
2-Extract the backups into a testing environment.
3-In that environment, make sure that you have at least 2GB
of free disk space and sufficient privileges to perform the upgrade
4-Start the instances
5-Disable the replication agents - in order to avoid
unnecessary interference with the production environment.
6-Go to CRX Explorer
(e.g., http://localhost:4053/crx/explorer/browser/index.jsp) and delete
recursively the following content:
- /var/upgrade/WorkflowPreserveContentHook
- /var/upgrade/PreserveContentHook
Note that it is important to
use the delete recursively in CRX Explorer as opposed
to simple delete in either CRX Explorer or CRXDE Lite
in performing this action, to prevent a long delay during the process.
7-If you have unneeded
archived workflows, these should be removed before upgrade, as upgrading
workflows is among the more time-consuming steps in the upgrade process.
8-Remove custom application code. In some cases custom
application code may interfere with the upgrade process. It is therefore
recommended to remove custom code before upgrade and re-install the code after
upgrade is complete.
9-Run a consistency
check on each instance, and perform the appropriate fixes, if necessary.
10-· Download the AEM
installation file appropriate to your case:
- If you are upgrading a standalone environment, download the quickstart jar file.
- If you are upgrading an application server environment, download the war file.
11-Follow the steps appropriate to your environment below.
There are
two ways to back up and restore CRX repository content:
- You can create an external backup of the repository and store it in a safe location. If the repository breaks down, you can restore it to the previous state.
- You can create internal versions of the repository content. These versions are stored in the repository along with the content, so you can quickly restore nodes and trees you have changed or deleted.
STANDALONE (QUICKSTART) AND APPLICATION SERVER UPGRADE
For more detail go through the
following link
Starting with CQ 5.5 the internal representation of
workflows was been changed. As a result, when upgrading from a pre-5.5 system
you must ensure that all old workflow definitions are properly converted to the
new model. To do this, the system must be shut down and restarted again,
after the upgrade has finished.
Note:
In some cases where a workflow references a sub-workflow,
the migration from the old model to the new one may fail. Make sure to double check the resulting workflow models in
your upgraded instance to ensure that they accurately reflect your original
workflow models. In cases where an error occurs it may have to be manually
corrected by rebuilding part of the affected workflow definition with the GUI
workflow tool.
New Start/Stop Scripts and Locations
In AEM,
all start, stop and status scripts are found in the directory
crx-quickstart/bin/
This
differs from versions of CQ prior to 5.5, where these scripts were found in
crx-quickstart/server/
This
directory no longer exists in a fresh (non-upgrade) 5.5, 5.6 or 5.61
installation.
On
upgrade to from pre-5.5, the new scripts are installed in crx-quickstart/bin/ just as they would be in a fresh installation.
Consequently,
any custom written scripts that rely on the old CQ scripts must be adjusted.
In
addition, support for Windows services is now provided by the script
crx-quickstart/opt/helpers/start-service.bat
Non-standard repository.xml location
When upgrading from any pre-5.5 version, if a non-standard repository.xml location has been specified in the old WEB-INF/web.xml or in a bootstrap.properties
file, the repository.xml must be moved to crx-quickstart/repository/repository.xml before
upgrading.
Custom 404 Page
If you have a customized 404 page in /apps/sling/servlet/errorhandler/404.jsp
and use a variable called bindings, replace it
with a different name (e.g. bnd). This avoids a
compile error.
Overlays
If your application uses components that overlay any
built-in CQ foundation components (those found in /libs/foundation/components/)
it is important to note these and test each one after the upgrade to ensure
that it still works correctly. See Components
for more details.
OSGi bundles
If you have installed and configured any OSGi bundles using
the Apache Felix OSGi console (as opposed to storing them in the JCR
repository), then the Felix configuration should be saved before the upgrade.
This is done by saving the contents of /system/console/config.
Preserving changes
The
upgrade procedure deletes everything under the following repository folders:
- /content/geometrixx
- /content/usergenerated
- /apps/geometrixx
- /etc/designs/geometrixx
- /libs/
Consequently,
any customizations located in these folders or any of their subfolders must be
saved before the upgrade procedure is performed.
Note that
the above are repository folders visible through CQDE Lite and CQDE, not file
directories visible through the host OS.
Note:
CQDE(CQ
IDE)
For more details
please go through the link:
To preserve content at these locations you must export that
content to a content package and then import it back into the upgraded system.
This is done through the Package
Manager.
Package Manager:-
- Package Manager, which you use to manage the packages in your local CRX installation, including how to upload, create, and download packages. It also explains what packages are and how to provide permissions to them.
- Package Share, which lets you find, share, and download packages, components, and hotfixes from the Day server. You can also upload packages for internal company use.
For more
Details please go through the following link:
Note:- Since CQ 5.5,
CQ Package Manager is completely replaced by CRX Package Manager.
Unknown Node Type Warnings
n most
cases, a warning that includes a stacktrace indicates that the upgrade did not
complete successfully.
Currently, the only known exception to this rule is
the following stacktrace:
*WARN *
SearchIndex: Unable to get aggregate root for 5cb50678-ff3e-d8c2-0eec-4e9477978603
(SearchIndex.java, line 1446) javax.jcr.RepositoryException: failed to resolve
name of 5cb50678-ff3e-d8c2-0eec-4e9477978603
at
org.apache.jackrabbit.core.HierarchyManagerImpl.getName(HierarchyManagerImp
l.java:467)
at
org.apache.jackrabbit.core.HierarchyManagerImpl.getName(HierarchyManagerImp
l.java:427)
at
org.apache.jackrabbit.core.query.lucene.AggregateRuleImpl$AbstractInclude.m
atches(AggregateRuleImpl.java:347)
[...]
This is
non-critical and does not affect operations.
Related
to the above issue are the following error messages that may also be logged to
crx-quickstart/logs/error.log, which are also non-critical:
If the log contains other error messages, apart
from these, this may indicate that the upgrade failed or was only partially
completed.
Workspace Consistency
Errors such as the following
indicate that the the upgrade process failed due to an workspace storage
inconsistency:
Caused by:
org.apache.jackrabbit.core.state.ItemStateException: Trying to add a
non-existing child node: e4469e5a-4892-4760-acd6-3a3e8f120d4e
at
org.apache.jackrabbit.core.state.SharedItemStateManager$Update.checkAddedCh
ildNode(SharedItemStateManager.java:995)
at
org.apache.jackrabbit.core.state.SharedItemStateManager$Update.checkAddedCh
ildNodes(SharedItemStateManager.java:978)
at
org.apache.jackrabbit.core.state.SharedItemStateManager$Update.begin(Shared
ItemStateManager.java:577)
*ERROR*
TarPersistenceManager: No bundle found for uuid
'deadbeef-cafe-babe-cafe-babecafebabe'
...
*ERROR* RepositoryImpl:
Failed to initialize workspace 'crx.default'
javax.jcr.RepositoryException:
Error indexing workspace: Error indexing workspace: Error indexing workspace
To avoid these problems, it is recommended that you always
perform a consistency check before proceeding with the upgrade. For details on
how to perform the check and how to remedy any inconsistencies found, Please go
through the following link to see Consistency
Check as given below:-
Javascript Library Loading Problems
In some cases you may find problems with Javascript
library loading after upgrade. In such a case, the problem may be solved by
doing the following:
- Delete the repository subfolders below /var/clientlibs/.
- Clear the cache on any browser that is attempting to connect to the newly upgraded instance for the first time.
Custom Users and Groups
In cases where a 5.2.1 installation has custom users and/or
groups, an upgrade directly to 5.5 or later will cause those users and groups
to be lost. In that case these users and groups would have to be re-entered
manually in the newly upgraded instance. If this is feasible, then a direct
upgrade to 5.5 or later and subsequent re-entry of users and groups is the
recommended course.
However, if preserving the exisiting users and groups is a
priority (if, for example you have a very large nukmber of them, too many to
re-enter manually) the 5.2.1 instance must be upgraded to either 5.3 or 5.4
after which the normal upgrade to 5.5 or later can be performed.
For More Details Please go through the following link
Upgrading from CQ 5.2
to CQ 5.3
Upgrading
from CQ 5.2.1 to CQ 5.3 with Application Servers
Upgrading from CQ 5.2 to CQ 5.4
Custom login page may require modification to work after upgrade
Where a
custom login-page at /apps/wcm/auth/content/login is used, it needs to be
adapted as follows:
- Change the sling:resourceType from wcm/auth/components/login to cq/core/components/login
- Move all the static files (background image, css and js) to underneath the /apps/wcm/auth/content/login node (these used to be on the same level as the actual login content node).
Blog content needs to be migrated separately
When upgrading from 5.2 to 5.5 the blog content is not
automatically migrated. This content must be manually migrated by exporting (through
the package manager) and re-importing into the upgraded instance.
Content package install fails
Nodes of type nt:folder with access controls that
were added after the installation of CQ 5.2.1 may cause problems on upgrade to
5.5. This does not happen for all nt:folder nodes with ACLs, but only for some.
For example, if a customer added ACLs to /libs/collab, this will cause a
problem. The crx-quickstart/logs/error.log will log an error like:
12.02.2010
14:08:54 *ERROR* Importer: Error while committing /libs/collab:
javax.jcr.nodetype.ConstraintViolationException: Unable to perform
operation. Node is protected. (Importer.java, line 715)
|
Remove these ACL
entries to make the content package install work.
ACLs(Access Control Lists):-For More Details Please go
through the following link which are given below:-
Re-indexing fails with Out of Memory Errors
Depending on the number of cores, JVM heap settings and
content stored, there is a small risk that re-indexing a workspace in CQ 5.5
fails
This can be solved by
starting the JVM process with affinity to fewer cores.
API Changes
Added
Modified
Authorizable.java
Profile.java
User.java
UserManager
Note:-
The following API changes were made between CQ 5.3 and 5.4
and still apply in CQ 5.5. If your CQ application uses any of these functions
you will need to manually adjust your code.
Asset signature changes
com.day.cq.dam.api.Asset has changed:
- Resource getRendition(String name) is now
Rendition getRendition(String name) - Resource getOriginal() is now
Rendition getOriginal() - Resource getCurrentOriginal() is now
Rendition getCurrentOriginal() - List<Resource> getRenditions() is now
List<Rendition> getRenditions() - Resource getRendition(RenditionPicker picker) is now
Rendition getRendition(RenditionPicker picker)
RenditionPicker signature changes
com.day.cq.dam.api.RenditionPicker has changed:- Resource getRendition(Asset asset) is now
Rendition getRendition(Asset asset)
Taglib bundle has incorrect version number
The
org.apache.sling.atom.taglib bundle displays an incorrect version number in the
CRX system console. On an instance upgraded from 5.3 to 5.5 the version
is 0.9.0.tlp-R830217. The correct version, as found in a freshly
installed 5.5 instance, is 0.9.0.R988585. To fix this do the following:
- Delete the org.apache.sling.atom.taglib bundle via the bundles page of the system console (http://<host>:<port>/system/console/bundles)
- In the repository (using CRXDE Lite, for example), move /libs/sling/install/org.apache.sling.atom.taglib-0.9.0-R988585.jar to /tmp.
- Wait a few seconds and then move the bundle back to its previous location.
- Wait a few seconds and then verify the bundle version in the system console.
Note:-
This issue has minimal impact,
but for a 100% clean upgrade it should be addressed.
Some bundles are no longer needed
The
following bundles are no longer used in 5.5:
- org.apache.jackrabbit.jackrabbit-api
- org.apache.sling.samples.path-based.rtp
These can
be removed using the Apache Felix console at
http://<host>:<port>/system/console.
This
issue has minimal impact, but for a 100% clean upgrade it should be addressed
Some Sling properties are not updated
The
following sling.properties are not updated when upgrading from 5.2.1 or 5.3 to
5.5. Note that these differences all have minimal or no impact. However, if you
want a 100% clean upgrade you may wish to change the settings to their fresh
5.5 install values:
- Upgrade refers to the setting as found in 5.2.1 or 5.3 and in a 5.3 instance that has been upgraded to 5.5.
- Fresh refers to the setting as found in a freshly installed 5.5 instance.
1-
ds.loglevel
- Upgrade: ds.loglevel=${org.apache.sling.commons.log.level}
- Fresh: ds.loglevel=warn
2-
felix.service.urlhandlers
- Upgrade: felix.service.urlhandlers=false
- Fresh: felix.service.urlhandlers=true
3-
org.osgi.framework.bootdelegation
- Upgrade:
org.osgi.framework.bootdelegation=
com.yourkit.* ${org.apache.sling.launcher.bootdelegation} - Fresh:
org.osgi.framework.bootdelegation=
com.yourkit.*,
sun.reflect ${org.apache.sling.launcher.bootdelegation}
4-
org.osgi.framework.system.packages
- Upgrade:
org.osgi.framework.system.packages=
${osgi-core-packages},
${osgi-compendium-services},
${jre-${java.specification.version} ${org.apache.sling.launcher.system.packages} - Fresh:
org.osgi.framework.system.packages=
${osgi-core-packages},
${osgi-compendium-services},
org.apache.sling.launchpad.api;version\=1.0.0,
${jre-${java.specification.version}} ${org.apache.sling.launcher.system.packages}
Issue with javax.activation
In some
cases, after a 5.3 to 5.5 upgrade, some bundles may not start properly and
instead report an error related to a missing javax.activation package (check
the Apache Felix console at http://host:port/crx/system/console/bundles).
In such a
case:
- Stop CQ
- Edit the crx-quickstart/launchpad/sling.properties file to remove javax.activation (and the comma that follows) from any list of packages that contains it.
- Restart CQ
Tasks to perform after the upgrade
The following tasks should be performed after the upgrade:
1-Reinstall any customized OSGi bundles (if you had manually
installed them before).
2-Restore any customized configurations from the Web
console, for example:
- Mail Service
- Day Commons GFX Font Helper
- SSO Authentication Handler
- Apache Sling Resource Resolve
3-Re-enable LDAP if required (and if
disabled during the consistency checks).
4-There are various items (mainly for backup reasons) that
can be reviewed, and where appropriate, cleaned up after a successful upgrade
to CQ 5.5:
· repository:
- /home/groups-<xxx>
- /home/users-<xxx>
· file
system:
- crx-quickstart/server/*.NEW_<xxx>
- crx-quickstart/archived-versions
- crx-quickstart/repository/patches/new/*.jar
·
miscellaneous:
- /tmp/asset*
- crx-quickstart/repository/shared/replication/durbo
5-The redundant workspaces can also be deleted:
- crx-quickstart/repository/workspaces/crx.system
- crx-quickstart/repository/shared/workspaces/crx.system
crx-system is no longer obligatory. User data is now stored
in the appropriate workspace, and other system-wide information is available
without the need to initialize an additional workspace.
0 comments:
Post a Comment