root
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Actions 12 Packages Projects Releases Wiki Activity

Merge pull request #10833 from Jay Bryant 

* gh-10833:
  Wrap deployment.adoc at 90 characters
  Make editorial changes to deployment.adoc
This commit is contained in:
Andy Wilkinson 2017-10-31 17:31:56 +00:00
parent 6f55b57855 ab4f211ebf
commit 3b21fd5ef6
1 changed files with 242 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,11 +1,11 @@
[[deployment]] [[deployment]]
= Deploying Spring Boot applications = Deploying Spring Boot Applications
[partintro] [partintro]
-- --
Spring Boot's flexible packaging options provide a great deal of choice when it comes to 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 deploying your application. You can deploy Spring Boot applications to a variety
of cloud platforms, to a container images (such as Docker) or to virtual/real machines. of cloud platforms, to container images (such as Docker), or to virtual/real machines.
This section covers some of the more common deployment scenarios. This section covers some of the more common deployment scenarios.
-- --
@ -13,25 +13,25 @@ This section covers some of the more common deployment scenarios.
[[cloud-deployment]] [[cloud-deployment]]
== Deploying to the cloud == Deploying to the Cloud
Spring Boot's executable jars are ready-made for most popular cloud PaaS 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 (Platform-as-a-Service) providers. These providers tend to require that you
"`bring your own container`"; they manage application processes (not Java applications "`bring your own container`". They manage application processes (not Java applications
specifically), so they need some intermediary layer that adapts _your_ application to the specifically), so they need some intermediary layer that adapts _your_ application to the
_cloud's_ notion of a running process. _cloud's_ notion of a running process.
Two popular cloud providers, Heroku and Cloud Foundry, employ a "`buildpack`" approach. 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 Ideally, your application, like a Spring Boot executable jar, has everything that it needs
to run packaged within it. to run packaged within it.
In this section we'll look at what it takes to get the In this section, we look at what it takes to get the
<<getting-started.adoc#getting-started-first-application, simple application that we <<getting-started.adoc#getting-started-first-application, simple application that we
developed>> in the "`Getting Started`" section up and running in the Cloud. developed>> in the "`Getting Started`" section up and running in the Cloud.
@ -40,32 +40,34 @@ developed>> in the "`Getting Started`" section up and running in the Cloud.
[[cloud-deployment-cloud-foundry]] [[cloud-deployment-cloud-foundry]]
=== Cloud Foundry === Cloud Foundry
Cloud Foundry provides default buildpacks that come into play if no other buildpack is 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. applications.
Once you've built your application (using, for example, `mvn clean package`) and 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` http://docs.cloudfoundry.org/devguide/installcf/install-go-cli.html[installed the `cf`
command line tool], simply deploy your application using the `cf push` command as follows, 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. your `cf` command line client] before pushing an application. The following line shows
using the `cf push` command to deploy an application:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
$ cf push acloudyspringtime -p target/demo-0.0.1-SNAPSHOT.jar $ 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` as the name of your application.
See the http://docs.cloudfoundry.org/devguide/installcf/whats-new-v6.html#push[`cf push` 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 documentation] for more options. If there is a Cloud Foundry
http://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html[`manifest.yml`] http://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html[`manifest.yml`]
file present in the same directory, it will be consulted. file present in the same directory, it is considered.
NOTE: Here we are substituting `acloudyspringtime` for whatever value you give `cf` At this point, `cf` starts uploading your application, producing output similar to the
as the name of your application. following example:
At this point `cf` will start uploading your application:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -94,7 +96,8 @@ At this point `cf` will start uploading your application:
Congratulations! The application is now live! Congratulations! The application is now live!
It's easy to then verify the status of the deployed application: Once your application is live, you can verify the status of the deployed application by
using the `cf apps` command, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -109,22 +112,22 @@ It's easy to then verify the status of the deployed application:
---- ----
Once Cloud Foundry acknowledges that your application has been deployed, you should be Once Cloud Foundry acknowledges that your application has been deployed, you should be
able to hit the application at the URI given, in this case able to find the application at the URI given. In the preceding example, you could find
`\http://acloudyspringtime.cfapps.io/`. it at `\http://acloudyspringtime.cfapps.io/`.
[[cloud-deployment-cloud-foundry-services]] [[cloud-deployment-cloud-foundry-services]]
==== Binding to services ==== Binding to Services
By default, metadata about the running application as well as service connection By default, metadata about the running application as well as service connection
information is exposed to the application as environment variables (for example: 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 don't always make for the easiest API so Spring Boot automatically 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: `Environment` abstraction, as shown in the following example:
[source,java,indent=0] [source,java,indent=0]
---- ----
@ -143,9 +146,10 @@ Spring's `Environment` abstraction:
} }
---- ----
All Cloud Foundry properties are prefixed with `vcap`. You can use vcap properties to All Cloud Foundry properties are prefixed with `vcap`. You can use `vcap` properties to
access application information (such as the public URL of the application) and service access application information (such as the public URL of the application) and service
information (such as database credentials). See `CloudFoundryVcapEnvironmentPostProcessor` information (such as database credentials). See
{dc-spring-boot}/cloud/CloudFoundryVcapEnvironmentPostProcessor.html['`CloudFoundryVcapEnvironmentPostProcessor`']
Javadoc for complete details. Javadoc for complete details.
TIP: The http://cloud.spring.io/spring-cloud-connectors/[Spring Cloud Connectors] project TIP: The http://cloud.spring.io/spring-cloud-connectors/[Spring Cloud Connectors] project
@ -161,8 +165,8 @@ Heroku is another popular PaaS platform. To customize Heroku builds, you provide
assigns a `port` for the Java application to use and then ensures that routing to the assigns a `port` for the Java application to use and then ensures that routing to the
external URI works. external URI works.
You must configure your application to listen on the correct port. Here's the `Procfile` You must configure your application to listen on the correct port. The following example
for our starter REST application: shows the `Procfile` for our starter REST application:
[indent=0] [indent=0]
---- ----
@ -171,11 +175,11 @@ for our starter REST application:
Spring Boot makes `-D` arguments available as properties accessible from a Spring Spring Boot makes `-D` arguments available as properties accessible from a Spring
`Environment` instance. The `server.port` configuration property is fed to the embedded `Environment` instance. The `server.port` configuration property is fed to the embedded
Tomcat, Jetty or Undertow instance which then uses it when it starts up. The `$PORT` 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. environment variable is assigned to us by the Heroku PaaS.
This should be everything you need. The most common 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. deployments is to `git push` the code to production, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -226,23 +230,24 @@ Your application should now be up and running on Heroku.
[[cloud-deployment-openshift]] [[cloud-deployment-openshift]]
=== 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. Just as in 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://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] * https://access.redhat.com/documentation/en-us/reference_architectures/2017/html-single/spring_boot_microservices_on_red_hat_openshift_container_platform_3/[Architecture guide]
* https://blog.openshift.com/using-spring-boot-on-openshift/[Running as traditional web application on Wildfly] * https://blog.openshift.com/using-spring-boot-on-openshift/[Running as a traditional web application on Wildfly]
* https://blog.openshift.com/openshift-commons-briefing-96-cloud-native-applications-spring-rhoar/[OpenShift Commons Briefing] * https://blog.openshift.com/openshift-commons-briefing-96-cloud-native-applications-spring-rhoar/[OpenShift Commons Briefing]
[[cloud-deployment-aws]] [[cloud-deployment-aws]]
=== Amazon Web Services (AWS) === Amazon Web Services (AWS)
Amazon Web Services offers multiple ways to install Spring Boot based applications, either Amazon Web Services offers multiple ways to install Spring Boot-based applications, either
as traditional web applications (war) or as executable jar files with an embedded web as traditional web applications (war) or as executable jar files with an embedded web
server. Options include : server. The options include:
* AWS Elastic Beanstalk * AWS Elastic Beanstalk
* AWS Code Deploy * AWS Code Deploy
@ -250,29 +255,30 @@ server. Options include :
* AWS Cloud Formation * AWS Cloud Formation
* AWS Container Registry * AWS Container Registry
Each has different features and pricing model, here we will describe only the simplest Each has different features and pricing model. In this document, we describe only the
option : AWS Elastic Beanstalk. simplest option: AWS Elastic Beanstalk.
==== 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
Beanstalk Java guide], there are two main options to deploy a Java application; You can 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`". either use the "`Tomcat Platform`" or the "`Java SE platform`".
===== Using the Tomcat platform ===== Using the Tomcat Platform
This option applies to Spring Boot projects producing 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, just follow the official guide. special configuration required. You need only follow the official guide.
===== Using the Java SE platform ===== Using the Java SE Platform
This option applies to Spring Boot projects producing a jar file and running an embedded This option applies to Spring Boot projects that produce a jar file and run an embedded
web container. Elastic Beanstalk environments run an nginx instance on port 80 to proxy web container. Elastic Beanstalk environments run an nginx instance on port 80 to proxy
the actual application, running on port 5000. To configure it, add the following to your the actual application, running on port 5000. To configure it, add the following line to
`application.properties`: your `application.properties` file:
[indent=0] [indent=0]
---- ----
@ -280,12 +286,12 @@ the actual application, running on port 5000. To configure it, add the following
---- ----
[TIP]
===== Best practices .Upload binaries instead of sources
====
====== Uploading binaries instead of sources By default, Elastic Beanstalk uploads sources and compiles them in AWS. However, it is
By default Elastic Beanstalk uploads sources and compiles them in AWS. To upload the best to upload the binaries instead. To do so, add the following lines to your
binaries instead, add the following to your `.elasticbeanstalk/config.yml` file: `.elasticbeanstalk/config.yml` file:
@ -294,29 +300,31 @@ binaries instead, add the following to your `.elasticbeanstalk/config.yml` file:
deploy: deploy:
artifact: target/demo-0.0.1-SNAPSHOT.jar artifact: target/demo-0.0.1-SNAPSHOT.jar
---- ----
====
[TIP]
.Reduce costs by setting the environment type
====== Reduce costs by setting the environment type ====
By default an Elastic Beanstalk environment is load balanced. The load balancer has a cost By default an Elastic Beanstalk environment is load balanced. The load balancer has a
perspective, to avoid it, set the environment type to "`Single instance`" as described significant cost. To avoid that cost, set the environment type to "`Single instance`", as
http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html#environments-create-wizard-capacity[in the Amazon documentation]. described in
Single instance environments can be created using the CLI as well using the following http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html#environments-create-wizard-capacity[the
command: Amazon documentation]. You can also create single instance environments by using the CLI
and the following command:
[indent=0] [indent=0]
---- ----
eb create -s eb create -s
---- ----
====
==== Summary ==== 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, e.g.: how to integrate Elastic Beanstalk into any CI / CD tool, using the how to integrate Elastic Beanstalk into any CI / CD tool, use the Elastic Beanstalk Maven
Elastic Beanstalk maven plugin instead of the CLI, etc. 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] 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.
@ -324,15 +332,16 @@ covering these topics more in detail.
=== Boxfuse and Amazon Web Services === Boxfuse and Amazon Web Services
https://boxfuse.com/[Boxfuse] works by turning your Spring Boot executable jar or war https://boxfuse.com/[Boxfuse] works by turning your Spring Boot executable jar or war
into a minimal VM image that can be deployed unchanged either on VirtualBox or on AWS. into a minimal VM image that can be deployed unchanged either on VirtualBox or on AWS.
Boxfuse comes with deep integration for Spring Boot and will use the information from your Boxfuse comes with deep integration for Spring Boot and uses the information from your
Spring Boot configuration file to automatically configure ports and health check URLs. Spring Boot configuration file to automatically configure ports and health check URLs.
Boxfuse leverages this information both for the images it produces as well as for all the Boxfuse leverages this information both for the images it produces as well as for all the
resources it provisions (instances, security groups, elastic load balancers, etc). resources it provisions (instances, security groups, elastic load balancers, and so on).
Once you have created a https://console.boxfuse.com[Boxfuse account], connected it to your Once you have created a https://console.boxfuse.com[Boxfuse account], connected it to
AWS account, and installed the latest version of the Boxfuse Client, you can deploy your your AWS account, installed the latest version of the Boxfuse Client, and ensured that
Spring Boot application to AWS as follows (ensure the application has been built by the application has been built by Maven or Gradle (by using, for example, `mvn clean
Maven or Gradle first using, for example, `mvn clean package`): package`), you can deploy your Spring Boot application to AWS with a command similar to
the following:
[indent=0] [indent=0]
---- ----
@ -341,16 +350,17 @@ Maven or Gradle first using, for example, `mvn clean package`):
See the https://boxfuse.com/docs/commandline/run.html[`boxfuse run` documentation] for See the https://boxfuse.com/docs/commandline/run.html[`boxfuse run` documentation] for
more options. If there is a https://boxfuse.com/docs/commandline/#configuration more options. If there is a https://boxfuse.com/docs/commandline/#configuration
[`boxfuse.conf`] file present in the current directory, it will be consulted. [`boxfuse.conf`] file present in the current directory, it is considered.
TIP: By default Boxfuse will activate a Spring profile named `boxfuse` on startup and 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 https://boxfuse.com/docs/payloads/springboot.html#configuration
[`application-boxfuse.properties`] [`application-boxfuse.properties`] file, Boxfuse bases its configuration based on the
file, Boxfuse will base its configuration based on the properties it contains. properties it contains.
At this point `boxfuse` will create an image for your application, upload it, At this point, `boxfuse` creates an image for your application, uploads it, and configures
and then configure and start the necessary resources on AWS: and starts the necessary resources on AWS resulting in output similar to the following
example:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -375,27 +385,28 @@ and then configure and start the necessary resources on AWS:
Your application should now be up and running on AWS. Your application should now be up and running on AWS.
There's a blog on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spring Boot apps See the blog post on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spring Boot
on EC2] as well as https://boxfuse.com/docs/payloads/springboot.html[documentation apps on EC2] as well as the
for the Boxfuse Spring Boot integration] on their website that will get you started with a https://boxfuse.com/docs/payloads/springboot.html[documentation for the Boxfuse Spring
Maven build to run the app. Boot integration] to get started with a Maven build to run the app.
[[cloud-deployment-gae]] [[cloud-deployment-gae]]
=== Google Cloud === Google Cloud
Google Cloud has several options that could be used to launch Spring Boot applications. Google Cloud has several options that can be used to launch Spring Boot applications.
The easiest to get started with is probably App Engine, but you could also find ways to The easiest to get started with is probably App Engine, but you could also find ways to
run Spring Boot in a container with Container Engine, or on a virtual machine using run Spring Boot in a container with Container Engine or on a virtual machine with
Compute Engine. Compute Engine.
To run in App Engine you can create a project in the UI first, which sets up a unique To run in App Engine, you can create a project in the UI first, which sets up a unique
identifier for you and also HTTP routes. Add a Java app to the project and leave it empty, identifier for you and also sets up HTTP routes. Add a Java app to the project and leave
then use the https://cloud.google.com/sdk/downloads[Google Cloud SDK] to push your it empty and then use the https://cloud.google.com/sdk/downloads[Google Cloud SDK] to
Spring Boot app into that slot from the command line or CI build. push your Spring Boot app into that slot from the command line or CI build.
App Engine needs you to create an `app.yaml` file to describe the resources your app App Engine needs you to create an `app.yaml` file to describe the resources your app
requires. Normally you put this in `src/main/appengine`, and it looks something like this: requires. Normally you put this file in `src/main/appengine`, and it should resemble the
following file:
[source,yaml,indent=0] [source,yaml,indent=0]
---- ----
@ -421,8 +432,8 @@ requires. Normally you put this in `src/main/appengine`, and it looks something
ENCRYPT_KEY: your_encryption_key_here ENCRYPT_KEY: your_encryption_key_here
---- ----
You can deploy the app, for example, with a Maven plugin by simply 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: build configuration, as shown in the following example:
[source,xml,indent=0,subs="verbatim,quotes,attributes"] [source,xml,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -436,31 +447,31 @@ to the build configuration:
</plugin> </plugin>
---- ----
Then deploy with `mvn appengine:deploy` (if you need to authenticate first the build will Then deploy with `mvn appengine:deploy` (if you need to authenticate first, the build
fail). fails).
NOTE: Google App Engine Classic is tied to the Servlet 2.5 API, so you can't deploy a NOTE: Google App Engine Classic is tied to the Servlet 2.5 API, so you cannot deploy a
Spring Application there without some modifications. See the Spring Application there without some modifications. See the
<<howto.adoc#howto-servlet-2-5, Servlet 2.5 section>> of this guide. <<howto.adoc#howto-servlet-2-5,Servlet 2.5 section>> of this guide.
[[deployment-install]] [[deployment-install]]
== Installing Spring Boot applications == Installing Spring Boot Applications
In additional to running Spring Boot applications 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: To create a '`fully executable`' jar with Maven, use the following plugin configuration:
[source,xml,indent=0,subs="verbatim,quotes,attributes"] [source,xml,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -473,7 +484,7 @@ To create a '`fully executable`' jar with Maven use the following plugin configu
</plugin> </plugin>
---- ----
With Gradle, the equivalent configuration is: The following example shows the equivalent Gradle configuration:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"] [source,groovy,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -482,40 +493,39 @@ With Gradle, the equivalent configuration is:
} }
---- ----
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 will be used as your application's working directory. application's working directory.
[[deployment-install-supported-operating-systems]] [[deployment-install-supported-operating-systems]]
=== 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, will require the use of a custom Other platforms, such as OS X and FreeBSD, require the use of a custom
`embeddedLaunchScript`. `embeddedLaunchScript`.
[[deployment-service]] [[deployment-service]]
=== Unix/Linux services === Unix/Linux Services
Spring Boot application can be easily started as Unix/Linux services 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]] [[deployment-initd-service]]
==== Installation as an init.d service (System V) ==== Installation as an `init.d` Service (System V)
If you've 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're not using a custom fully executable jar>>, and you do not use a custom `embeddedLaunchScript`, your
`embeddedLaunchScript`, then your application can be used as an `init.d` service. Simply 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: The script supports the following features:
* Starts the services as the user that owns the jar file * Starts the services as the user that owns the jar file
* Tracks application's PID using `/var/run/<appname>/<appname>.pid` * Tracks the application's PID by using `/var/run/<appname>/<appname>.pid`
* Writes console logs to `/var/log/<appname>.log` * Writes console logs to `/var/log/<appname>.log`
Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a 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: Spring Boot application as an `init.d` service, create a symlink, as follows:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -523,7 +533,7 @@ Spring Boot application as an `init.d` service simply create a symlink:
---- ----
Once installed, you can start and stop the service in the usual way. For example, on a Once installed, you can start and stop the service in the usual way. For example, on a
Debian based system: Debian based system, you could start it with the following command:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -533,8 +543,8 @@ Debian based system:
TIP: If your application fails to start, check the log file written to TIP: If your application fails to start, check the log file written to
`/var/log/<appname>.log` for errors. `/var/log/<appname>.log` for errors.
You can also flag the application to start automatically using your standard operating You can also flag the application to start automatically by using your standard operating
system tools. For example, on Debian: system tools. For example, on Debian, you could use the following command:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -544,44 +554,42 @@ system tools. For example, on Debian:
[[deployment-initd-service-securing]] [[deployment-initd-service-securing]]
===== Securing an init.d service ===== 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's being run 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, When executed as root, as is the case when root is being used to start an init.d service,
the default executable script will run the application as the user which 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. For example: use `chown` to make it the owner of the jar file, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
$ chown bootapp:bootapp your-app.jar $ chown bootapp:bootapp your-app.jar
---- ----
In this case, the default executable script will run the application as the `bootapp` In this case, the default executable script runs the application as the `bootapp` user.
user.
TIP: To reduce the chances of the application's user account being compromised, you should TIP: To reduce the chances of the application's user account being compromised, you should
consider preventing it from using a login shell. Set the account's shell to consider preventing it from using a login shell. For example, you can set the account's
`/usr/sbin/nologin`, for example. shell to `/usr/sbin/nologin`.
You should also take steps to prevent the modification of your application's jar file. You should also take steps to prevent the modification of your application's jar file.
Firstly, configure its permissions so that it cannot be written and can only be read or Firstly, configure its permissions so that it cannot be written and can only be read or
executed by its owner: executed by its owner, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
$ chmod 500 your-app.jar $ chmod 500 your-app.jar
---- ----
Secondly, 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 using `chattr`: immutable by using `chattr`, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -592,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 If root is used to control the application's service and you
<<deployment-script-customization-conf-file, use a `.conf` file>> to customize its <<deployment-script-customization-conf-file, use a `.conf` file>> to customize its
startup, the `.conf` file will be 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: make root the owner, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -605,14 +613,15 @@ secured accordingly. Use `chmod` so that the file can only be read by the owner
[[deployment-systemd-service]] [[deployment-systemd-service]]
==== Installation as a 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 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 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` using Spring Boot application as a `systemd` service, create a script named `myapp.service` and
the following example and place it in `/etc/systemd/system` directory: place it in `/etc/systemd/system` directory. The following script offers an example:
[indent=0] [indent=0]
---- ----
@ -629,19 +638,19 @@ the following example and place it in `/etc/systemd/system` directory:
WantedBy=multi-user.target WantedBy=multi-user.target
---- ----
TIP: Remember to change the `Description`, `User` and `ExecStart` fields for your IMPORTANT: Remember to change the `Description`, `User` and `ExecStart` fields for your
application. application.
TIP: Note that `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 `run` command is used by default. the `run` command is used by default.
Note that unlike when running as an `init.d` service, user that runs the application, PID Note that, unlike when running as an `init.d` service, the user that runs the application,
file and 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
using appropriate fields in '`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 http://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit
configuration man page] for more details. configuration man page] for more details.
To flag the application to start automatically on system boot use the following command: To flag the application to start automatically on system boot, use the following command:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -653,20 +662,20 @@ Refer to `man systemctl` for more details.
[[deployment-script-customization]] [[deployment-script-customization]]
==== Customizing the startup script ==== Customizing the Startup Script
The default embedded startup script written by the Maven or Gradle plugin can be 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 can't 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]] [[deployment-script-customization-when-it-written]]
===== Customizing script when it's written ===== Customizing the Start Script when It Is Written
It often makes sense to customize elements of the start script as it's written into the 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`" and, since you know jar file. For example, init.d scripts can provide a "`description`". Since you know the
this up front (and it won't change), you may as well provide it when the jar is generated. description up front (and it need not change), you may as well provide it when the jar is
generated.
To customize written elements, use the `embeddedLaunchScriptProperties` option of the To customize written elements, use the `embeddedLaunchScriptProperties` option of the
Spring Boot Maven or Gradle plugins. Spring Boot Maven or Gradle plugins.
@ -713,8 +722,8 @@ for Gradle and to `${project.name}` for Maven.
|`inlinedConfScript` |`inlinedConfScript`
|Reference to a file script that should be inlined in the default launch script. |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` |`logFolder`
|The default value for `LOG_FOLDER`. Only valid for an `init.d` service. |The default value for `LOG_FOLDER`. Only valid for an `init.d` service.
@ -726,12 +735,12 @@ for Gradle and to `${project.name}` for Maven.
|The default value for `PID_FOLDER`. Only valid for an `init.d` service. |The default value for `PID_FOLDER`. Only valid for an `init.d` service.
|`pidFilename` |`pidFilename`
|The default value for the name of the pid file in `PID_FOLDER`. Only valid for an |The default value for the name of the PID file in `PID_FOLDER`. Only valid for an
`init.d` service. `init.d` service.
|`useStartStopDaemon` |`useStartStopDaemon`
|If the `start-stop-daemon` command, when it's available, should be used to control the |Whether the `start-stop-daemon` command, when it's available, should be used to control
process. Defaults to `true`. the process. Defaults to `true`.
|`stopWaitTime` |`stopWaitTime`
|The default value for `STOP_WAIT_TIME`. Only valid for an `init.d` service. |The default value for `STOP_WAIT_TIME`. Only valid for an `init.d` service.
@ -740,10 +749,10 @@ for Gradle and to `${project.name}` for Maven.
[[deployment-script-customization-when-it-runs]] [[deployment-script-customization-when-it-runs]]
===== Customizing script 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 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: The following environment properties are supported with the default script:
@ -752,32 +761,32 @@ The following environment properties are supported with the default script:
|Variable |Description |Variable |Description
|`MODE` |`MODE`
|The "`mode`" of operation. The default depends on the way the jar was built, but will |The "`mode`" of operation. The default depends on the way the jar was built but is
usually be `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 just 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` |`USE_START_STOP_DAEMON`
|If the `start-stop-daemon` command, when it's available, should be used to control the |Whether the `start-stop-daemon` command, when it's available, should be used to control
process. Defaults to `true`. the process. Defaults to `true`.
|`PID_FOLDER` |`PID_FOLDER`
|The root name of the pid folder (`/var/run` by default). |The root name of the pid folder (`/var/run` by default).
|`LOG_FOLDER` |`LOG_FOLDER`
|The name of the folder to put log files in (`/var/log` by default). |The name of the folder in which to put log files (`/var/log` by default).
|`CONF_FOLDER` |`CONF_FOLDER`
|The name of the folder to read .conf files from (same folder as jar-file by default). |The name of the folder from which to read .conf files (same folder as jar-file by
default).
|`LOG_FILENAME` |`LOG_FILENAME`
|The name of the log file in the `LOG_FOLDER` (`<appname>.log` by default). |The name of the log file in the `LOG_FOLDER` (`<appname>.log` by default).
|`APP_NAME` |`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
but 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` |`RUN_ARGS`
|The arguments to pass to the program (the Spring Boot app). |The arguments to pass to the program (the Spring Boot app).
@ -791,28 +800,28 @@ The following environment properties are supported with the default script:
|`JARFILE` |`JARFILE`
|The explicit location of the jar file, in case the script is being used to launch a jar |The explicit location of the jar file, in case the script is being used to launch a jar
that it is not actually embedded in. that it is not actually embedded.
|`DEBUG` |`DEBUG`
|if not empty will set the `-x` flag on the shell process, making it easy to see the logic |If not empty, sets the `-x` flag on the shell process, making it easy to see the logic
in the script. in the script.
|`STOP_WAIT_TIME` |`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 NOTE: The `PID_FOLDER`, `LOG_FOLDER`, and `LOG_FILENAME` variables are only valid for an
`init.d` service. With `systemd` the equivalent customizations are made using '`service`' `init.d` service. For `systemd`, the equivalent customizations are made by using the
script. Check the '`service`' script. See the
http://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit http://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit
configuration man page] for more details. configuration man page] for more details.
[[deployment-script-customization-conf-file]] [[deployment-script-customization-conf-file]]
With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured using With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured by
a `.conf` file. The file is expected 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
will use the configuration file named `/var/myapp/myapp.conf`. `/var/myapp/myapp.jar` uses the configuration file named `/var/myapp/myapp.conf`.
.myapp.conf .myapp.conf
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
@ -821,34 +830,33 @@ will use the configuration file named `/var/myapp/myapp.conf`.
LOG_FOLDER=/custom/log/folder LOG_FOLDER=/custom/log/folder
---- ----
TIP: You can use a `CONF_FOLDER` environment variable to customize the location of the TIP: If you do not like having the config file next to the jar file, you can set a
config file if you don't like it living next to the jar. `CONF_FOLDER` environment variable to customize the location of the config file.
To learn about securing this file appropriately, please refer to To learn about securing this file appropriately, see
<<deployment-initd-service-securing,the guidelines for securing an init.d service>>. <<deployment-initd-service-securing,the guidelines for securing an init.d service>>.
[[deployment-windows]] [[deployment-windows]]
=== Microsoft Windows services === Microsoft Windows Services
Spring Boot application can be started as Windows service using A Spring Boot application can be started as a Windows service by using
https://github.com/kohsuke/winsw[`winsw`]. https://github.com/kohsuke/winsw[`winsw`].
A sample https://github.com/snicoll-scratches/spring-boot-daemon[maintained separately] A sample (https://github.com/snicoll-scratches/spring-boot-daemon[maintained separately])
to the core of Spring Boot 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.
[[deployment-whats-next]] [[deployment-whats-next]]
== What to read next == What to Read Next
Check out the http://www.cloudfoundry.com/[Cloud Foundry], Check out the http://www.cloudfoundry.com/[Cloud Foundry],
https://www.heroku.com/[Heroku], https://www.openshift.com[OpenShift] and https://www.heroku.com/[Heroku], https://www.openshift.com[OpenShift], and
https://boxfuse.com[Boxfuse] web sites for more information about the kinds of features https://boxfuse.com[Boxfuse] web sites for more information about the kinds of features
that a PaaS can offer. These are just four of the most popular Java PaaS providers, since that a PaaS can offer. These are just four of the most popular Java PaaS providers. Since
Spring Boot is so amenable to cloud-based deployment you're free to consider other Spring Boot is so amenable to cloud-based deployment, you can freely consider other
providers as well. providers as well.
The next section goes on to cover the _<<spring-boot-cli.adoc#cli, Spring Boot CLI>>_; The next section goes on to cover the _<<spring-boot-cli.adoc#cli, Spring Boot CLI>>_,
or you can jump ahead to read about or you can jump ahead to read about
_<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_. _<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.