Moving AEM From CRX2 To Oak Without Losing Control

An Adobe Experience Manager upgrade from CRX2 to Oak is a repository migration as much as an application upgrade. The change affects how content is stored, how queries are indexed, how permissions are evaluated, and how AEM behaves under load. Treating it as a routine version update can turn a manageable project into a prolonged outage or a difficult rollback.

CRX2 was built around Jackrabbit 2, while Oak provides a more scalable repository foundation for modern AEM deployments. Oak supports storage choices such as TarMK and DocumentNodeStore, allowing teams to design for authoring, publishing, clustering, and cloud-oriented operating models. The correct path depends on the AEM version, repository size, integrations, and availability requirements.

Australian teams also need to consider practical scheduling. A Sydney or Melbourne authoring platform may serve users across several time zones, while a publishing estate in Perth or Brisbane can have different maintenance windows and support coverage. A migration planned around Australian Eastern Standard Time should account for overnight editorial activity, batch integrations, and the reporting demands of the end of financial year.

The safest approach is staged: inventory the current platform, prepare code and content, rehearse the conversion, validate the Oak repository, and move production only after measured tests pass. The process below focuses on the decisions and pitfalls that most often determine whether the upgrade is predictable.

Understand The Repository Change

Oak is not simply a newer name for CRX2. It changes repository internals, indexing behaviour, observation mechanisms, and the way a deployment can scale. AEM code that worked against older Jackrabbit assumptions may rely on implementation details that are unsupported or inefficient in Oak.

Start by recording the current AEM and service pack versions, Java runtime, repository size, blob store arrangement, installed packages, custom bundles, workflows, scheduled jobs, and external connectors. Capture the number of nodes, binaries, users, groups, tags, versions, and active sessions. Include author, publish, dispatcher, and development environments rather than inspecting only the production author instance.

Architecture decisions should be made before data is moved. A smaller publisher may remain on TarMK, whereas a large author cluster may require a DocumentNodeStore and an external data store. Oak clustering is not a substitute for good replication design; shared storage, topology, failover, and session behaviour must be tested together. The discussion in horizontal AEM clustering is useful background when evaluating these choices.

Audit Content, Code, And Dependencies

A repository report should identify oversized assets, deep or unusual node structures, obsolete versions, orphaned binaries, unused tags, and packages that are no longer deployed. Remove confirmed rubbish before migration, but preserve an export or backup so that cleanup decisions remain reversible. Large DAM libraries deserve separate analysis because binary transfer time can dominate the overall window.

Review application code for direct JCR queries, custom node types, repository sessions, observation listeners, schedulers, servlets, and resource resolvers. Replace administrative sessions with service users and map each service user to the smallest practical set of permissions. Examine workflows that create large histories or launch external actions, since those can multiply repository writes during a cutover.

Query patterns are especially important. A query that was acceptable in CRX2 can become expensive in Oak if an appropriate index is absent or if the query definition prevents index use. Record slow-query logs and representative traffic before migration. Include content fragments, tags, site search, asset metadata, and custom components in the test set rather than relying on a handful of homepage requests.

Select And Rehearse The Migration Route

For many supported AEM upgrade paths, Adobe’s CRX2-to-Oak migration tooling, commonly associated with the crx2oak utility, performs the repository conversion. The exact command-line options and compatibility limits depend on the source and target AEM releases, so the tool supplied for the target version should be treated as authoritative. Do not copy a command from an older project without checking the current product documentation.

Create a full backup and test restoration before running the conversion. Then perform at least two rehearsals using production-like content, permissions, binaries, indexes, and integrations. Measure extraction time, conversion time, repository compaction, index generation, application startup, and post-migration checks. A rehearsal that excludes the DAM binary store or user directory gives false confidence.

The migration itself should normally occur with writes stopped. Quiesce authoring, disable schedulers and workflows, pause inbound feeds, and prevent deployment pipelines from changing packages during the window. Export or record any changes made after the final rehearsal, and define a clear rollback point. A database snapshot or filesystem copy is useful only when its consistency and restoration procedure have been proven.

Rebuild Indexes And Adapt Application Code

Oak indexes need deliberate design. Review the standard indexes provided by the target AEM release and add only the custom definitions required by real queries. Copying every old index into Oak can increase repository size, slow writes, and make reindexing unnecessarily long. Index definitions should be managed as code and deployed consistently across author and publish environments.

After conversion, allow indexes to complete before judging query performance. Check index status, traversal warnings, query plans, and slow-query logs. Test queries with realistic filters, ordering, full-text terms, and result limits. An application can appear healthy while silently traversing a large subtree, especially when a custom component requests broad results.

Code changes may include updated OSGi configurations, service-user mappings, repository session handling, and resource type resolution. Test package installation, content policies, editable templates, workflows, replication agents, launchers, and custom editors. Verify that Oak-compatible APIs are used and that no bundle depends on private Jackrabbit classes. Recompile against the target AEM SDK and run automated tests before the migration rehearsal.

Validate Operations And Performance

Functional testing should cover the full author-to-publish journey: create a page, upload and transform an asset, publish content, invalidate the dispatcher, render cached and uncached pages, and confirm analytics and search behaviour. Validate permissions with ordinary authors, publishers, administrators, service users, and anonymous visitors. Check versioning, rollout configurations, translations, redirects, vanity URLs, and scheduled activation.

Performance testing needs more than a page-load measurement. Observe repository response times, JVM memory, garbage collection, Oak observation queues, index latency, replication queues, dispatcher hit rates, and network traffic. Compare baseline and post-migration measurements under realistic concurrency. Application performance monitoring can make this evidence easier to interpret; a practical New Relic monitoring guide can help structure the telemetry review.

Plan for operational differences after go-live. Backup frequency, blob-store retention, compaction, revision cleanup, log rotation, and disk alerts should be documented for the Oak topology. Confirm who owns each alert and how an Australian support team will respond outside Sydney business hours. A short hypercare period with daily checks is safer than assuming a successful startup means the migration is complete.

Plan The Cutover And Compare Options

Choose a cutover window based on measured migration duration, not a hopeful estimate. Freeze content and code, take the final backup, stop integrations, run the conversion, install validated packages and configurations, complete index checks, and execute smoke tests before reopening authoring. Publish a controlled content sample first, then resume replication and traffic gradually.

Keep the old CRX2 environment intact until business owners approve the new system and recovery objectives have been tested. Do not allow both repositories to accept independent content changes after the final backup. Maintain a migration log covering commands, timestamps, checksums, package versions, validation results, and exceptions. This record is valuable for audit, incident response, and future platform upgrades.

Decision area	Conservative approach	Higher-scale approach	Main risk to control
Repository store	TarMK with carefully tested standby procedures	DocumentNodeStore with shared or cloud-backed storage	Incorrect assumptions about failover
Migration method	Offline conversion during a controlled freeze	Rehearsed conversion with automation and repeatable validation	Unmeasured downtime
Index strategy	Standard Oak indexes plus a small custom set	Tuned indexes based on production query evidence	Traversal and slow writes
Content handling	Migrate all approved content after cleanup	Separate large DAM or legacy-content workstreams	Extended transfer and validation time
Release decision	Full cutover after smoke and business tests	Phased traffic or publishing rollout	Split-brain content or unclear rollback

Use the migration as an opportunity to remove unsupported customisations, standardise deployment packages, and document repository ownership. Teams attending or reviewing CIRCUIT’s AEM-focused technical material can also use the CIRCUIT registration page as a route to the event’s wider developer resources and session context.

A controlled CRX2-to-Oak project protects more than content. It preserves publishing reliability, search performance, editorial permissions, integrations, and the confidence of the people who operate the platform. Build a production-like rehearsal, measure every stage, and make the final go-live decision from evidence rather than optimism.