SLING-9522 - Add how-to series for the Feature Model
diff --git a/src/main/jbake/assets/documentation/feature-model/howtos/sling.home.in.browser.png b/src/main/jbake/assets/documentation/feature-model/howtos/sling.home.in.browser.png
deleted file mode 100644
index 2bd1686..0000000
--- a/src/main/jbake/assets/documentation/feature-model/howtos/sling.home.in.browser.png
+++ /dev/null
Binary files differ
diff --git a/src/main/jbake/content/documentation/development/feature-model.md b/src/main/jbake/content/documentation/development/feature-model.md
index 6f99012..b0492b9 100644
--- a/src/main/jbake/content/documentation/development/feature-model.md
+++ b/src/main/jbake/content/documentation/development/feature-model.md
@@ -11,4 +11,74 @@
evolves.
See [https://github.com/apache/sling-org-apache-sling-feature](https://github.com/apache/sling-org-apache-sling-feature) for more information
-about the Feature Model.
\ No newline at end of file
+about the Feature Model.
+
+### The Feature Model
+
+As said above the Feature Model is an *OSGi** version of the Sling Provisioning Model.
+
+OSGi bundles can be installed on an OSGi container but there is a much more to it to install it onto
+an application or create an application. The Feature Model provides these additional parts necessary
+to build applications by defining the dependencies, properties, configuration and setup actions.
+
+It is important to note that a Feature Model does **not have to contain all parts** and some of them
+can be just providing for example configurations to customize a module or to override a configuration
+provided by another Feature Model.
+
+A Feature Model provides:
+
+* A unique Identifier
+* Title, Description, Vendor etc
+* Bundle Dependencies
+* Framework Properties
+* Configurations
+* Repo(sitory)-init statements
+
+Some of these parts are handled by Feature Model Extensions so that they can be loaded if required.
+
+Because Feature Model can be easily aggregated basically every bundle can provide their own feature model
+which then can be aggregated into a bigger module or application (like Sling).
+
+### Feature Model Ecosystem
+
+The Feature Model Ecosystem is comprised of these parts:
+
+* Feature Model (JSon file)
+* Feature Model Maven Plugin (sling-slingfeature-maven-plugin)
+* Feature Launcher
+* Feature Model Extension (provides handling for additional Feature Model parts)
+* Feature Model Converters (Content Package or Provisioning Model to Feature Models)
+* Feature Model Converter Maven Plugins (Maven Plugin wrapper for Converters)
+* Maven Repository / Cache
+
+### Feature Model and Maven Repository
+
+If not inside a project Feature Models and other Artifact created from processing Feature Models
+are stored in the local Maven Repository. They may or may not be stored in the same location
+as the project.
+
+This allows the Feature Aggregator and/or Launcher to obtain Feature Models from other sources than
+just the current project without to know anything about the project(s) that provide them.
+
+### Aggregration
+
+The most important principal of Feature Model is that fact that they can be aggregated into bigger
+modules or entire applications. This applies to all part of a Feature Model and resolving conflicts.
+
+Aggregation to generate consolidated Feature Models is done by the **Feature Model Maven Plugin**
+(sling-slingfeature-maven-plugin) which takes a list of Feature Modules and then creates
+a new Feature Model with all aggregates in it. It also provides the ability to mark a Feature
+Model as complete or final, provide artifact, variable, configuration and framwork property
+overwrites. Feature Models can added as files, by their classifiers or as Maven dependencies.
+
+Overwrites are used to decide which version of a conflicting element is added to the aggregate.
+
+### Feature Reference Files
+
+A **text file** that contains a list of **Maven Ids** or **Maven Urls** of Feature Models which then can
+be used as a reference to include all of the listed Feature Models.
+So instead of listing all the desired Feature Models a single Feature Reference file with all of
+the Feature Models listed is enough.
+
+Feature Reference Files can be added for example by adding it as **Selection** with type **REFS_INCLUDE**.
+
diff --git a/src/main/jbake/content/documentation/feature-model/feature-model-overview.md b/src/main/jbake/content/documentation/feature-model/feature-model-overview.md
index 6bf4945..1161abf 100644
--- a/src/main/jbake/content/documentation/feature-model/feature-model-overview.md
+++ b/src/main/jbake/content/documentation/feature-model/feature-model-overview.md
@@ -1,24 +1,44 @@
-title=Feature Model Documentation Overview
+title=Feature Model
type=page
status=published
tags=feature model,osgi,project,guide,howtos
~~~~~~
-## Guide to a Feature Model
+## A How-To Guide to Feature Models
-This document is the landing page for the guides about Feature Models and other
-references.
+The Sling Feature Model provides a new approach for assembling applications and is intended to replace the Sling Provisioning Model.
+Both approaches accomplish the same goal of defining and assembling OSGi-based applications, however, the Feature Model
+is more robust and is not coupled to Sling. It addresses application packaging concerns by allowing all aspects of an application
+(e.g., bundles, configuration, framework properties, capabilities, requirements and custom artifacts) to be defined declaratively.
-## Feature Model Guides
+### Key Concepts
-* [How To Start Sling with Kickstart](/documentation/feature-model/howtos/kickstart.md)
-* [Deep Dive into Create Sling Feature Model](/documentation/feature-model/howtos/create-sling-fm.md)
-* [How To Create Sling Feature Archive](/documentation/feature-model/howtos/create-sling-far.md)
-* [How to Create Sling Composite Node Store](/documentation/feature-model/howtos/create-sling-composite.md)
+* Features - Central entity of the Feature Model used to logically group metadata, configuration, bundles and
+ extensions to represent a system module or subsystem.
+* Feature Extension - An extension point for adding new capabilities to the Feature Model.
+* Feature Archives - Packages one or more features and dependencies to simplify the distribution of an application.
+* Feature Reference Files - A text descriptor file with a list of features.
+* Feature Aggregation - A method for packaging multiple features into a single feature.
-## Feature Model Readme Files
+### About this How-To
-This is a list of all Feature Model Read Me files that are available
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+This how-to is designed to be a progressive tutorial in which each how-to builds on the previous. It's recommended
+that you start on the first and work your way through them consecutively.
+</div>
+
+
+## Exploring Feature Models by Example
+
+* [How To Start Sling with the Kickstarter](/documentation/feature-model/howtos/kickstart.html)
+* [How to Create a Custom Feature Model Project](/documentation/feature-model/howtos/sling-with-custom-project.html)
+* [How to Create a Sling Composite Node Store](/documentation/feature-model/howtos/create-sling-composite.html)
+* [How to Convert a Provisioning Model to a Feature Model](/documentation/feature-model/howtos/create-sling-fm.html)
+
+## Advanced Reading
+
+Want to know more? Take a look at the README files for the projects in the Feature Model ecosystem.
* [Feature Model](https://github.com/apache/sling-org-apache-sling-feature/blob/master/readme.md)
* [Feature Docs](https://github.com/apache/sling-org-apache-sling-feature/blob/master/docs/features.md)
@@ -28,3 +48,4 @@
* [Feature Aggregation](https://github.com/apache/sling-org-apache-sling-feature/blob/master/docs/aggregation.md)
* [SlingFeature Maven Plugin](https://github.com/apache/sling-slingfeature-maven-plugin)
* [Feature Launcher](https://github.com/apache/sling-org-apache-sling-feature-launcher)
+* [Kickstarter](https://github.com/apache/sling-org-apache-sling-kickstart/blob/master/Readme.md)
diff --git a/src/main/jbake/content/documentation/feature-model/howtos/create-sling-composite.md b/src/main/jbake/content/documentation/feature-model/howtos/create-sling-composite.md
new file mode 100644
index 0000000..e323332
--- /dev/null
+++ b/src/main/jbake/content/documentation/feature-model/howtos/create-sling-composite.md
@@ -0,0 +1,187 @@
+title=How to Create a Composite NodeStore
+type=page
+status=published
+tags=feature model,sling,kickstarter
+~~~~~~
+
+### About this How-To
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+#### What we'll explore:
+
+* Create a Sling instance with a Composite NodeStore using the Feature Model
+* Learn why it's a good idea to segment your application from your content
+
+#### What you should know:
+
+* Skill Level: Intermediate
+* Environment: Windows/Unix
+* Time: 20 minutes
+
+</div>
+
+* Back To: [How to Create a Custom Feature Model Project](/documentation/feature-model/howtos/sling-with-custom-project.html)
+* Back Home: [Feature Model](/documentation/feature-model/feature-model-overview.html)
+
+### Prerequisites
+
+In order to follow this how-to you'll need the following on your computer:
+
+* Java 8
+* Maven 3
+* Bash shell
+
+
+### What's the Composite NodeStore
+
+A Composite NodeStore is a repository composed of two or more nodestores. The nodestores work together
+to provide a single logical repository. Like a UNIX file system, each nodestore acts similar to
+file system mount points. For example, you can mount the `/content` node as read-write and the
+`/apps` and `/libs` nodes as read-only.
+
+
+### Why use a Composite NodeStore
+
+The Composite NodeStore can be used to improve the stability of your site. In general, you can think
+of a Sling site as consisting of two parts: your content (which changes often) and your application
+(which changes periodically). Unless there's a scheduled application release, there's very little
+reason to allow a running Sling instance to be changed from a code/application perspective.
+
+It provides a great way to ensure that application changes are not allowed without an
+official release, but still allow day-to-day editorial content changes. Some of the benefits of using
+the Composite NodeStore and separating your content and application concerns are:
+
+* Improve site stability
+* Minimize downtime with blue-green deployments
+* Use CI/CD pipelines to release immutable versions of your application
+* Easily update/rollback your application without impacting your valuable content
+* Ensure your site is always up-to-date and current
+
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+For those of you familiar with container orchestration platforms like Kubernetes (k8s), can you
+think of a reason why the Composite NodeStore may be useful for Sling applications in the container world?
+
+</div>
+
+
+### Explanation on what will happen
+
+Let's take a quick look at what will happen behind the scenes as we work through this tutorial.
+
+1. First, we'll start Sling using a regular nodestore. We'll call this our _seed_ step as it'll allow
+ us to bootstrap our instance with our application code. When we're done with the _seeding_ process,
+ we'll have our application fully populated in the `/apps` and `/libs` JCR nodes. These nodes will
+ later become read-only.
+2. Once Sling has started for the first time and completed the seeding process, we'll stop the instance.
+3. Then, we'll designate the seeded repository as our read-only segment store.
+4. Lastly, we'll start Sling in _composite mode_. When Sling comes up it will create another nodestore,
+ called _global_ that will function as our read-write portion of the repository. At this point, your
+ application can't be changed while the Sling instance is running.
+
+
+### Step 1: Obtain the Kickstarter module
+
+<div style="background: #fff3cd; padding: 14px; border-left: 10px solid #ffeeba;">
+
+**TODO:** Update instructions to use the binary release.
+
+</div>
+
+Build the Kickstarter and install it into your local Maven repository.
+
+ $ git clone https://github.com/apache/sling-org-apache-sling-kickstart.git
+ $ cd sling-org-apache-sling-kickstart
+ $ mvn clean install
+
+### Step 2: Initialize (seed) the repository
+
+Start Sling for the first time using the seed creation script.
+
+ $ ./bin/create_seed_fm.sh
+
+This script uses the Kickstarter to start Sling with two Feature Models:
+
+1. `feature-sling12-two-headed.json` - Our main Feature Model. Sling Feature Model without a NodeStore
+2. `feature-two-headed-seed.json` - Additional Feature Model. Feature Model with a single NodeStore
+
+When you see the line below, Sling has been fully initialized and should be safely stopped by entering `<CTRC>+C`.
+
+ ESAPI: SUCCESSFULLY LOADED validation.properties via the CLASSPATH from '/ (root)'...
+
+<div style="background: #fff3cd; padding: 14px; border-left: 10px solid #ffeeba;">
+
+**TODO:** Add more detail on what happens during the seeding process.
+
+</div>
+
+
+### Step 3: Start Sling using the Composite NodeStore
+
+Now, let's start Sling a second time using the Composite NodeStore.
+
+ $ ./bin/run_composite_fm.sh
+
+
+<div style="background: #fff3cd; padding: 14px; border-left: 10px solid #ffeeba;">
+
+**TODO:** Add more detail on what happens during the composite startup process.
+
+</div>
+
+
+### Step 4: Verify read-only and read-write nodes
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+The next set of steps uses the _SlingPostSevlet_ and cURL to test the read-write and read-only portions of
+the repository. If you prefer not to use cURL, simply [log into Sling](http://localhost:8080), navigate to
+[Composum](http://localhost:8080/bin/browser.html) and manipulate the nodes by hand.
+
+</div>
+
+
+**1.** Let's start by making a post request and add a JCR property to the `/content` node.
+
+ $ curl -s -v -u admin:admin -FtestProperty='I can write to the content node' \
+ 'http://localhost:8080/content/slingshot' > /dev/null
+ ...
+ < HTTP/1.1 200 OK
+ ...
+
+Since this is a read-write repository path, you should receive an _HTTP 200 OK_ response and be able to write to a property called
+`testProperty` with the value `I can write to the content node` on the `/content/slingshot` node.
+
+**2.** Now, let's try the same test, but let's attempt to write to a read-only node.
+
+ $ curl -s -v -u admin:admin -FtestProperty='I cannot write to the apps node' \
+ 'http://localhost:8080/apps/slingshot' > /dev/null
+ ...
+ < HTTP/1.1 500 Server Error
+ ...
+
+You should now receive an _HTTP 500 error_ response. So, even as the admin user, you can't write to the `/apps` section of the repository.
+
+
+## Mission Accomplished
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+#### What we learned:
+
+* The benefits of running a repository comprised of read-only and read-write nodes
+* How to run Sling using the Composite Nodestore
+* Even as the admin user, we can't make changes to read-only nodes
+
+</div>
+
+If you stick with us, we'll show you how to convert an existing Provisioning Model to a Feature Model..
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+* Next Up: [How to Convert a Provisioning Model to a Feature Model](/documentation/feature-model/howtos/create-sling-fm.html)
+* Back To: [How to Create a Custom Feature Model Project](/documentation/feature-model/howtos/sling-with-custom-project.html)
+
+</div>
diff --git a/src/main/jbake/content/documentation/feature-model/howtos/create-sling-fm.md b/src/main/jbake/content/documentation/feature-model/howtos/create-sling-fm.md
new file mode 100644
index 0000000..523c557
--- /dev/null
+++ b/src/main/jbake/content/documentation/feature-model/howtos/create-sling-fm.md
@@ -0,0 +1,129 @@
+title=How to Convert a Provisioning Model to a Feature Model
+type=page
+status=published
+tags=feature model,sling,kickstarter
+~~~~~~
+
+### About this How-To
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+#### What we'll explore:
+
+* We'll convert the Sling Starter project to a Feature Model using a Maven plugin
+* We'll visit our old friend, the Kickstarter, and start Sling using the generated Feature Model
+
+#### What you should know:
+
+* Skill Level: Intermediate
+* Environment: Windows/Unix
+* Time: 20 minutes
+
+</div>
+
+* Back To: [How to Create a Composite NodeStore](/documentation/feature-model/howtos/create-sling-composite.html)
+* Back Home: [Feature Model](/documentation/feature-model/feature-model-overview.html)
+
+
+### Prerequisites
+
+In order to follow this how-to you'll need the following on your computer:
+
+* Java 8
+* Maven 3
+* Bash shell
+
+
+### Create a Feature Model
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+**Note:** At the time of this writing, the Feature Model is not officially used by Sling.
+Until Sling is fully converted to the Feature Model, we'll have to use the
+ _Provisioning to Feature Model Converter Plugin_. The plugin will create a Feature Model
+from each Provisioning Model file. The plugin will then assemble all the Feature Models
+into a single Feature Model file using the Feature Aggregate.
+
+</div>
+
+
+### Step 1: Get Sling Starter and the Kickstarter projects
+
+Start by creating a directory called `myfeaturemodel`. We'll use this directory as our
+project workspace.
+
+ $ mkdir myfeaturemodel
+
+We'll add two projects to this workspace:
+
+* The Sling Starter source code
+* The Sling Kickstarter source code
+
+ $ cd myfeaturemodel
+ $ git clone https://github.com/apache/sling-org-apache-sling-starter.git
+ $ git clone https://github.com/apache/sling-org-apache-sling-kickstart.git
+
+Your workspace should now look like this:
+
+ $ ls -l
+ drwxr-xr-x 15 user group 480 Jun 8 16:16 sling-org-apache-sling-kickstart
+ drwxr-xr-x 13 user group 416 Jun 8 16:10 sling-org-apache-sling-starter
+
+
+### Step 2: Run the Provisioning Model Conversion
+
+The Kickstarter provides a Maven POM file called `sling-fm-pom.xml` that converts the Sling Starter Provisioning Models
+to Feature Models. It then aggregates them into a single Feature Model.
+
+ $ cd sling-org-apache-sling-kickstart
+ $ mvn -f sling-fm-pom.xml install -Dsling.starter.folder=../sling-org-apache-sling-starter
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+Once the build is complete, you'll find a Feature Model file at
+`sling-org-apache-sling-kickstart/target/slingfeature-tmp/feature-sling12.json`.
+
+</div>
+
+
+Before continuing, run one more Maven build in this directory as we will need a copy of the Kickstarter JAR in the next
+section.
+
+ $ mvn clean install
+
+
+### Step 3: Run Sling using the Feature Model
+
+Now that we have a Feature Model file for Sling and a Kickstarter JAR, we are ready to create a new directory
+to execute Sling using the Kickstarter and the Feature Model we just created.
+
+Begin, by changing into the parent workspace (`myfeaturemodel`) and create a new directory to run the Kickstarter.
+Then, copy the Feature Model file and Kickstarter JAR.
+
+ $ cd ..
+ $ mkdir kickstart-run && cd kickstart-run
+ $ cp ../sling-org-apache-sling-kickstart/target/slingfeature-tmp/feature-sling12.json .
+ $ cp ../sling-org-apache-sling-kickstart/target/org.apache.sling.kickstart-0.0.3-SNAPSHOT.jar .
+
+Lastly, let's start Sling using the Feature Model.
+
+ $ java -jar org.apache.sling.kickstart-0.0.3-SNAPSHOT.jar -s feature-sling12.json
+
+
+## Mission Accomplished
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+#### What we learned:
+
+* Learned that the _Provisioning to Feature Model Converter Plugin_ can be used to convert Provisioning Models to Feature Models
+* Converted the Provisioning Models in the Sling Starter project to a single Feature Model
+* Started Sling using the newly created Feature Model file with the Kickstarter
+
+</div>
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+* Back To: [How to Create a Composite NodeStore](/documentation/feature-model/howtos/create-sling-composite.html)
+
+</div>
diff --git a/src/main/jbake/content/documentation/feature-model/howtos/kickstart.md b/src/main/jbake/content/documentation/feature-model/howtos/kickstart.md
index 0137bad..29851ff 100644
--- a/src/main/jbake/content/documentation/feature-model/howtos/kickstart.md
+++ b/src/main/jbake/content/documentation/feature-model/howtos/kickstart.md
@@ -1,222 +1,220 @@
-title=How To Startup Sling with Kickstart
+title=How to Start Sling with the Kickstarter
type=page
status=published
-tags=feature model,sling,kickstart
+tags=feature model,sling,kickstarter
~~~~~~
-## How To Startup Sling with Kickstart
+### About this How-To
-What will you learn: start Sling with Sling Kickstart Project
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
- How much time: 30min
- Skill Level: Beginner
- Environment: Unix
+#### What we'll explore:
+* We'll start Sling with the Kickstart Launcher (a.k.a the kickstarter) and explore the Feature Model
-[Back to the Feature Model Home](/documentation/feature-model/feature-model-overview.md)
+#### What you should know:
+
+* Skill Level: Beginner
+* Environment: Windows/Unix
+* Time: 20 minutes
+
+</div>
+
+Back To: [Feature Model Home](/documentation/feature-model/feature-model-overview.html)
### Prerequisites
-In order to follow through this HowTo you need the following on your computer:
+In order to follow this how-to you'll need the following on your computer:
* Java 8
-* Maven 3
-* Command Line with Bash
+* Bash shell
-### Download the Kickstart JAR File
+### What's the Kickstarter
-The Sling Kickstart Project JAR file can be downloaded here:
-[Sling Kickstart Snapshots](https://repository.apache.org/content/groups/snapshots/org/apache/sling/org.apache.sling.kickstart/0.0.1-SNAPSHOT/)
-Select the latest version, download it and then rename it to
-**org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar**. Then place the file inside
-the **Project Root Folder** of your choice and then open a Terminal and change
-to that folder:
+Prior to the Kickstarter, the Sling application was assembled into an uber JAR using the Provisioning Model.
+The JAR file was fairly large in size and weighed in at ~70MB. If the Sling application required a new bundle,
+the uber JAR would have to be rebuilt. The Kickstarter was designed to solve this problem as well as streamline
+the application packaging process.
- $ cd <project root folder>
+The Kickstarter provides a method to start Sling using a new application packaging/assembly approach known as
+the _Feature Model_. By default, the Kickstarter is configured with a minimum set of feature definitions to
+produce a lightweight Sling application. If additional customization is required, simply
+define additional features based on your requirements. Any additional features will then be pulled from a Maven repository.
+### How does the Kickstarter work
-### Run and Access Sling
+The [Kickstarter](https://github.com/apache/sling-org-apache-sling-kickstart) uses the Feature Model Launcher to
+start a Sling instance. It sets up a control port to manage the instance and provides default values to start Sling.
+The Feature Launcher then downloads the necessary dependencies and installs them into the OSGi container.
-We start Sling by just executing the JAR file:
+Let's try this out!
- $ java -jar org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar
+### Step 1: Download the Kickstarter
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
-Wait a moment for Sling to launch fully then head over to the
-[Sling Home Page](http://localhost:8080/):
+At the time of this writing, the latest Kickstarter version was `0.0.2`. Adjust the commands below to reflect the
+version you downloaded.
-
+</div>
-Click **Login** link and log in with **admin/admin** and then click on **browse
-Content** to bring up Composum to see the JCR node tree.
+Visit the [Apache Sling Downloads](https://sling.apache.org/downloads.cgi) page and download the _Kickstart Project_
+bundle.
-### Run a Service
+Then, create a working directory for the Kickstarter and copy the bundle to this location. You can name this
+directory anything you like.
-We first will stop Sling by hitting **Ctrl-C** on the command line to exit the
-process and then launch it with the **start** command:
+ $ mkdir kickstarter
+ $ cd kickstarter
+ $ cp /some/download/path/org.apache.sling.kickstart-0.0.2.jar .
-First check if Sling process has ended
+### Step 2: Start Sling with the Kickstarter
- $ ps -ef | grep java
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+ Make sure nothing is listening on port 8080 as this port will be used by Sling.
-Then let Sling start as service:
+</div>
- $ java -jar org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar start &
+Run the Kickstarter to start Sling.
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar
-**Note**: the **&** at the end will put the process into the background. Let's
-check if that process is still running:
+Next, open a browser and visit [http://localhost:8080/](http://localhost:8080/).
- $ ps -ef | grep java
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+* The Kickstarter will take some time to start the first time since the Feature Model needs to populate your local
+ Maven repository with any missing artifacts.
+* If you run into any issues, try re-running the Kickstarter with the `-v` option.
-This should return a line like this:
+</div>
- 501 5498 5008 0 1:10PM ttys001 0:20.17 /usr/bin/java -jar org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar start
+### Step 3: Start using Sling
+Click the **Login** link and log in with **admin/admin**.
-You can now use a browser to work with Sling. To get a status on the Sling service
-then do:
- $ java -jar org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar status
+### Step 4: Check the status of Sling
+Open a new terminal window and navigate to the same Kickstarter working directory that
+was used to start Sling.
-Which should return:
+Now, run the Kickstarter JAR again with the `status` command to view the current
+status of your Sling instance.
- /127.0.0.1:52516>status
- /127.0.0.1:52516<OK
- Sent 'status' to /127.0.0.1:52481: OK
- Terminate VM, status: 0
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar status
-To stop it do:
+If your Sling instance is running, you should see output similar to this:
- $ java -jar org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar stop
+ /127.0.0.1:52516>status
+ /127.0.0.1:52516<OK
+ Sent 'status' to /127.0.0.1:52481: OK
+ Terminate VM, status: 0
+If your sling instance is not running, you should see:
-This will then show the status of the process and unix will also print then
-termination of the process:
+ No Apache Sling running at /127.0.0.1:52244
+ Terminate VM, status: 3
+### Step 5: Stop Sling with the Kickstater
- /127.0.0.1:52520>stop
- /127.0.0.1:52520<OK
- Stop Application
- Sent 'stop' to /127.0.0.1:52481: OK
- Terminate VM, status: 0
- mac:sling-kickstart-run schaefa$ [INFO] Framework stopped
+Run the Kickstarter JAR again and specify the `stop` command.
- [1]+ Done java -jar org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar start
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar stop
+Alternatively, you can stop Sling by hitting `<CTRL+C>`.
-### Kickstart Launch options
+## Mission Accomplished
-Finally let's have a look at the launch options:
- $ java -jar org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar -h
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+#### What we learned:
-This will print this:
+* We successfully started Sling with the Kickstarter and had our first
+ glimpse of the Feature Model.
- Usage: java -jar <Sling Kickstarter JAR File> [-hnv] [-a=<address>]
- [-c=<slingHome>] [-f=<logFile>]
- [-i=<launcherHome>]
- [-j=<controlAddress>]
- [-l=<logLevel>] [-p=<port>]
- [-r=<contextPath>]
- [-s=<mainFeatureFile>]
- [-af=<additionalFeatureFile>]...
- [-D=<String=String>]... [COMMAND]
- Apache Sling Kickstart
- [COMMAND] Optional Command for Server Instance Interaction, can be
- one of: 'start', 'stop', 'status' or 'threads'
- -a, --address=<address> the interface to bind to (use 0.0.0.0 for any)
- -af, --additionalFeature=<additionalFeatureFile>
- additional feature files
- -c, --slingHome=<slingHome>
- the sling context directory (default sling)
- -D, --define=<String=String>
- sets property n to value v. Make sure to use this option
- *after* the jar filename. The JVM also has a -D option
- which has a different meaning
- -f, --logFile=<logFile> the log file, "-" for stdout (default logs/error.log)
- -h, --help Display the usage message.
- -i, --launcherHome=<launcherHome>
- the launcher home directory (default launcher)
- -j, --control=<controlAddress>
- host and port to use for control connection in the
- format '[host:]port' (default 127.0.0.1:0)
- -l, --logLevel=<logLevel> the initial loglevel (0..4, FATAL, ERROR, WARN, INFO,
- DEBUG)
- -n, --noShutdownHook don't install the shutdown hook
- -p, --port=<port> the port to listen to (default 8080)
- -r, --context=<contextPath>
- the root servlet context path for the http service
- (default is /)
- -s, --mainFeature=<mainFeatureFile>
- main feature file (file path or URL) replacing the
- provided Sling Feature File
- -v, --verbose the feature launcher is verbose on launch
- Copyright(c) 2020 The Apache Software Foundation.
+</div>
+Did we succeed in making you more curious about the world of Feature Models?
+If you stay with us, you'll learn how to customize Sling by creating your own
+Feature Models.
-Most of the options are the same as for the **Sling Starter** project with these
-two additional options:
+If you still want to learn a bit more about the Kickstarter, stay on this page
+and keep reading.
-* **-s**: allows to specify your own Sling Feature Model / Archive
-* **-af**: allows to add additional Feature Model / Archives (repeat for each feature file)
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
-### Conclusion
+* Next Up: [How to Create a Custom Feature Model Project](/documentation/feature-model/howtos/sling-with-custom-project.html)
+* Back To: [Feature Model Home](/documentation/feature-model/feature-model-overview.html)
-This was s short introduction into the **Sling Kickstart** project to launch Sling
-on your local computer to check it out, develop of test Sling applications.
+</div>
-[Back to the Feature Model Home](/documentation/feature-model/feature-model-overview.md)
+## A couple additional things to explore
-## Addendum: Build from Source
+### Kickstarter commands and options
-To build the Kickstart project from code you need to clone and build both the
-Sling Kickstart Maven Plugin as well as the Sling Kickstart project.
+The generalized command for the Kickstarter is as follows:
-### Clone and Build Kickstart Maven Plugin
+ $ java -jar <jarfile> [options] [command]
-First we need to build the Maven plugin because it is needed to run the IT test
-in the Kickstart Project. So we clone it from GitHub:
+It supports three commands: `stop`, `start` and `status` as well as a number of options. For
+a full list of available options, run the Kickstarter with the `-h` option.
- $ cd <project root folder>
- $ git clone git@github.com:apache/sling-kickstart-maven-plugin.git
- $ cd sling-kickstart-maven-plugin
+| Short Option | Long Option | Description |
+| ------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
+| -a | --address=<address> | Address to bind to (default `0.0.0.0`). |
+| -af | --additionalFeature=<additionalFeature> | Define additional feature files. Use multiple options for multiple features. |
+| -c | --slingHome=<slingHome> | Sling context directory (default `sling`). |
+| -D | --define=<key=value> | Sets property key to value. This is different than the `-D` JVM option. This must come after the jar filename. |
+| -f | --logFile=<logFile> | Log file or "-" for stdout (default `logs/error.log`). |
+| -h | --help | Display usage. |
+| -i | --launcherHome=<launcherHome> | Launcher home directory (default `launcher`). |
+| -j | --control=<controlAddress> | Host and port to use for control connection. Format `[host:]port`.
+| -l | --logLevel=<logLevel> | Initial log level (0..4, FATAL, ERROR, WARN, INFO, DEBUG). |
+| -n | --noShutdownHook | Don't install the shutdown hook. |
+| -p | --port=<port> | Port to listen to (default `8080`). |
+| -r | --context=<contextPath> | Root servlet context path for the HTTP service (default `/`). |
+| -s | --mainFeature=<mainFeatureFile> | Main feature file (file path or URL). This will replace the default file used by Sling. |
+| -v | --verbose | Start the launcher with additional information. |
-Now we can build the project:
- $ mvn clean install
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+For compatibility, most of the options are the same as the
+[Sling Starter](https://github.com/apache/sling-org-apache-sling-starter) project. The
+options below are specific to the Kickstarter.
-### Clone and Build Kickstart Project
+* `-s`: Replaces the main default Sling feature with your own Feature Model.
+* `-af`: Defines additional Feature Models (use multiple `-af` options for multiple features).
-Now we can clone the Kickstart Project:
+</div>
+### Start Sling using --mainFeature
- $ git clone git@github.com:apache/sling-org-apache-sling-kickstart.git
- $ cd sling-org-apache-sling-kickstart
+The real power of the Kickstarter can be seen when you specify your own Feature Model. As an example,
+let's re-run the Kickstarter and specify an external Feature Model.
+We'll start by moving into our `kickstarter` workspace. Then, we'll Stop Sling if it's still running.
+Next, remove the old `conf` and `launcher` directories so that we can start a clean Sling instance.
+Extract the Sling 12 Feature Model file from the Kickstarter JAR. Lastly, start Sling using the Feature Model
+JSON file.
-Now we are ready to build it and then finally run Sling.
+ $ cd kickstarter
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar stop
+ $ rm -rf conf launcher
+ $ jar -xf org.apache.sling.kickstart-0.0.2.jar feature-sling12.json
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar --mainFeature=feature-sling12.json
- mvn clean install
+If you're curious, take a peak at the Feature Model for Sling 12 by opening `feature-sling12.json` in
+your favorite editor.
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
-This will build the project but also run Sling as IT to run the Smoke IT test to
-make sure it is working.
-At the end you will find the file **org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar**
-in the **target** folder of our project. We could run it there but that would wipe
-Sling away whenever we clean the project.
-To avoid this will go back to the project root folder and create folder **sling-kickstart-run**
-folder next to folder **sling-org-apache-sling-kickstart** and copy the JAR file
-there:
+* Next Up: [How to Create a Custom Feature Model Project](/documentation/feature-model/howtos/sling-with-custom-project.html)
+* Back To: [Feature Model Home](/documentation/feature-model/feature-model-overview.html)
- cd ..
- mkdir sling-kickstart-run
- cd sling-kickstart-run
- cp ../sling-org-apache-sling-kickstart/target/org.apache.sling.kickstart-0.0.1-SNAPSHOT.jar .
+</div>
diff --git a/src/main/jbake/content/documentation/feature-model/howtos/sling-with-custom-project.md b/src/main/jbake/content/documentation/feature-model/howtos/sling-with-custom-project.md
new file mode 100644
index 0000000..b1c4c6d
--- /dev/null
+++ b/src/main/jbake/content/documentation/feature-model/howtos/sling-with-custom-project.md
@@ -0,0 +1,215 @@
+title=How to Create a Custom Feature Model Project
+type=page
+status=published
+tags=feature model,sling, kickstarter
+~~~~~~
+
+### About this How-To
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+#### What we'll explore:
+
+* Create a sample Sling bundle project
+* Update the Maven POM to add Feature Model support to the project
+* Launch our sample application with the Kickstarter
+
+#### What you should know:
+
+* Skill Level: Intermediate
+* Environment: Windows/Unix
+* Time: 20 minutes
+
+</div>
+
+* Back To: [How to Start Sling with the Kickstarter](/documentation/feature-model/howtos/kickstart.html)
+* Back Home: [Feature Model](/documentation/feature-model/feature-model-overview.html)
+
+
+### Prerequisites
+
+In order to follow this how-to you'll need the following on your computer:
+
+* Java 8
+* Maven 3
+* Bash shell
+
+
+### What's the Sling Feature Model
+
+The Sling Feature Model provides a robust approach for configuring and assembling OSGi-based applications.
+Here are some of its high-level capabilities:
+
+* Declarative description of an entire application or part of an application
+* Support for aggregating Feature Models into a single Feature Model for simpler packaging and distribution
+* Easy application startup through the Feature Launcher or the Kickstarter
+
+
+### What's a Feature Model project
+
+A Feature Model project is a standard Maven project with the following additional features:
+
+* Sling Feature Maven Plugin
+* Kickstarter launch profile
+
+
+### Step 1: Create a Sling bundle project
+
+
+Let's start by creating a simple Sling project using the traditional Maven [Sling Bundle Archetype](/documentation/development/maven-archetypes.html#sling-jcrinstall-bundle-archetype-1).
+
+ $ mvn -X archetype:generate -DarchetypeGroupId=org.apache.sling -DarchetypeArtifactId=sling-bundle-archetype \
+ -DgroupId=org.apache.sling.example \
+ -DartifactId=feature-model-sample \
+ -Dversion=1.0.0-SNAPSHOT \
+ -Dpackage=org.apache.sling.example
+ $ cd feature-model-sample
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+**Note:** There are plans to introduce a Maven archetype that will create a Maven project with support for Feature Models.
+
+</div>
+
+
+### Step 2: Update the POM
+
+Now, let's update the POM and add a few elements to layer on support for Feature Models.
+
+**1.** Add the following to the `<properties>` element.
+
+ <slingfeature-maven-plugin.version>1.3.4</slingfeature-maven-plugin.version>
+ <sling-kickstart-maven-plugin.version>0.0.2</sling-kickstart-maven-plugin.version>
+ <oak.version>1.26.0</oak.version>
+
+**2.** Add the [Sling Feature Maven Plugin](https://sling.apache.org/components/slingfeature-maven-plugin/plugin-info.html) under `<build>` -> `<plugins>`.
+
+ <plugin>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>slingfeature-maven-plugin</artifactId>
+ <version>${slingfeature-maven-plugin.version}</version>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <id>create-fm</id>
+ <phase>package</phase>
+ <goals>
+ <goal>include-artifact</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>aggregate-configuration</id>
+ <phase>package</phase>
+ <goals>
+ <goal>aggregate-features</goal>
+ </goals>
+ <configuration>
+ <aggregates>
+ <aggregate>
+ <classifier>feature_model_sample</classifier>
+ <filesInclude>**/*.json</filesInclude>
+ <title>Sling Sample Feature Model</title>
+ </aggregate>
+ </aggregates>
+ </configuration>
+ </execution>
+ <execution>
+ <id>install-fm</id>
+ <phase>package</phase>
+ <goals>
+ <goal>attach-features</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+
+
+The Sling Feature Maven Plugin is responsible for creating a Feature Model JSON file for your project. The only pieces that change from
+project to project are the `<classifier>` and `<title>` element values. Set these values to something descriptive for your project.
+The classifier value will be used as part of the Feature Model JSON filename:
+`target/slingfeature-tmp/feature-`_classifier_`.json`
+
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+Make a note of `target/slingfeature-tmp/feature-feature_model_sample.json` as this path will be used in the next section.
+
+</div>
+
+**3.** Add a Maven profile called `launch` under `<project>` -> `<profiles>`.
+
+ <profile>
+ <id>launch</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>sling-kickstart-maven-plugin</artifactId>
+ <version>${sling-kickstart-maven-plugin.version}</version>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <id>start-sling</id>
+ <phase>install</phase>
+ <goals>
+ <goal>start</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <launchpadDependency>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>org.apache.sling.kickstart</artifactId>
+ <version>0.0.3-SNAPSHOT</version>
+ </launchpadDependency>
+ <parallelExecution>false</parallelExecution>
+ <keepLaunchpadRunning>true</keepLaunchpadRunning>
+ <servers>
+ <server>
+ <port>8080</port>
+ <controlPort>8081</controlPort>
+ <additionalFeatureFile>
+ target/slingfeature-tmp/feature-feature_model_sample.json
+ </additionalFeatureFile>
+ <debug>true</debug>
+ </server>
+ </servers>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+
+
+This profile is responsible for starting your application using the Kickstarter. Simply, set the `<additionalFeatureFile>` to the file
+in your target directory that contains your application's Feature Model JSON.
+
+### Step 4: Launch your application
+
+
+ $ mvn clean install -Plaunch
+
+Now, log into Sling and visit the System Console. You should see your bundle (`feature-model-sample`) listed.
+
+
+## Mission Accomplished
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+#### What we learned:
+
+* How to update a traditional Sling bundle project to support Feature Models
+* How to start your project with the Kickstarter
+
+</div>
+
+Well, that was fun. We'll revisit this sample project soon, But first, let's see how the Feature Model can help us handle
+complex application configurations. In the next section, we'll take a look at the Composite NodeStore and how to configure
+it with the Feature Model.
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+* Next Up: [How to Create a Sling Composite Node Store](/documentation/feature-model/howtos/create-sling-composite.html)
+* Back To: [Feature Model Home](/documentation/feature-model/feature-model-overview.html)
+
+</div>
diff --git a/src/main/jbake/content/documentation/feature-model/howtos/start-sling-feature-launcher.md b/src/main/jbake/content/documentation/feature-model/howtos/start-sling-feature-launcher.md
new file mode 100644
index 0000000..c833c84
--- /dev/null
+++ b/src/main/jbake/content/documentation/feature-model/howtos/start-sling-feature-launcher.md
@@ -0,0 +1,155 @@
+title=Start Sling Feature Model with Feature Launcher
+type=page
+status=published
+tags=feature model,sling,feature launcher
+~~~~~~
+
+### How-To Overview
+
+<div style="background: lightblue;">
+
+* What will you learn:
+ * We are starting up Apache Sling with the Feature Launcher directly
+
+* Time: 15 minutes
+* Skill Level: Beginner
+* Environment: Windows/Unix
+</div>
+
+* Back To: [Feature Model Home](/documentation/feature-model/feature-model-overview.html)
+
+### Prerequisites
+
+In order to follow through this HowTo you need the following on your computer:
+
+* Java 8
+* Command Line with Bash
+
+### What is the Feature Launcher
+
+The [Feature Launcher](https://github.com/apache/sling-org-apache-sling-feature-launcher) is
+taking a Feature Model, resolves all the dependencies and launches the Feature Model ontop
+of an OSGi container.
+Some of the Feature Models are handled by extensions which have to be provided to the Feature
+Launcher at startup time.
+
+### Explanation on what will happen
+
+### Step 1: Obtain the Feature Launcher
+
+First we create the project folder:
+
+ $ cd <project root folder>
+ $ mkdir sling-feature-launcher
+ $ cd sling-feature-launcher
+ $ curl https://repository.apache.org/content/groups/public/org/apache/sling/org.apache.sling.feature.launcher/1.1.4/org.apache.sling.feature.launcher-1.1.4.jar \
+ org.apache.sling.feature.launcher-1.1.4.jar
+
+
+### Step 2: Optional: Obtain Extensions
+
+Extension are optional pieces that can added to the Feature Launcher to handle additional media like here
+the Content Extension.
+
+Going to the [Sling Folder](https://repository.apache.org/content/groups/public/org/apache/sling/)
+you can select the desired extension.
+In this Howto we are going to use the Content Extension:
+
+ $ cd <project root folder>
+ $ cd sling-feature-launcher
+ $ curl https://repository.apache.org/content/groups/public/org/apache/sling/org.apache.sling.feature.extension.content/1.0.6//org.apache.sling.feature.extension.content-1.0.6.jar \
+ org.apache.sling.feature.extension.content-1.0.6.jar
+
+
+### Step 3: Obtain the Sling Feature Model
+
+The Sling Feature Model can be taken from the [Sling Kickstart](https://github.com/apache/sling-org-apache-sling-kickstart#build)
+project. Just got the folder /src/main/resources in the GitHub project page and then download the
+[feature-sling12.json](https://github.com/apache/sling-org-apache-sling-kickstart/blob/master/src/main/resources/feature-sling12.json)
+file.
+
+### Step 5: Create Custom Log Settings
+
+This step will create a Configuration Feature Model so that we can adjust the Log settings of Sling's
+main log (error.log).
+**Note**: this can be applied to any configuration inside the Sling12 Feature Model file.
+
+Create a Configuration Feature Model file:
+1. Create a file called **feature-config-sling12.json** (name does not matter)
+2. Add the content from below
+3. Save it
+
+Feature Model Config file:
+
+ {
+ "id":"org.apache.sling:config.local:slingosgifeature:sling12-config:0.0.1-SNAPSHOT",
+ "configurations": {
+ "org.apache.sling.commons.log.LogManager": {
+ "org.apache.sling.commons.log.level":"debug",
+ "org.apache.sling.commons.log.file":"logs/test2.log"
+ }
+ }
+ }
+
+**Note**: this will only have the properties that we want to change. To remove a property from the
+Sling Feature Model then add the entire configuration (copy it from the Sling Feature Model file)
+and then use the option **USE_FIRST** instead of **MERGE_FIRST** in the **-CC** option.
+
+### Step 4: Launch Sling
+
+Execute
+
+ java \
+ -Dorg.osgi.service.http.port=8170 \
+ -Dorg.apache.felix.http.host=localhost \
+ -cp org.apache.sling.feature.extension.content-1.0.6.jar
+ -jar org.apache.sling.feature.launcher-1.1.4.jar \
+ -f feature-config-sling12.json \
+ -f feature-sling12.json \
+ -CC "org.apache.sling.commons.log.LogManager=MERGE_FIRST" \
+ -c artifacts
+
+
+This will bring up Sling on port 8170 just fine with the adjusted Sling logging.
+
+
+
+Adjusted Logging:
+
+
+
+## Mission Accomplished
+
+* Next Up: [Custom Feature Project with Sling](/documentation/feature-model/howtos/sling-with-custom-project.html)
+* Back To: [Feature Model Home](/documentation/feature-model/feature-model-overview.html)
+
+## Addendum
+
+### Configuration Class Overrides
+
+The [Feature Launcher](https://github.com/apache/sling-org-apache-sling-feature-launcher) requires
+the user to define Configuration Class Overrides if provided Feature Models' Configuration contain
+conflicting configurations.
+The caller must provide it with the **-CC** option with a key-value pair separted by an
+equal sign. These are examples:
+
+* Merge Log Manager and take the first configuration:
+ * org.apache.sling.commons.log.LogManager=MERGE_FIRST
+* Merge any configuration under 'org.apache.sling.commons.log' and take the last
+ * org.apache.sling.commons.log.*=MERGE_LATEST
+* Take the first configuration of any file
+ * *=USE_FIRST
+
+These are the available actions:
+
+* PROPERTY_CLASH: if conflicting then fail
+* USE_FIRST: use first provided configuration
+* USE_LATEST: use the last configuration
+* MERGE_FIRST: merge first provided configuration (whatever is not provided is taken from the later)
+* MERGE_LATEST: merge last provided configuration (whatever is not provided is taken from the former)
+
+These are the available configuration pattern:
+
+* fully qualified path: applies on to the configuration with that path
+* prefix ending in a *: applies to all configurations with the given prefix
+* *: all configurations
