Author: kwin
Date: Wed May 11 16:33:40 2016
New Revision: 1743395
URL: http://svn.apache.org/viewvc?rev=1743395&view=rev
Log:
extend documentation on starting servers with the slingstart-maven-plugin
Modified:
sling/site/trunk/content/documentation/development/slingstart.mdtext
Modified: sling/site/trunk/content/documentation/development/slingstart.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/slingstart.mdtext?rev=1743395&r1=1743394&r2=1743395&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development/slingstart.mdtext
(original)
+++ sling/site/trunk/content/documentation/development/slingstart.mdtext Wed
May 11 16:33:40 2016
@@ -6,7 +6,7 @@ The Apache Sling provisioning model is a
The model is describing an instance, it is not directly related to any
particular tooling or packaging/provisioning vehicle.
-For Apache Maven users, the slingstart-maven-plugin uses the model to create
an executable application and/or a web application based on the model. Sling's
Launchpad is defined using the model and built by this Maven plugin.
+For Apache Maven users, the `slingstart-maven-plugin` uses the model to create
an executable application and/or a web application based on the model. Sling's
Launchpad is defined using the model and built by this Maven plugin.
## The Model
@@ -196,10 +196,10 @@ Notice that this definition only support
## Slingstart and Slingfeature projects
-The slingstart-maven-plugin introduces two new packaging types:
+The `slingstart-maven-plugin` introduces two new packaging types:
-* slingstart : This type requires a model at src/main/provisioning. It reads
all text files in that directory and merges them in alphabetical order. The
resulting artifact is a runnable jar. The assembled model is also attached to
the project artifacts.
-* slingfeature : This type requires a model at src/main/provisioning. It reads
all text files in that directory and merges them in alphabetical order and
creates a merged model which is the final artifact of this project.
+* `slingstart` : This type requires a model at src/main/provisioning. It reads
all text files in that directory and merges them in alphabetical order. The
resulting artifact is a runnable jar. The assembled model is also attached to
the project artifacts.
+* `slingfeature` : This type requires a model at src/main/provisioning. It
reads all text files in that directory and merges them in alphabetical order
and creates a merged model which is the final artifact of this project.
A model can reference other slingstart or slingfeature artifacts. When such an
artifact is reference, the type needs to be specified, for example:
@@ -281,18 +281,36 @@ When the merge directive is used, the co
If a merged configuration redefines a property that already exists, it
overwrites it, so the last configuration supplied in a merge wins.
-## slingstart-maven-plugin
+## Starting a server
-### Starting a server
+Use the goal with name `start` to start one or multiple servers. The goal is
bound by default to the [`pre-integration-test` lifecycle
phase](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference).
The launchpad JAR used to start the server is being looked up from the
following locations:
-Use the goal with name `start` to start one or multiple servers. The goal is
bound by default to the [`pre-integration-test` lifecycle
phase](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference).
+1. the file path given in the configuration field `launchpadJar` or parameter
`launchpad.jar`
+2. the slingstart artifact being referenced in the configuration element
`launchpadDependency`
+3. the artifact being created through the Maven project itself (only if the
current project has pacakaging `slingstart`)
+4. the first dependency of type `slingstart`
+
+The server itself is configured within an element `server` below the
configuration element `servers`. It supports the following configuration
settings
+
+Name | Type | Description | Default Value | Mandatory
+---- | ---- | ----------- | ------------- | ---------
+port | String | The port on which the server is listening for HTTP
requests. Arbitrary if not set. | - | no
+id | String | The instance id for this server. If not set the id is
automatically generated from the run modes and the port. | - | no
+runmode | String | The comma-separated list of [run modes]({{
refs.sling-settings-org-apache-sling-settings.path }}#run-modes) to be set for
this server. Those will be set in addition to the ones being defined by the
underlying model. | - | no
+contextPath | String | The context path. If not set then Sling is deployed in
the root context. | - | no
+controlPort | String | The TCP [control port]({{ refs.the-sling-launchpad.path
}}#control-port) on which the server is listening for control commands.
Arbitrary if not set. | - | no
+instances | int | The number of instances which should be created from this
server element. In this case the configuration acts as template. The port and
controlPort for all servers being generated from this configuration are random
(except for the first server). | 1 | no
+folder | String | The folder from where to start Sling. If not set is a folder
in the project's build directory named like the `id`. | - | no
+vmOpts | String | The JVM options to use. | `-Xmx1024m -XX:MaxPermSize=256m
-Djava.awt.headless=true` | no
+opts | String | Additional application options. | - | no
+debug | String | See below for an explanation. | - | no
-#### Debugging
+### Debugging
-Since version 1.2.0 of this plugin it is possible to easily start a Sling
server in debug mode
([SLING-4677](https://issues.apache.org/jira/browse/SLING-4677)). For that you
either configure the property `debug` inside you server configuration in the
pom.xml accordingly or by using the parameter `Dlaunchpad.debug`. Both values
can either be `true` (in which case the [JDWT
options](http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation)
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000` are
appended to the VM options) or just some arbitrary string defining JDWT options.
+Since version 1.2.0 of this plugin it is possible to easily start a Sling
server in debug mode
([SLING-4677](https://issues.apache.org/jira/browse/SLING-4677)). For that you
either configure the property `debug` inside you server configuration in the
pom.xml accordingly or by using the parameter `Dlaunchpad.debug`. Both values
can either be `true` (in which case the [JDWP
options](http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation)
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000` are
appended to the VM options) or just some arbitrary string defining debugging
options.
In case both are used the parameter `Dlaunchpad.debug` takes precedence.
-### Stopping a server
+## Stopping a server
Use the goal with name `stop` to stop one or multiple servers. The goal is
bound by default to the [`post-integration-test` lifecycle
phase](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference).
