Merge pull request #48 from headwirecom/feature/SLING-9522
SLING-9522 - Added how-to series for the Feature Model
diff --git a/src/main/jbake/content/documentation/development/feature-model.md b/src/main/jbake/content/documentation/development/feature-model.md
index 6f99012..822fdf1 100644
--- a/src/main/jbake/content/documentation/development/feature-model.md
+++ b/src/main/jbake/content/documentation/development/feature-model.md
@@ -11,4 +11,76 @@
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.
+
+See the [Feature Model How-To Guide](/documentation/feature-model/feature-model-overview.html) for practical examples.
+
+### 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
new file mode 100644
index 0000000..3d4b748
--- /dev/null
+++ b/src/main/jbake/content/documentation/feature-model/feature-model-overview.md
@@ -0,0 +1,33 @@
+title=Feature Model How-To Guide
+type=page
+status=published
+tags=featuremodel,osgi,project,guide,howtos
+~~~~~~
+
+### About this How-To
+
+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.
+
+
+## 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)
+
+
+## Related 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)
+* [Feature Extensions](https://github.com/apache/sling-org-apache-sling-feature/blob/master/docs/extensions.md)
+* [Feature Archive](https://github.com/apache/sling-org-apache-sling-feature/blob/master/docs/feature-archives.md)
+* [Feature References](https://github.com/apache/sling-org-apache-sling-feature/blob/master/docs/feature-ref-files.md)
+* [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..51056d4
--- /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=featuremodel,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;">
+
+**Note:** These instructions will be updated to use the binary release once an official Sling Feature Model JSON file is released.
+
+</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..b5f9a3b
--- /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=featuremodel,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
new file mode 100644
index 0000000..e4b1602
--- /dev/null
+++ b/src/main/jbake/content/documentation/feature-model/howtos/kickstart.md
@@ -0,0 +1,220 @@
+title=How to Start Sling with the Kickstarter
+type=page
+status=published
+tags=featuremodel,sling,kickstarter
+~~~~~~
+
+### About this How-To
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+#### What we'll explore:
+
+* We'll start Sling with the Kickstart Launcher (a.k.a the kickstarter) and explore the Feature Model
+
+#### 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 this how-to you'll need the following on your computer:
+
+* Java 8
+* Bash shell
+
+### What's the Kickstarter
+
+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.
+
+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
+
+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.
+
+Let's try this out!
+
+### Step 1: Download the Kickstarter
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00;">
+
+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>
+
+Visit the [Apache Sling Downloads](https://sling.apache.org/downloads.cgi) page and download the _Kickstart Project_
+bundle.
+
+Then, create a working directory for the Kickstarter and copy the bundle to this location. You can name this
+directory anything you like.
+
+ $ mkdir kickstarter
+ $ cd kickstarter
+ $ cp /some/download/path/org.apache.sling.kickstart-0.0.2.jar .
+
+### Step 2: Start Sling with the Kickstarter
+
+<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.
+
+</div>
+
+Run the Kickstarter to start Sling.
+
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar
+
+Next, open a browser and visit [http://localhost:8080/](http://localhost:8080/).
+
+<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.
+
+</div>
+
+### Step 3: Start using Sling
+
+Click the **Login** link and log in with **admin/admin**.
+
+
+### 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.
+
+Now, run the Kickstarter JAR again with the `status` command to view the current
+status of your Sling instance.
+
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar status
+
+
+If your Sling instance is running, you should see output similar to this:
+
+ /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:
+
+ No Apache Sling running at /127.0.0.1:52244
+ Terminate VM, status: 3
+
+### Step 5: Stop Sling with the Kickstater
+
+Run the Kickstarter JAR again and specify the `stop` command.
+
+ $ java -jar org.apache.sling.kickstart-0.0.2.jar stop
+
+Alternatively, you can stop Sling by hitting `<CTRL+C>`.
+
+## Mission Accomplished
+
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+#### What we learned:
+
+* We successfully started Sling with the Kickstarter and had our first
+ glimpse of the Feature Model.
+
+</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.
+
+If you still want to learn a bit more about the Kickstarter, stay on this page
+and keep reading.
+
+<div style="background: #cde0ea; padding: 14px; border-left: 10px solid #f9bb00; margin-bottom: 1em;">
+
+* 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)
+
+</div>
+
+## A couple additional things to explore
+
+### Kickstarter commands and options
+
+The generalized command for the Kickstarter is as follows:
+
+ $ java -jar <jarfile> [options] [command]
+
+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.
+
+
+| 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. |
+
+
+<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.
+
+* `-s`: Replaces the main default Sling feature with your own Feature Model.
+* `-af`: Defines additional Feature Models (use multiple `-af` options for multiple features).
+
+</div>
+
+### Start Sling using --mainFeature
+
+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.
+
+ $ 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
+
+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;">
+
+* 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)
+
+</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..e74e101
--- /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=featuremodel,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>
