Wrap deployment.adoc at 90 characters

Closes gh-10833

spring-boot-project/spring-boot-docs/src/main/asciidoc/deployment.adoc

@@ -21,12 +21,12 @@ specifically), so they need some intermediary layer that adapts _your_ applicati
 _cloud's_ notion of a running process.
 
 Two popular cloud providers, Heroku and Cloud Foundry, employ a "`buildpack`" approach.
-The buildpack wraps your deployed code in whatever is needed to _start_ your
+The buildpack wraps your deployed code in whatever is needed to _start_ your application:
-application: it might be a JDK and a call to `java`, it might be an embedded web server,
+it might be a JDK and a call to `java`, it might be an embedded web server, or it might be
-or it might be a full-fledged application server. A buildpack is pluggable, but ideally
+a full-fledged application server. A buildpack is pluggable, but ideally you should be
-you should be able to get by with as few customizations to it as possible.
+able to get by with as few customizations to it as possible. This reduces the footprint of
-This reduces the footprint of functionality that is not under your control. It minimizes
+unctionality that is not under your control. It minimizes divergence between development
-divergence between development and production environments.
+and production environments.
 
 Ideally, your application, like a Spring Boot executable jar, has everything that it needs
 to run packaged within it.
@@ -40,26 +40,26 @@ developed>> in the "`Getting Started`" section up and running in the Cloud.
 [[cloud-deployment-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]
+specified. The Cloud Foundry https://github.com/cloudfoundry/java-buildpack[Java
-has excellent support for Spring applications, including Spring Boot. You can deploy
+buildpack] has excellent support for Spring applications, including Spring Boot. You can
-stand-alone executable jar applications as well as traditional `.war` packaged
+deploy stand-alone executable jar applications as well as traditional `.war` packaged
 applications.
 
 Once you have built your application (by using, for example, `mvn clean package`) and have
 http://docs.cloudfoundry.org/devguide/installcf/install-go-cli.html[installed the `cf`
-command line tool], deploy your application by using the `cf push` command,
+command line tool], deploy your application by using the `cf push` command, substituting
-substituting the path to your compiled `.jar`. Be sure to have
+the path to your compiled `.jar`. Be sure to have
-http://docs.cloudfoundry.org/devguide/installcf/whats-new-v6.html#login[logged in with your
+http://docs.cloudfoundry.org/devguide/installcf/whats-new-v6.html#login[logged in with
-`cf` command line client] before pushing an application. The following line shows using
+your `cf` command line client] before pushing an application. The following line shows
-the `cf push` command to deploy an application:
+using the `cf push` command to deploy an application:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
 	$ cf push acloudyspringtime -p target/demo-0.0.1-SNAPSHOT.jar
 ----
 
-NOTE: In the preceding example, we substitute `acloudyspringtime` for whatever value you give `cf`
+NOTE: In the preceding example, we substitute `acloudyspringtime` for whatever value you
-as the name of your application.
+give `cf` as the name of your application.
 
 See the http://docs.cloudfoundry.org/devguide/installcf/whats-new-v6.html#push[`cf push`
 documentation] for more options. If there is a Cloud Foundry
@@ -121,13 +121,13 @@ it at `\http://acloudyspringtime.cfapps.io/`.
 ==== 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
+`$VCAP_SERVICES`). This architecture decision is due to Cloud Foundry's polyglot (any
-(any language and platform can be supported as a buildpack) nature. Process-scoped
+language and platform can be supported as a buildpack) nature. Process-scoped environment
-environment variables are language agnostic.
+variables are language agnostic.
 
 Environment variables do not always make for the easiest API, so Spring Boot automatically
-extracts them and flattens the data into properties that can be accessed through
+extracts them and flattens the data into properties that can be accessed through Spring's
-Spring's `Environment` abstraction, as shown in the following example:
+`Environment` abstraction, as shown in the following example:
 
 [source,java,indent=0]
 ----
@@ -178,8 +178,8 @@ Spring Boot makes `-D` arguments available as properties accessible from a Sprin
 Tomcat, Jetty, or Undertow instance which, then uses the port when it starts up. The `$PORT`
 environment variable is assigned to us by the Heroku PaaS.
 
-This should be everything you need. The most common deployment workflow for Heroku deployments is to
+This should be everything you need. The most common deployment workflow for Heroku
-`git push` the code to production, as shown in the following example:
+deployments is to `git push` the code to production, as shown in the following example:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -230,11 +230,12 @@ Your application should now be up and running on Heroku.
 
 [[cloud-deployment-openshift]]
 === OpenShift
-https://www.openshift.com/[OpenShift] is the Red Hat public (and enterprise) extension of the
+https://www.openshift.com/[OpenShift] is the Red Hat public (and enterprise) extension of
-Kubernetes container orchestration platform.  Similarly to Kubernetes, OpenShift has many
+the Kubernetes container orchestration platform.  Similarly to Kubernetes, OpenShift has
-options for installing Spring Boot based applications.
+many options for installing Spring Boot based applications.
 
-OpenShift has many resources describing how to deploy Spring Boot applications, which include:
+OpenShift has many resources describing how to deploy Spring Boot applications, which
+include:
 
 * https://blog.openshift.com/using-openshift-enterprise-grade-spring-boot-deployments/[Using the S2I builder]
 * https://access.redhat.com/documentation/en-us/reference_architectures/2017/html-single/spring_boot_microservices_on_red_hat_openshift_container_platform_3/[Architecture guide]
@@ -260,15 +261,16 @@ simplest option: AWS Elastic Beanstalk.
 
 
 ==== AWS Elastic Beanstalk
-As described in the official http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_Java.html[Elastic
+As described in the official
+http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_Java.html[Elastic
 Beanstalk Java guide], there are two main options to deploy a Java application. You can
 either use the "`Tomcat Platform`" or the "`Java SE platform`".
 
 
 
 ===== Using the Tomcat Platform
-This option applies to Spring Boot projects that produce a war file. There is no any special
+This option applies to Spring Boot projects that produce a war file. There is no any
-configuration required. You need only follow the official guide.
+special configuration required. You need only follow the official guide.
 
 
 
@@ -306,9 +308,9 @@ best to upload the binaries instead. To do so, add the following lines to your
 By default an Elastic Beanstalk environment is load balanced. The load balancer has a
 significant cost. To avoid that cost, set the environment type to "`Single instance`", as
 described in
-http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html#environments-create-wizard-capacity[the Amazon documentation].
+http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html#environments-create-wizard-capacity[the
-You can also create single instance environments by using the CLI and the
+Amazon documentation]. You can also create single instance environments by using the CLI
-following command:
+and the following command:
 
 [indent=0]
 ----
@@ -318,11 +320,11 @@ following command:
 
 
 ==== Summary
-This is one of the easiest ways to get to AWS, but there are more things
+This is one of the easiest ways to get to AWS, but there are more things to cover, such as
-to cover, such as how to integrate Elastic Beanstalk into any CI / CD tool, use the
+how to integrate Elastic Beanstalk into any CI / CD tool, use the Elastic Beanstalk Maven
-Elastic Beanstalk maven plugin instead of the CLI, and others. There is a
+plugin instead of the CLI, and others. There is a
-https://exampledriven.wordpress.com/2017/01/09/spring-boot-aws-elastic-beanstalk-example/[blog post]
+https://exampledriven.wordpress.com/2017/01/09/spring-boot-aws-elastic-beanstalk-example/
-covering these topics more in detail.
+[blog post] covering these topics more in detail.
 
 
 
@@ -350,15 +352,15 @@ See the https://boxfuse.com/docs/commandline/run.html[`boxfuse run` documentatio
 more options. If there is a https://boxfuse.com/docs/commandline/#configuration
 [`boxfuse.conf`] file present in the current directory, it is considered.
 
-TIP: By default, Boxfuse activates a Spring profile named `boxfuse` on startup. If
+TIP: By default, Boxfuse activates a Spring profile named `boxfuse` on startup. If your
-your executable jar or war contains an
+executable jar or war contains an
 https://boxfuse.com/docs/payloads/springboot.html#configuration
-[`application-boxfuse.properties`]
+[`application-boxfuse.properties`] file, Boxfuse bases its configuration based on the
-file, Boxfuse bases its configuration based on the properties it contains.
+properties it contains.
 
-At this point, `boxfuse` creates an image for your application, uploads it, and
+At this point, `boxfuse` creates an image for your application, uploads it, and configures
-configures and starts the necessary resources on AWS resulting in output similar to the
+and starts the necessary resources on AWS resulting in output similar to the following
-following example:
+example:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -430,8 +432,8 @@ following file:
 	  ENCRYPT_KEY: your_encryption_key_here
 ----
 
-You can deploy the app (for example, with a Maven plugin) by adding the project ID
+You can deploy the app (for example, with a Maven plugin) by adding the project ID to the
-to the build configuration, as shown in the following example:
+build configuration, as shown in the following example:
 
 [source,xml,indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -456,18 +458,18 @@ Spring Application there without some modifications. See the
 
 [[deployment-install]]
 == Installing Spring Boot Applications
-In additional to running Spring Boot applications by using `java -jar`, it is also possible
+In additional to running Spring Boot applications by using `java -jar`, it is also
-to make fully executable applications for Unix systems. A fully executable jar can be
+possible to make fully executable applications for Unix systems. A fully executable jar
-executed like any other executable binary or it can be <<deployment-service,registered
+can be executed like any other executable binary or it can be
-with `init.d` or `systemd`>>. This makes it very easy to install and manage Spring Boot
+<<deployment-service,registered with `init.d` or `systemd`>>. This makes it very easy to
-applications in common production environments.
+install and manage Spring Boot applications in common production environments.
 
-WARNING: Fully executable jars work by embedding an extra script at the front of the
+WARNING: Fully executable jars work by embedding an extra script at the front of the file.
-file. Currently, some tools do not accept this format, so you may not always be able to
+Currently, some tools do not accept this format, so you may not always be able to use this
-use this technique. For example, `jar -xf` may silently fail to extract a jar or war that
+technique. For example, `jar -xf` may silently fail to extract a jar or war that has been
-has been made fully executable. It is recommended that you only make your jar or war
+made fully executable. It is recommended that you only make your jar or war fully
-fully executable if you intend to execute it directly, rather than running it with
+executable if you intend to execute it directly, rather than running it with `java -jar`
-`java -jar` or deploying it to a servlet container.
+or deploying it to a servlet container.
 
 To create a '`fully executable`' jar with Maven, use the following plugin configuration:
 
@@ -491,31 +493,30 @@ The following example shows the equivalent Gradle configuration:
 	}
 ----
 
-You can then run your application by typing `./my-application.jar` (where
+You can then run your application by typing `./my-application.jar` (where `my-application`
-`my-application` is the name of your artifact). The directory containing the
+is the name of your artifact). The directory containing the jar is used as your
-jar is used as your application's working directory.
+application's working directory.
 
 [[deployment-install-supported-operating-systems]]
 === Supported Operating Systems
-The default script supports most Linux distributions and is tested on CentOS and
+The default script supports most Linux distributions and is tested on CentOS and Ubuntu.
-Ubuntu. Other platforms, such as OS X and FreeBSD, require the use of a custom
+Other platforms, such as OS X and FreeBSD, require the use of a custom
 `embeddedLaunchScript`.
 
 
 
 [[deployment-service]]
 === Unix/Linux Services
-Spring Boot application can be easily started as Unix/Linux services by using either `init.d`
+Spring Boot application can be easily started as Unix/Linux services by using either
-or `systemd`.
+`init.d` or `systemd`.
 
 
 [[deployment-initd-service]]
 ==== Installation as an `init.d` Service (System V)
-If you configured Spring Boot's Maven or Gradle plugin to generate a
+If you configured Spring Boot's Maven or Gradle plugin to generate a <<deployment-install,
-<<deployment-install,fully executable jar>>, and you do not use a custom
+fully executable jar>>, and you do not use a custom `embeddedLaunchScript`, your
-`embeddedLaunchScript`, your application can be used as an `init.d` service. To do so,
+application can be used as an `init.d` service. To do so, symlink the jar to `init.d` to
-symlink the jar to `init.d` to support the standard `start`, `stop`, `restart` and
+support the standard `start`, `stop`, `restart` and `status` commands.
-`status` commands.
 
 The script supports the following features:
 
@@ -555,17 +556,15 @@ system tools. For example, on Debian, you could use the following command:
 [[deployment-initd-service-securing]]
 ===== Securing an `init.d` Service
 
-NOTE: The following is a set of guidelines on how to secure a Spring Boot application
+NOTE: The following is a set of guidelines on how to secure a Spring Boot application that
-that runs as an init.d service. It is not intended to be an exhaustive list of
+runs as an init.d service. It is not intended to be an exhaustive list of everything that
-everything that should be done to harden an application and the environment in which it
+should be done to harden an application and the environment in which it runs.
-runs.
 
 When executed as root, as is the case when root is being used to start an init.d service,
-the default executable script runs the application as the user who owns the jar
+the default executable script runs the application as the user who owns the jar file. You
-file. You should never run a Spring Boot application as `root`, so your application's jar
+should never run a Spring Boot application as `root`, so your application's jar file
-file should never be owned by root. Instead, create a specific user to run your
+should never be owned by root. Instead, create a specific user to run your application and
-application and use `chown` to make it the owner of the jar file, as shown in the
+use `chown` to make it the owner of the jar file, as shown in the following example:
-following example:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -587,10 +586,10 @@ executed by its owner, as shown in the following example:
 	$ chmod 500 your-app.jar
 ----
 
-Second, you should also take steps to limit the damage if your application or the
+Second, you should also take steps to limit the damage if your application or the account
-account that's running it is compromised. If an attacker does gain access, they could make
+that's running it is compromised. If an attacker does gain access, they could make the jar
-the jar file writable and change its contents. One way to protect against this is to make
+file writable and change its contents. One way to protect against this is to make it
-it immutable by using `chattr`, as shown in the following example:
+immutable by using `chattr`, as shown in the following example:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -601,9 +600,9 @@ This will prevent any user, including root, from modifying the jar.
 
 If root is used to control the application's service and you
 <<deployment-script-customization-conf-file, use a `.conf` file>> to customize its
-startup, the `.conf` file is read and evaluated by the root user. It should be
+startup, the `.conf` file is read and evaluated by the root user. It should be secured
-secured accordingly. Use `chmod` so that the file can only be read by the owner and use
+accordingly. Use `chmod` so that the file can only be read by the owner and use `chown` to
-`chown` to make root the owner, as shown in the following example:
+make root the owner, as shown in the following example:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -615,13 +614,14 @@ secured accordingly. Use `chmod` so that the file can only be read by the owner
 
 [[deployment-systemd-service]]
 ==== Installation as a `systemd` Service
-`systemd` is the successor of the System V init system and is now being used by many modern
+`systemd` is the successor of the System V init system and is now being used by many
-Linux distributions. Although you can continue to use `init.d` scripts with `systemd`, it
+modern Linux distributions. Although you can continue to use `init.d` scripts with
-is also possible to launch Spring Boot applications by using `systemd` '`service`' scripts.
+`systemd`, it is also possible to launch Spring Boot applications by using `systemd`
+'`service`' scripts.
 
 Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a
-Spring Boot application as a `systemd` service, create a script named `myapp.service`
+Spring Boot application as a `systemd` service, create a script named `myapp.service` and
-and place it in `/etc/systemd/system` directory. The following script offers an example:
+place it in `/etc/systemd/system` directory. The following script offers an example:
 
 [indent=0]
 ----
@@ -641,12 +641,12 @@ and place it in `/etc/systemd/system` directory. The following script offers an
 IMPORTANT: Remember to change the `Description`, `User` and `ExecStart` fields for your
 application.
 
-NOTE: The `ExecStart` field does not declare the script action command, which means
+NOTE: The `ExecStart` field does not declare the script action command, which means that
-that the `run` command is used by default.
+the `run` command is used by default.
 
-Note that, unlike when running as an `init.d` service, the user that runs the application, the PID
+Note that, unlike when running as an `init.d` service, the user that runs the application,
-file, and the console log file are managed by `systemd` itself and therefore must be configured
+the PID file, and the console log file are managed by `systemd` itself and therefore must
-by using appropriate fields in the '`service`' script. Consult the
+be configured by using appropriate fields in the '`service`' script. Consult the
 http://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit
 configuration man page] for more details.
 
@@ -664,19 +664,18 @@ Refer to `man systemctl` for more details.
 [[deployment-script-customization]]
 ==== Customizing the Startup Script
 The default embedded startup script written by the Maven or Gradle plugin can be
-customized in a number of ways. For most people, using the default script along with
+customized in a number of ways. For most people, using the default script along with a few
-a few customizations is usually enough. If you find you cannot customize something that
+customizations is usually enough. If you find you cannot customize something that you need
-you need to, you can always use the `embeddedLaunchScript` option to write your own
+to, you can always use the `embeddedLaunchScript` option to write your own file entirely.
-file entirely.
 
 
 
 [[deployment-script-customization-when-it-written]]
 ===== Customizing the Start Script when It Is Written
 It often makes sense to customize elements of the start script as it is written into the
-jar file. For example, init.d scripts can provide a "`description`". Since you know
+jar file. For example, init.d scripts can provide a "`description`". Since you know the
-the description up front (and it need not change), you may as well provide it when the
+description up front (and it need not change), you may as well provide it when the jar is
-jar is generated.
+generated.
 
 To customize written elements, use the `embeddedLaunchScriptProperties` option of the
 Spring Boot Maven or Gradle plugins.
@@ -723,8 +722,8 @@ for Gradle and to `${project.name}` for Maven.
 
 |`inlinedConfScript`
 |Reference to a file script that should be inlined in the default launch script.
- This can be used to set environmental variables such as `JAVA_OPTS` before
+ This can be used to set environmental variables such as `JAVA_OPTS` before any external
- any external config files are loaded.
+ config files are loaded.
 
 |`logFolder`
 |The default value for `LOG_FOLDER`. Only valid for an `init.d` service.
@@ -752,8 +751,8 @@ for Gradle and to `${project.name}` for Maven.
 [[deployment-script-customization-when-it-runs]]
 ===== Customizing a Script When It Runs
 For items of the script that need to be customized _after_ the jar has been written, you
-can use environment variables or a
+can use environment variables or a <<deployment-script-customization-conf-file, config
-<<deployment-script-customization-conf-file, config file>>.
+file>>.
 
 The following environment properties are supported with the default script:
 
@@ -763,10 +762,10 @@ The following environment properties are supported with the default script:
 
 |`MODE`
 |The "`mode`" of operation. The default depends on the way the jar was built but is
- usually `auto` (meaning it tries to guess if it is an init script by checking if it
+ usually `auto` (meaning it tries to guess if it is an init script by checking if it is a
- is a symlink in a directory called `init.d`). You can explicitly set it to `service` so
+ symlink in a directory called `init.d`). You can explicitly set it to `service` so that
- that the `stop\|start\|status\|restart` commands work or to `run` if you want to
+ the `stop\|start\|status\|restart` commands work or to `run` if you want to run the
- run the script in the foreground.
+ script in the foreground.
 
 |`USE_START_STOP_DAEMON`
 |Whether the `start-stop-daemon` command, when it's available, should be used to control
@@ -786,9 +785,8 @@ The following environment properties are supported with the default script:
 |The name of the log file in the `LOG_FOLDER` (`<appname>.log` by default).
 
 |`APP_NAME`
-|The name of the app. If the jar is run from a symlink, the script guesses the app name
+|The name of the app. If the jar is run from a symlink, the script guesses the app name if
- If it is not a symlink or you want to explicitly set the app name, this can be
+ it is not a symlink or you want to explicitly set the app name, this can be useful.
- useful.
 
 |`RUN_ARGS`
 |The arguments to pass to the program (the Spring Boot app).
@@ -809,21 +807,21 @@ The following environment properties are supported with the default script:
  in the script.
 
 |`STOP_WAIT_TIME`
-|The time in seconds to wait when stopping the application before forcing a shutdown
+|The time in seconds to wait when stopping the application before forcing a shutdown (`60`
- (`60` by default).
+ by default).
 |===
 
 NOTE: The `PID_FOLDER`, `LOG_FOLDER`, and `LOG_FILENAME` variables are only valid for an
-`init.d` service. For `systemd`, the equivalent customizations are made by using the '`service`'
+`init.d` service. For `systemd`, the equivalent customizations are made by using the
-script. See the
+'`service`' script. See the
 http://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit
 configuration man page] for more details.
 
 [[deployment-script-customization-conf-file]]
-With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured by using
+With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured by
-a `.conf` file. The file is expected to be next to the jar file and have the same name but
+using a `.conf` file. The file is expected to be next to the jar file and have the same
-suffixed with `.conf` rather than `.jar`. For example, a jar named `/var/myapp/myapp.jar`
+name but suffixed with `.conf` rather than `.jar`. For example, a jar named
-uses the configuration file named `/var/myapp/myapp.conf`.
+`/var/myapp/myapp.jar` uses the configuration file named `/var/myapp/myapp.conf`.
 
 .myapp.conf
 [indent=0,subs="verbatim,quotes,attributes"]
@@ -845,8 +843,8 @@ A Spring Boot application can be started as a Windows service by using
 https://github.com/kohsuke/winsw[`winsw`].
 
 A sample (https://github.com/snicoll-scratches/spring-boot-daemon[maintained separately])
-describes step-by-step how you can create a Windows service for
+describes step-by-step how you can create a Windows service for your Spring Boot
-your Spring Boot application.
+application.