Update deployment documentation

Change the "cloud deployment" section to cover general "deployment" and
add documentation for init.d and systemd support.

Closes gh-1117

spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc

@@ -383,6 +383,18 @@ want the other Boot features but not this one)
 |`customConfiguration`
 |The name of the custom configuration which is used to populate the nested lib directory
  (without specifying this you get all compile and runtime dependencies).
+
+|`executable`
+|Boolean flag to indicate if jar files are fully executable on Unix like operating
+ systems. Defaults to `true`.
+
+|`embeddedLaunchScript`
+|The embedded launch script to prepend to the front of the jar if it is fully executable.
+ If not specified the 'Spring Boot' default script will be used.
+
+|`embeddedLaunchScriptProperties`
+|Additional properties that to be expanded in the launch script. The default script
+ supports a `mode` property which can contain the values `auto`, `service` or `run`.
 |===
 
 

spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc → spring-boot-docs/src/main/asciidoc/deployment.adoc

-[[cloud-deployment]]
-= Deploying to the cloud
+[[deployment]]
+== Deploying Spring Boot applications
 
 [partintro]
 --
+Spring Boot's flexible packaging options provide a great deal of choice when it comes to
+deploying your application. You can easily deploy Spring Boot applications to a variety
+of cloud platforms, to a container images (such as Docker) or to virtual/real machines.
+
+This section covers some of the more common deployment scenarios.
+--
+
+
+
+[[cloud-deployment]]
+== Deploying to the cloud
+
 Spring Boot's executable jars are ready-made for most popular cloud PaaS
 (platform-as-a-service) providers. These providers tend to require that you
 "`bring your own container`"; they manage application processes (not Java applications
@@ -23,12 +35,11 @@ to run packaged within it.
 In this section we'll look at what it takes to get the
 <<getting-started.adoc#getting-started-first-application, simple application that we
 developed>> in the "`Getting Started`" section up and running in the Cloud.
---
 
 
 
 [[cloud-deployment-cloud-foundry]]
-== Cloud Foundry
+=== Cloud Foundry
 Cloud Foundry provides default buildpacks that come into play if no other buildpack is
 specified. The Cloud Foundry https://github.com/cloudfoundry/java-buildpack[Java buildpack]
 has excellent support for Spring applications, including Spring Boot.  You can deploy
@@ -102,7 +113,7 @@ able to hit the application at the URI given, in this case
 
 
 [[cloud-deployment-cloud-foundry-services]]
-=== Binding to services
+==== Binding to services
 By default, metadata about the running application as well as service connection
 information is exposed to the application as environment variables (for example:
 `$VCAP_SERVICES`). This architecture decision is due to Cloud Foundry's polyglot
@@ -142,7 +153,7 @@ auto-configuration support and a `spring-boot-starter-cloud-connectors` starter
 
 
 [[cloud-deployment-heroku]]
-== Heroku
+=== Heroku
 Heroku is another popular PaaS platform. To customize Heroku builds, you provide a
 `Procfile`, which provides the incantation required to deploy an application. Heroku
 assigns a `port` for the Java application to use and then ensures that routing to the
@@ -225,7 +236,7 @@ Your application should now be up and running on Heroku.
 
 
 [[cloud-deployment-openshift]]
-== Openshift
+=== Openshift
 https://www.openshift.com/[Openshift] is the RedHat public (and enterprise) PaaS solution.
 Like Heroku, it works by running scripts triggered by git commits, so you can script
 the launching of a Spring Boot application in pretty much any way you like as long as the
@@ -288,14 +299,85 @@ run the app.
 
 
 [[cloud-deployment-gae]]
-== Google App Engine
+=== Google App Engine
 Google App Engine is tied to the Servlet 2.5 API, so you can't deploy a Spring Application
 there without some modifications. See the <<howto.adoc#howto-servlet-2-5, Servlet 2.5 section>>
 of this guide.
 
 
+[[deployment-service]]
+== Installing Spring Boot applications
+In additional to running Spring Boot applications using `java -jar` it is also possible
+to execute applications directly on Unix systems (Linux, OSX, FreeBSD etc). This makes it
+very easy to install and manage Spring Boot applications in common production
+environments. As long as you are generating '`fully executable`' jars from your build, and
+you are not using a custom `embeddedLaunchScript`, the following techniques can be used.
+
+
+
+=== Unix/Linux services
+Spring Boot application can be easily started as Unix/Linux services using either `init.d`
+or `systemd`.
+
+
+
+==== Installation as a init.d (system v) service
+The default executable script that is embedded into Spring Boot executable jars will act
+as an `init.d` script when it is symlinked to `/etc/init.d`. The standard `start`, `stop`,
+`restart` and `status` commands can be used. The script supports the following features:
+
+* Starts the services as the user that owns the jar file
+* Tracks application PIDs using `/var/run/<appname>.pid`
+* Writes console logs to `/var/log/<appname>.log`
+
+Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a
+Spring Boot application as an `init.d` service simply create a symlink:
+
+[indent=0,subs="verbatim,quotes,attributes"]
+----
+	$ sudo link -s /var/myapp/myapp.jar /etc/init.d/myapp
+----
+
+TIP: It is advisable to create a specific user account to run you application. Ensure
+that you have set the owner of the jar file using `chown` before installing your service.
 
-[[cloud-deployment-whats-next]]
+Once installed, you can start and stop the service in the usual way. You can also flag the
+application to start automatically using your standard operating system tools. For example,
+if you use Debian:
+
+[indent=0,subs="verbatim,quotes,attributes"]
+----
+	$ update-rc.d myapp defaults <priority>
+----
+
+
+
+==== Installation as a systemd service
+Systemd is the successor to `init.d` scripts, and now being used by many many modern Linux
+distributions. Although you can continue to use `init.d` script with `systemd`, it is also
+possible to launch Spring Boot applications using `systemd` '`service`' scripts.
+
+For example, to run a Spring Boot application installed in `var/myapp` you can add the
+following script in `/etc/systemd/system/myapp.service`:
+
+[indent=0]
+----
+	[Unit]
+	Description=myapp
+	After=syslog.target
+
+	[Service]
+	ExecStart=/var/myapp/myapp.jar
+
+	[Install]
+	WantedBy=multi-user.target
+----
+
+TIP: Remember to change the `Description` and `ExecStart` fields for your application.
+
+
+
+[[deployment-whats-next]]
 == What to read next
 Check out the http://www.cloudfoundry.com/[Cloud Foundry], https://www.heroku.com/[Heroku]
 and https://www.openshift.com[Openshift] web sites for more information about the kinds of
@@ -307,6 +389,3 @@ The next section goes on to cover the _<<spring-boot-cli.adoc#cli, Spring Boot C
 or you can jump ahead to read about
 _<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.
 
-
-
-

spring-boot-docs/src/main/asciidoc/documentation-overview.adoc

@@ -136,10 +136,9 @@ When you're ready to push your Spring Boot application to production, we've got
 == Advanced topics
 Lastly, we have a few topics for the more advanced user.
 
-* *Deploy to the cloud:*
-<<cloud-deployment.adoc#cloud-deployment-cloud-foundry, Cloud Foundry>> |
-<<cloud-deployment.adoc#cloud-deployment-heroku, Heroku>> |
-<<cloud-deployment.adoc#cloud-deployment-cloudbees, CloudBees>>
+* *Deploy Spring Boot Applications:*
+<<deployment.adoc#cloud-deployment, Cloud Deployment>> |
+<<deployment.adoc#deployment-service, OS Service>>
 * *Build tool plugins:*
 <<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven>> |
 <<build-tool-plugins.adoc#build-tool-plugins-gradle-plugin, Gradle>>

spring-boot-docs/src/main/asciidoc/index.adoc

@@ -45,7 +45,7 @@ include::getting-started.adoc[]
 include::using-spring-boot.adoc[]
 include::spring-boot-features.adoc[]
 include::production-ready-features.adoc[]
-include::cloud-deployment.adoc[]
+include::deployment.adoc[]
 include::spring-boot-cli.adoc[]
 include::build-tool-plugins.adoc[]
 include::howto.adoc[]

spring-boot-docs/src/main/asciidoc/production-ready-features.adoc

@@ -1043,7 +1043,7 @@ If you want to explore some of the concepts discussed in this chapter, you can t
 look at the actuator {github-code}/spring-boot-samples[sample applications]. You also
 might want to read about graphing tools such as http://graphite.wikidot.com/[Graphite].
 
-Otherwise, you can continue on, to read about <<cloud-deployment.adoc#cloud-deployment,
-'`cloud deployment options`'>> or jump ahead
+Otherwise, you can continue on, to read about <<deployment.adoc#deployment,
+'`deployment options`'>> or jump ahead
 for some in-depth information about Spring Boot's
 _<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.

spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc

@@ -5,8 +5,8 @@
 [partintro]
 --
 This section goes into more detail about how you should use Spring Boot. It covers topics
-such as build systems, auto-configuration and run/deployment options. We also cover some
-Spring Boot best practices. Although there is nothing particularly special about
+such as build systems, auto-configuration and how to run your applications. We also cover
+some Spring Boot best practices. Although there is nothing particularly special about
 Spring Boot (it is just another library that you can consume), there are a few
 recommendations that, when followed, will make your development process just a
 little easier.