Recommend mechanism for launching the feature-model based Starter

STATUS: Proposal

Problem description

With the launchpad and provisioning model Sling Starter (or Launchpad) we always had a single deliverable - the executable jar. With the feature model this becomes more complicated, as we have multiple options for delivery and launch. We should make clear recommendations to our users, consumers of the Sling Starter, on how to obtain and launch it.

Requirements

The Sling Starter serves two major purposes:

1. Be an example for Sling users regarding how a Sling application can be structured
2. Allow Sling users to quickly start up a Sling application and experiment with it

It is not an objective for the Sling Starter to be extended for production applications, as documented in the Sling Starter README.

Supported scenarios

The following scenarios are supported for discovering Sling functionality through the Sling Starter:

TS1: explore the Sling Starter Applications ( Welcome page, Composum, SlingShot)
TS2: run Sling Starter in various topologies - oak_tar, oak_mongo
TS3: access Sling Starter logs and runtime data
TS4: install, update, and uninstall bundles and content packages
TS5: perform various operations through the Web Console

Notably, altering the feature model and rebuilding the Sling Starter are not supported.

Available options

Feature Launcher

The Sling Feature Launcher launches feature model files ( defined as JSON ) or feature archives. It support various low-level options that control OSGi and Feature Model level configurations.

To launch the Sling Starter, the following requirements must be met:

• A suitable version of the JRE is present locally
• The feature launcher is present locally

Then, the user should execute the feature launcher and pass it the relevant arguments. These can be either feature files or feature models, and can either be present locally or accessed from a Maven repository.

Examples:

$ java -jar org.apache.sling.feature.launcher-1.2.0.jar -f org.apache.sling.starter-oak_tar.json
$ java -jar org.apache.sling.feature.launcher-1.2.0.jar -f org.apache.sling.starter-oak_tar.json
$ java -jar org.apache.sling.feature.launcher-1.2.0.jar -f https://repo1.maven.org/maven2/org/apache/sling/org.apache.sling.starter/12/org.apache.sling.starter-oak_tar.json

Kickstart Launcher

The Kickstart Launcher creates an executable jar that wraps a feature model archive. It exposes various high-level options controlling the behaviour of the Sling Starter.

To launch the Sling Starter, the following requirements must be met:

• A suitable version of the JRE is present locally
• The kickstart launcher is present locally

Examples:

$ java -jar org.apache.sling.kickstart-12.jar

Feature Launcher container

The Sling Feature Launcher is also able to produce a Docker image ( apache/sling-feature-launcher  ) during build time. This image can be used to launch feature-based applications. It is similar to the Feature Launcher  option, but does not require a locally installed JVM.

To launch the Sling Starter, the only requirement is a container engine.

Examples:

$ docker run -e FEATURE_FILES="https://repo1.maven.org/maven2/org/apache/sling/org.apache.sling.starter/12/org.apache.sling.starter-oak_tar.json" --rm apache/sling-feature-launcher
$ podman run -e FEATURE_FILES="https://repo1.maven.org/maven2/org/apache/sling/org.apache.sling.starter/12/org.apache.sling.starter-oak_tar.json" --rm apache/sling-feature-launcher

Sling Starter container

We publish a Sling container image that exposes the full functionality of the Sling Starter at https://hub.docker.com/r/apache/sling . This image can be launched via Docker (or another compatible runtime like Podman ). The configuration must be done using the environment variables accepted by the Sling Starter.

To launch the Sling Starter, the only requirement is a container engine.

Examples

$ docker run -e MONGODB_HOST=mongo apache/sling:12 oak_mongo
$ podman run -p 8080 apache/sling:12 oak_tar

JBang

JBang allows for running Java "scripts" which are real Java classes executed with a real JVM.

Comments-based annotations for scripts allow for declaring dependencies that are automatically downloaded, selecting a specific JVM etc.

Installing JBang is easy and does not require a JVM to be pre-installed. If one is available it will be used but that's not a requirement, and ot

Evaluation

All the listed solutions fulfill the supported scenarios. To select a preferred solution, we should evaluate how easy they are to launch for our users.

Solution	Launch requirements	Launch complexity
Feature Launcher	Supported version of Java, Feature Launcher downloaded locally	Low-level, feature launcher flags
Kickstart Launcher	Supported version of Java, Kickstart Launcher downloaded locally	High-level, kickstart launcher flags
Feature Launcher Container	Container runtime engine	Low-level, feature launcher flags
Sling Starter Container	Container runtime engine	High-level, Sling Starter env vars and flags

Java vs Containers

The assumption that a container engine is a lower execution bar compared to a Java Runtime for our users need to be qualified.

The Sling Starter supports a range of Java versions, e.g. 8-17. We don't only ask our users to have a Java Runtime installed, we ask them to have a specific version. Each new Java version potentially breaks the Sling Starter in a way, and historically we have not released the Sling Starter frequently enough to

It is a reasonable assumption that users are more likely to have recent versions of Java installed, rather than old ones. So the problem here would be that we are asking users to install older Java runtime versions, which a) they may not want to do and b) reflects poorly on us.

As for the availability of container engines, there are two data points available:

1. In the JRebel Java developer productivity report 2021 Virtualisation category, 57% of respondents use Docker, 42% Kubernetes (multiple selections possible). Only 4% do not use a virtualisation tool
2. The StackOverflow developer survey 2021 reports that 55% of professional developers have done extensive development work with Docker. Additionally, Docker is on the second spot in the most loved/wanted technologies, behind Git.

Proposal

Make the Sling Starter Container the recommended way of launching the Sling Starter. This will be reflected in the Sling Documentation and the Sling Starter README.