Skip to main content


One Tool to Configure Them All: Sling RepoInit

One Tool Hero

The core paradigm for the Java Content Repository (JCR), the repository for Adobe Experience Manager (AEM) is Everything is Content. This principal drives the flexibility which made AEM a market-leading solution. It does, however, come with a downside, managing the initial repository state is challenging since the repository state is a combination of the content, code and configuration for an AEM application.

Managing this initial state is important for developers and administrators to be able to stand up local instances, standing up new environments and keeping environments in sync.

Multiple teams have build parts of a solution to this problem, including:

Recently though, another solution has come to the fore for configuring the initial repository state.

Apache Sling RepoInit

Apache Sling RepoInit has been a feature of Apache Sling since 2016, but historically has been used for base repository initialization as a part of slingstart / launchpad starter, not for project-level repository initialization.

Version 1.1.6+ of Sling JCR RepoInit includes the ability for registering configurations with RepoInit scripts or references. This brings Apache Sling Repoint out from just being a base repository initializer to enable use by project teams.

With Sling Repoint, we have a consolidated grammar to:

  • Create groups
  • Assign permissions
  • Create paths
  • Set properties
  • Assign group membership
  • Create OSGi configurations
  • Create service users

Enabling RepoInit in AEM

Note: this is based on AEM 6.5.5, newer service packs and AEM Cloud Service may have different dependency versions.

AEM includes a fairly old version of Sling RepoInit, in order to leverage the full power of Sling RepoInit, you need to upgrade to the following dependencies for AEM 6.5.5:

Configuring RepositoryInitializer

We can configure RepoInit scripts to be executed by registering a configuration of the Service Factory, however there is a challenge with how this service resolves the references. Each reference is expected to be in the form of a URL and OSGi supports exposing bundles as URLs, however when Apache Felix resolves the URL of a bundle in the URLHandlersBundleStreamHandler, it expects the URL host to be the UUID of the bundle, not a stable ID such as the Bundle’s Symbolic Name.

Note: as per Oliver Lietz’s comment I would recommend following the PAX URL Classpath method rather than the approach below.

I have opened a ticket to get this resolved, but until that’s complete and Generally Available, the best option is to create an OSGi Component to resolve the Bundle URL and initialize the configurations when the bundle starts.

Below is a sample implementation showing how this could be done, showing how to support multiple RepoInit files in a single bundle:

Now that you have Sling RepoInit setup and working, you can create any number of RepoInit scripts in the ./src/main/resources/repoinits folder and on bundle installation they’ll be live reloaded.

With the RepoInit scripts, you can set up your repository completely with commands like:

# Create paths
create path /content/my-site(cq:Page)

# Create a group
create group my-site-admin
set ACL for my-site-admin
    allow crx:replicate, jcr:lockManagement, jcr:versionManagement, rep:write on /content/my-site

# Add group members
add my-site-admin to group administrators

# And More! 

Apache Sling RepoInit is the consolidated way to initialize a repository for any Apache Sling-based system including AEM 6.5, AEM as a Cloud Service and Apache Sling CMS. With RepoInit, you can be assured that your solution will work on both the current version of AEM as well as AEM as a Cloud Service.

Thoughts on “One Tool to Configure Them All: Sling RepoInit”

  1. You don’t have to write any code, you can use the field scripts and put your script in there (which works best if you deploy the script).

  2. Agreed Jörg, you can do this without any additional code, however, specifying via the script attribute isn’t ideal as you have to inline the RepoInit statements into OSGi configuration which is hard to read / understand.

  3. While implementing repoinit there are only two scenarios when these scripts gets executed, given if one does not have access to either crx/de or felix console.(for the case of CI/CD using Jenkins or cloud deployment)
    1. If config related to repoinit with scripts in it is not existing, then doing a mvn deployment using ci/cd for first time will add ACL or create group based on whatever is written in script. However it is not adding or updating any ACL in subsequent deployment. (it works only if we manually remove repoinit config from crx/de before next deployment or save script by opening it again in crx/de or felix).
    2. If we are restarting the application, then all scripts gets executed and permission gets added. ( effectively after each deployment we need to bounce the application to execute repoinit script)

    Because of this limitation, if there is a requirement to update the script with different set of ACL for existing group or user then those permission will not get updated unless we bounce the instance or some one with access to crx/de or admin console goes and manually triggers those config. In both the case admin is required.

    Any suggestion on how to overcome this problem.

  4. Hi Dan,
    I am trying to use the following syntax raw:classpath://some-repoinit-file.txt as mentioned in the documentation but I get a java.lang.IllegalStateException: Unknown protocol: raw.
    Any idea why? Also what is the link to the ticket you have submitted so that I can follow?

    Assuming it works, will the init file get executed everytime the bundle containing it is deployed or only once?


  5. There is no need to write any code, just use Pax URL Classpath (an OSGi URL handler) to reference (configurations and) repoinit statements.
    Since version 2.6.3 Pax URL Classpath is an uber jar and therefore you only have to deploy the pax-url-classpath bundle to make it work.
    See also SLING-5930 “Provide repoinit statements as bundle resource” (2016!), SLING-9944 “Bundle configurations and reference via classpath protocol” and – plain repoinit statements are much more readable and easier to (re)use.
    The proper syntax for factory configs is classpath:[//BundleSymbolicName/]filename.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Dan Klco, Adobe Digital Marketing Technical Director

Dan is a certified Adobe Digital Marketing Technologist, Architect, and Advisor, having led multiple successful digital marketing programs on the Adobe Experience Cloud. He's passionate about solving complex problems and building innovative digital marketing solutions. Dan is a PMC Member of the Apache Sling project, frequent Adobe Beta participant and committer to ACS AEM Commons, allowing a unique insight into the cutting edge of the Adobe Experience Cloud platform.

More from this Author

Follow Us