src/main/jbake/content/documentation/the-sling-engine/the-sling-launchpad.md

title=The Sling Launchpad type=page status=published tags=launchpad,launchers

[TOC]

This tries to explain how exactly the Sling Launchpad works, what constitutes the Sling Launchpad and how you can use the Sling Launchpad to custom create you Sling launchers. For a view behind the scenes of the Sling Launchpad Base module (the actual launcher) you might want to refer to the [Embedding Sling](/documentation/development/embedding-sling.html) page.

## Sling Home

Since Sling requires some space on the filesystem to store various files Sling has to know where this filesystem space is located.

The following is a list of uses for the Sling Home directory:

* `sling.properties` -- The main configuration file used by Sling to launch the framework. It mainly contains OSGi framework configuration and initial configuration for some bundles. This file is read on each startup of *Launcher JAR*. That is, changes to this file require a restart of the *Launcher JAR*.
* `org.apache.sling.launchpad.base.jar` -- This is the *Launcher JAR* file used by the Standalone Application or the Web Application to start the OSGi Framework. This file is initially placed when first starting Sling and may later be updated by updating the system bundle with a new *Launcher JAR*.
* `felix` -- The directory into which the Apache Felix Framework places the bundles, which have been installed into the system. This does generally not need to be touched.
* `config` -- The directory into which the Apache Felix Configuration Admin Service stores the configurationes. Do not change any files in this directory, since changes will not generally be picked up.
* `jackrabbit` -- The directory in which the Apache Jackrabbit JCR repository is started ( only applicable when using Apache Jackrabbit 2.x ). This is only available for Sling Launchpad 7 or older. Amongst other things this also contains the Jackrabbit configuration file `repository.xml`. You may modify this file, but don't forget to restart the Embedded Jackrabbit Repository bundle after doing this.
* `oak` - The directory in which the Apache Jackrabbit Oak JCR Repository is started ( only applicable when using Apache Jackrabbit Oak with the SegmentNodeStoreBackend ). This is only available for Sling Launchpad 8 or newer.
* `logs` -- Contains the log files generated by Sling. By default this contains the error.log and its rotated generations.

## Command Line Options

The Java Standalone Application supports a number of command line options, which influence the operation of the launch process.

| Option | Argument | Description |
|---|---|---|
| `start` | (-) | Open a TCP/IP server socket when starting Sling. Uses option `-j` to define the local socket address. |
| `status` | (-) | Check whether a (remote) Sling application is running. Uses option `-j` to define the address of the Sling instance to check. Note, that the Sling application terminates after checking for the (remote) Sling status. |
| `stop` | (-) | Stop a (remote) Sling application is running. Uses option `-j` to define the address of the Sling instance to stop. Note, that the Sling application tesrminates after stopping the (remote) Sling instance. |
| `-j` | [ host ":" ] port | The socket address to listen on for control connections (`start` or to use as the remote endpoint for the control connection (`status` and `stop`. If this parameter has no arguments or is not specified, the address defaults to any free port on localhost/127.0.0.1. If only the port is specified localhost/127.0.0.1 is used as the host part of the address. |
| `-c` | slinghome | The directory in which Sling locates its initial configuration file `sling.properties` and where files of Sling itself such as the Apache Felix bundle archive or the JCR repository files are stored. This defaults to the `sling` folder in the current working directory. This is the value which is commonly refered to as `$\{sling.home}.`
| `-i` | launchpadhome | The launchpad directory. If not set, this is the same as `$\{sling.home}.` (since Sling Launchpad 2.4.0) |
| `-l` | loglevel | Sets the initial loglevel as an integer in the range 0 to 4 or as one of the well known level strings `ERROR`, `WARN`, `INFO`, or `DEBUG`. This option overwrites the `org.apache.sling.osg.log.level` setting the `sling.properties` file. The default is `INFO`. |
| `-f` | logfile | The log file to use or `-` to log to standard out. This option overwrites the `org.apache.sling.osg.log.file` setting in the `sling.properties` file. The default is `$\{sling.home}/logs/error.log`. |
| `-a` | address | The interfact to bind to (use 0.0.0.0 for any). This option overwrites the `org.apache.felix.http.host` setting in the `sling.properties` file and requires the embedded Http Service implementation to honor this property. (supported since Sling Launchpad 2.4.0) |
| `-p` | port | The port to listen (default 8080) to handle HTTP requests. This option overwrites the `org.osgi.service.http.port` setting in the `sling.properties` file. |
| `-r` | path | The root servlet context path for the Http Service (default is /). This option overwrites the `org.apache.felix.http.context_path` setting in the `sling.properties` file and requires the embedded Http Service implementation to honor this property. (since Sling Launchpad 2.4.0) |
| `-D` | n=v | Sets the property `n` to the value `v`. This option can be added repeatedly setting additional properties. Any property set in this manner overwrites same named properties in the `sling.properties` file. (since Sling Launchpad 2.4.0) |
| `-n` | (-) | Don't install the shutdown hook. See [Shutdown Hook](#shutdown-hook) below. (since Sling Launchpad 2.5.2) |
| `-h` | (-) | Prints a simple usage message listing all available command line options. |

The Sling Standalone application looks for a definition of the `sling.home` setting in the following locations in order of precendence:

1. The `-c` command line option
1. The `sling.home` system property
1. The `SLING_HOME` environment variable
1. If none of the above resolves to a non-null value, the default value of `sling` is assumed

### Control Port

When starting the Sling Standalone Application with the `start` command line option, a TCP control port is opened to receive simple commands which allow for stopping an instance and getting thread dumps.

Currently supported commands are

* `stop` to stop the Sling instance
* `status` to get the instance status (OK or STOPPING)
* `threads` to get a thread dump

For the Whole Truth about this functionality see the [ControlListener class source code](https://github.com/apache/sling-org-apache-sling-launchpad-base/blob/master/src/main/java/org/apache/sling/launchpad/app/ControlListener.java).

The interface and port is configurable with the `-j` command line option. The actual address and port used are written to the `$\{sling.home}/conf/controlport` file. So technically the `-j` option is not required for the `status` and `stop` operations because the port information can be read from that file.

Note that using a control connection for the Sling Standalone Application presents a potential security issue. For this reason the following defaults apply:

* The server side socket for a running Sling Standalone Application is not created by default, but only if the application is started with the `start` command line option.
* The default control port configuration is `localhost/127.0.0.1` meaning that the socket is only accessible from the same system as the Sling Standalone Application is running on.
* A nonce, followed by a space character, must be used as a prefix for every command sent to the control port. This nonce is generated by Sling at startup and also written to the `controlport` file mentioned above.

For additional security, do not allow the control port to be opened on an externally visible network interface and strictly restrict access to the Sling installation folder (`${sling.home}`).

Here's an example session where a Sling Standalone Application is started with the control port active:

$ java -jar target/org.apache.sling.starter-${sling_releaseVersion}.jar start
05.04.2016 11:50:45.003 *INFO * [main] Setting sling.home=sling (default)
05.04.2016 11:50:45.006 *INFO * [main] Starting Apache Sling in /foo/sling/launchpad/builder/sling
...
05.04.2016 11:50:45.012 *INFO * [Apache Sling Control Listener@/127.0.0.1:59239] Apache Sling Control Listener started
...

And stopped using its control port, from another terminal:

$ cat sling/conf/controlport
127.0.0.1:59239
mdsryh1k5fpcgvm7suqnckxkr7fvluzv

$ telnet 127.0.0.1 59239
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

mdsryh1k5fpcgvm7suqnckxkr7fvluzv stop

OK
Connection closed by foreign host.

### Shutdown Hook

By default the Sling Launchpad standalone application installs a Shutdown Hook with the Java Runtime to make sure the framework is properly
terminated in case of a Java termination. In some situations or setups you want to control shutdown of Sling yourselves, so Sling supports a command
line option `-n` to prevent the installation of a shutdown hook.

Apart from the command line option, the `sling.shutdown.hook` system property is also supported: If this property is set to `true` or is not set at all
the shutdown hook is installed as expected. If the property is set to anything other than `true`, e.g. `false`, the shutdown hook is not installed.

If you are embedding the Sling Launchpad application's `Main` class, the `sling.shutdown.hook` property can also be set as a member of the `props` map
handed to the `Main` constructor.

## Servlet Parameters

The Web Application does not require specific servlet parameters. Those which are specified are used to overwrite any properties with the same name from the `sling.properties` file. One exception to this rule is the `sling.home` parameter, which is used to set the value of the `sling.home` property. If no parameter with this name is defined the Sling home directory is derived from the context path at which the Sling Web Application is registered.

The `sling.home` folders for Sling Web Applications without the `sling.home` servlet parameter are all located in the `sling` folder in the current working directory as reported by the `user.dir` system property. The name of the actual directory is derived from the Web Application Context Path by replacing all slash characters `/` by underscore characters `_`. For the root context a single underscore character `_` is used.

Examples:

| Servlet Context | Default `sling.home` |
|---|---|
| *root* | `sling/_` |
| `/sling` | `sling/_sling` |
| `/sling/instance1` | `sling/_sling/instance1` |

Starting with Launchpad Base 2.2.2 the fixed prefix `sling` is configurable with the `sling.home.prefix` system property. If this property is set the value used as the prefix.

Examples: Assume the `sling.home.prefix` system property is set to `/var/sling`

| Servlet Context | Default `sling.home` |
|---|---|
| *root* | `/var/sling/_` |
| `/sling` | `/var/sling/_sling` |
| `/sling/instance1` | `/var/sling/_sling/instance1` |

## sling.properties

The `sling.properties` file contains the initial setup of the Sling Application and the OSGi framework. Some of the parameters are required and should not be modified without a very good reason. Some parameters may be freely modified to your needs. Please see the inlined comment in the `sling.properties` file installed when Sling is first started.

One thing to note is, that the `sling.properties` file is a simple Java Properties file with support for property references. That is, the value of properties may refer other property values by means of the well known `${name}` notation. Such property references may even be nested as in

java.packages=${jre-${java.specification.version}}

## Components

The Sling Launchapd consists of *Launchbad Base* project and three additional projects which ultimately create a Standalone Java Application and a Web Appliction with standard parts of Sling.

### Launchpad Base

The *Launchpad Base* projects creates the following artifacts, which are required in actual setups to get a Sling application:

* *Launcher JAR* -- The primary artifact of the Base project contains the actual support to launch the Apache Felix OSGi Framework and install bundles, which are packaged with the application. It also contains the Apache Felix Framework together with the OSGi R4.1 Core and Compendium libraries as well as the Equinox HttpService bridge and the Servlet API.

* *App JAR* -- The secondary artifact with classifier *app* is a minimal Standalone Java Application which may be started by simply typing

$ java -jar org.apache.sling.launchpad.base-app.jar

* *Web App Archive* -- The secondary artifact with classifier *webapp* is a minimal Web Application, which may simply be deployed into your favirourite servlet container, provided it supports at least Servlet API 2.4.

* *Source JAR* -- The secondary artifact with the classifier *sources* is simple the source of the *Launchpad Base* project.

To build a very basic Sling launcher, the *Launchpad Base* is actually all you need. But to really glue this together and get a usable system, some more work is required. Lets see how the additionaly projects *Launchpad Bundles*, *Launchpad App*, and *Launchpad WebApp* get to that.

### Launchpad App and Launchpad WebApp

The *Launchpad App* and *Launchpad WebApp* bundles are actually projects which just glue together artifacts from the Launchpad projects. There is nothing special about them. Here's what is done:

* Take the appropriate secondary artifact from the *Launchpad Base* project: *app* for the Standalone Java Application or *webapp* for the Web Application and unpack
* Take the *Launchpad Base* primary artifact and place it under the name `org.apache.sling.launchpad.base.jar` into the `resources` folder
* Copies the list of artifacts defined in the [Provisioning model](/documentation/development/slingstart.html)
* Finally pack all together into a single big JAR or WAR file

The artifacts can be configured to use different JCR repository implementations, based on the value of the `-Dsling.run.modes` property. The following run modes are available for the 8 version of the Sling Launchpad:

* `oak`: configures and starts up an Apache Jackrabbit Oak repository implementation with a SegmentNodeStore ( TarMK ) implementation
* `oak,oak_mongo`: configures and starts up an Apache Jackrabbit Oak repository implementation with a DocumentNodeStore implementation connected to a MongoDB database. The default configuration points to a MongoDB instance at mongodb://localhost:27017 and a database named sling.

That's it. The resulting artifact may be directly used to launch the Standalone Java Application or may directly be deployed into any Servlet API 3.0 (or later) compliant servlet container.