diff --git a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc index 3fff6e10c4b..536700a63c6 100644 --- a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc +++ b/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`. |=== diff --git a/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc b/spring-boot-docs/src/main/asciidoc/deployment.adoc similarity index 79% rename from spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc rename to spring-boot-docs/src/main/asciidoc/deployment.adoc index 84ffecc6743..c2f7c247703 100644 --- a/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc +++ b/spring-boot-docs/src/main/asciidoc/deployment.adoc @@ -1,8 +1,20 @@ -[[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 <> 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 <> 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/.pid` +* Writes console logs to `/var/log/.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 +---- + + + +==== 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 _<>_. - - - diff --git a/spring-boot-docs/src/main/asciidoc/documentation-overview.adoc b/spring-boot-docs/src/main/asciidoc/documentation-overview.adoc index 8b0990bd170..53ebc8f876a 100644 --- a/spring-boot-docs/src/main/asciidoc/documentation-overview.adoc +++ b/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:* -<> | -<> | -<> +* *Deploy Spring Boot Applications:* +<> | +<> * *Build tool plugins:* <> | <> diff --git a/spring-boot-docs/src/main/asciidoc/index.adoc b/spring-boot-docs/src/main/asciidoc/index.adoc index f9a1cb452ec..e9a2416bd44 100644 --- a/spring-boot-docs/src/main/asciidoc/index.adoc +++ b/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[] diff --git a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index eca4e004c7b..16436c871fa 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/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 <> or jump ahead +Otherwise, you can continue on, to read about <> or jump ahead for some in-depth information about Spring Boot's _<>_. diff --git a/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc b/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc index 4103189e94b..b9cf076bdf4 100644 --- a/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc +++ b/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.