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
commit
3b21fd5ef6
|
|
@ -1,11 +1,11 @@
|
|||
[[deployment]]
|
||||
= Deploying Spring Boot applications
|
||||
= 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.
|
||||
deploying your application. You can deploy Spring Boot applications to a variety
|
||||
of cloud platforms, to container images (such as Docker), or to virtual/real machines.
|
||||
|
||||
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]]
|
||||
== Deploying to the cloud
|
||||
== 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
|
||||
(Platform-as-a-Service) providers. These providers tend to require that you
|
||||
"`bring your own container`". They manage application processes (not Java applications
|
||||
specifically), so they need some intermediary layer that adapts _your_ application to the
|
||||
_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
|
||||
application: it might be a JDK and a call to `java`, it might be an embedded web server,
|
||||
or it might be a full-fledged application server. A buildpack is pluggable, but ideally
|
||||
you should be able to get by with as few customizations to it as possible.
|
||||
This reduces the footprint of functionality that is not under your control. It minimizes
|
||||
divergence between development and production environments.
|
||||
The buildpack wraps your deployed code in whatever is needed to _start_ your application:
|
||||
it might be a JDK and a call to `java`, it might be an embedded web server, or it might be
|
||||
a full-fledged application server. A buildpack is pluggable, but ideally you should be
|
||||
able to get by with as few customizations to it as possible. This reduces the footprint of
|
||||
unctionality that is not under your control. It minimizes divergence between development
|
||||
and production environments.
|
||||
|
||||
Ideally, your application, like a Spring Boot executable jar, has everything that it needs
|
||||
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
|
||||
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 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
|
||||
stand-alone executable jar applications, as well as traditional `.war` packaged
|
||||
specified. The Cloud Foundry https://github.com/cloudfoundry/java-buildpack[Java
|
||||
buildpack] has excellent support for Spring applications, including Spring Boot. You can
|
||||
deploy stand-alone executable jar applications as well as traditional `.war` packaged
|
||||
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`
|
||||
command line tool], simply deploy your application using the `cf push` command as follows,
|
||||
substituting 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
|
||||
`cf` command line client] before pushing an application.
|
||||
command line tool], deploy your application by using the `cf push` command, substituting
|
||||
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 `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"]
|
||||
----
|
||||
$ 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`
|
||||
documentation] for more options. If there is a Cloud Foundry
|
||||
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`
|
||||
as the name of your application.
|
||||
|
||||
At this point `cf` will start uploading your application:
|
||||
At this point, `cf` starts uploading your application, producing output similar to the
|
||||
following example:
|
||||
|
||||
[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!
|
||||
|
||||
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"]
|
||||
----
|
||||
|
|
@ -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
|
||||
able to hit the application at the URI given, in this case
|
||||
`\http://acloudyspringtime.cfapps.io/`.
|
||||
able to find the application at the URI given. In the preceding example, you could find
|
||||
it at `\http://acloudyspringtime.cfapps.io/`.
|
||||
|
||||
|
||||
|
||||
[[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
|
||||
(any language and platform can be supported as a buildpack) nature; process-scoped
|
||||
environment variables are language agnostic.
|
||||
`$VCAP_SERVICES`). This architecture decision is due to Cloud Foundry's polyglot (any
|
||||
language and platform can be supported as a buildpack) nature. Process-scoped environment
|
||||
variables are language agnostic.
|
||||
|
||||
Environment variables don't always make for the easiest API so Spring Boot automatically
|
||||
extracts them and flattens the data into properties that can be accessed through
|
||||
Spring's `Environment` abstraction:
|
||||
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 Spring's
|
||||
`Environment` abstraction, as shown in the following example:
|
||||
|
||||
[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
|
||||
information (such as database credentials). See `CloudFoundryVcapEnvironmentPostProcessor`
|
||||
information (such as database credentials). See
|
||||
{dc-spring-boot}/cloud/CloudFoundryVcapEnvironmentPostProcessor.html['`CloudFoundryVcapEnvironmentPostProcessor`']
|
||||
Javadoc for complete details.
|
||||
|
||||
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
|
||||
external URI works.
|
||||
|
||||
You must configure your application to listen on the correct port. Here's the `Procfile`
|
||||
for our starter REST application:
|
||||
You must configure your application to listen on the correct port. The following example
|
||||
shows the `Procfile` for our starter REST application:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
|
|
@ -171,11 +175,11 @@ for our starter REST application:
|
|||
|
||||
Spring Boot makes `-D` arguments available as properties accessible from a Spring
|
||||
`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.
|
||||
|
||||
This should be everything you need. The most common workflow for Heroku deployments is to
|
||||
`git push` the code to production.
|
||||
This should be everything you need. The most common deployment workflow for Heroku
|
||||
deployments is to `git push` the code to production, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -226,23 +230,24 @@ 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
|
||||
Kubernetes container orchestration platform. Just as in Kubernetes, OpenShift has many
|
||||
options for installing Spring Boot based applications.
|
||||
https://www.openshift.com/[OpenShift] is the Red Hat public (and enterprise) extension of
|
||||
the Kubernetes container orchestration platform. Similarly to Kubernetes, OpenShift has
|
||||
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]
|
||||
* 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]
|
||||
|
||||
|
||||
[[cloud-deployment-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
|
||||
server. Options include :
|
||||
server. The options include:
|
||||
|
||||
* AWS Elastic Beanstalk
|
||||
* AWS Code Deploy
|
||||
|
|
@ -250,29 +255,30 @@ server. Options include :
|
|||
* AWS Cloud Formation
|
||||
* AWS Container Registry
|
||||
|
||||
Each has different features and pricing model, here we will describe only the simplest
|
||||
option : AWS Elastic Beanstalk.
|
||||
Each has different features and pricing model. In this document, we describe only the
|
||||
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
|
||||
Beanstalk Java guide], there are two main options to deploy a Java application; You can
|
||||
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 producing a war file. There is no any special
|
||||
configuration required, just follow the official guide.
|
||||
===== Using the Tomcat Platform
|
||||
This option applies to Spring Boot projects that produce a war file. There is no any
|
||||
special configuration required. You need only follow the official guide.
|
||||
|
||||
|
||||
|
||||
===== Using the Java SE platform
|
||||
This option applies to Spring Boot projects producing a jar file and running an embedded
|
||||
===== Using the Java SE Platform
|
||||
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
|
||||
the actual application, running on port 5000. To configure it, add the following to your
|
||||
`application.properties`:
|
||||
the actual application, running on port 5000. To configure it, add the following line to
|
||||
your `application.properties` file:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
|
|
@ -280,12 +286,12 @@ the actual application, running on port 5000. To configure it, add the following
|
|||
----
|
||||
|
||||
|
||||
|
||||
===== Best practices
|
||||
|
||||
====== Uploading binaries instead of sources
|
||||
By default Elastic Beanstalk uploads sources and compiles them in AWS. To upload the
|
||||
binaries instead, add the following to your `.elasticbeanstalk/config.yml` file:
|
||||
[TIP]
|
||||
.Upload binaries instead of sources
|
||||
====
|
||||
By default, Elastic Beanstalk uploads sources and compiles them in AWS. However, it is
|
||||
best to upload the binaries instead. To do so, add the following lines to your
|
||||
`.elasticbeanstalk/config.yml` file:
|
||||
|
||||
|
||||
|
||||
|
|
@ -294,29 +300,31 @@ binaries instead, add the following to your `.elasticbeanstalk/config.yml` file:
|
|||
deploy:
|
||||
artifact: target/demo-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
====== Reduce costs by setting the environment type
|
||||
By default an Elastic Beanstalk environment is load balanced. The load balancer has a cost
|
||||
perspective, to avoid it, set the environment type to "`Single instance`" as described
|
||||
http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html#environments-create-wizard-capacity[in the Amazon documentation].
|
||||
Single instance environments can be created using the CLI as well using the following
|
||||
command:
|
||||
[TIP]
|
||||
.Reduce costs by setting the environment type
|
||||
====
|
||||
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]. You can also create single instance environments by using the CLI
|
||||
and the following command:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
eb create -s
|
||||
----
|
||||
|
||||
====
|
||||
|
||||
|
||||
==== Summary
|
||||
This is one of the easiest ways to get to AWS, but there are more things
|
||||
to cover, e.g.: how to integrate Elastic Beanstalk into any CI / CD tool, using the
|
||||
Elastic Beanstalk maven plugin instead of the CLI, etc. There is a
|
||||
https://exampledriven.wordpress.com/2017/01/09/spring-boot-aws-elastic-beanstalk-example/[blog]
|
||||
covering these topics more in detail.
|
||||
This is one of the easiest ways to get to AWS, but there are more things to cover, such as
|
||||
how to integrate Elastic Beanstalk into any CI / CD tool, use the Elastic Beanstalk Maven
|
||||
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] covering these topics more in detail.
|
||||
|
||||
|
||||
|
||||
|
|
@ -324,15 +332,16 @@ covering these topics more in detail.
|
|||
=== Boxfuse and Amazon Web Services
|
||||
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.
|
||||
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.
|
||||
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
|
||||
AWS account, and installed the latest version of the Boxfuse Client, you can deploy your
|
||||
Spring Boot application to AWS as follows (ensure the application has been built by
|
||||
Maven or Gradle first using, for example, `mvn clean package`):
|
||||
Once you have created a https://console.boxfuse.com[Boxfuse account], connected it to
|
||||
your AWS account, installed the latest version of the Boxfuse Client, and ensured that
|
||||
the application has been built by Maven or Gradle (by using, for example, `mvn clean
|
||||
package`), you can deploy your Spring Boot application to AWS with a command similar to
|
||||
the following:
|
||||
|
||||
[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
|
||||
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
|
||||
your executable jar or war contains an
|
||||
TIP: By default, Boxfuse activates a Spring profile named `boxfuse` on startup. If your
|
||||
executable jar or war contains an
|
||||
https://boxfuse.com/docs/payloads/springboot.html#configuration
|
||||
[`application-boxfuse.properties`]
|
||||
file, Boxfuse will base its configuration based on the properties it contains.
|
||||
[`application-boxfuse.properties`] file, Boxfuse bases its configuration based on the
|
||||
properties it contains.
|
||||
|
||||
At this point `boxfuse` will create an image for your application, upload it,
|
||||
and then configure and start the necessary resources on AWS:
|
||||
At this point, `boxfuse` creates an image for your application, uploads it, and configures
|
||||
and starts the necessary resources on AWS resulting in output similar to the following
|
||||
example:
|
||||
|
||||
[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.
|
||||
|
||||
There's a blog on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spring Boot apps
|
||||
on EC2] as well as https://boxfuse.com/docs/payloads/springboot.html[documentation
|
||||
for the Boxfuse Spring Boot integration] on their website that will get you started with a
|
||||
Maven build to run the app.
|
||||
See the blog post on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spring Boot
|
||||
apps on EC2] as well as the
|
||||
https://boxfuse.com/docs/payloads/springboot.html[documentation for the Boxfuse Spring
|
||||
Boot integration] to get started with a Maven build to run the app.
|
||||
|
||||
|
||||
|
||||
[[cloud-deployment-gae]]
|
||||
=== 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
|
||||
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.
|
||||
|
||||
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,
|
||||
then use the https://cloud.google.com/sdk/downloads[Google Cloud SDK] to push your
|
||||
Spring Boot app into that slot from the command line or CI build.
|
||||
To run in App Engine, you can create a project in the UI first, which sets up a unique
|
||||
identifier for you and also sets up HTTP routes. Add a Java app to the project and leave
|
||||
it empty and then use the https://cloud.google.com/sdk/downloads[Google Cloud SDK] to
|
||||
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
|
||||
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]
|
||||
----
|
||||
|
|
@ -421,8 +432,8 @@ requires. Normally you put this in `src/main/appengine`, and it looks something
|
|||
ENCRYPT_KEY: your_encryption_key_here
|
||||
----
|
||||
|
||||
You can deploy the app, for example, with a Maven plugin by simply adding the project ID
|
||||
to the build configuration:
|
||||
You can deploy the app (for example, with a Maven plugin) by adding the project ID to the
|
||||
build configuration, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -436,31 +447,31 @@ to the build configuration:
|
|||
</plugin>
|
||||
----
|
||||
|
||||
Then deploy with `mvn appengine:deploy` (if you need to authenticate first the build will
|
||||
fail).
|
||||
Then deploy with `mvn appengine:deploy` (if you need to authenticate first, the build
|
||||
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
|
||||
<<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]]
|
||||
== Installing Spring Boot applications
|
||||
In additional to running Spring Boot applications using `java -jar` it is also possible
|
||||
to make fully executable applications for Unix systems. A fully executable jar can be
|
||||
executed like any other executable binary or it can be <<deployment-service,registered
|
||||
with `init.d` or `systemd`>>. This makes it very easy to install and manage Spring Boot
|
||||
applications in common production environments.
|
||||
== Installing Spring Boot Applications
|
||||
In additional to running Spring Boot applications by using `java -jar`, it is also
|
||||
possible to make fully executable applications for Unix systems. A fully executable jar
|
||||
can be executed like any other executable binary or it can be
|
||||
<<deployment-service,registered with `init.d` or `systemd`>>. This makes it very easy to
|
||||
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
|
||||
file. Currently, some tools do not accept this format so you may not always be able to
|
||||
use this technique. For example, `jar -xf` may silently fail to extract a jar or war that
|
||||
has been made fully-executable. It is recommended that you only make your jar or war
|
||||
fully executable if you intend to execute it directly, rather than running it with
|
||||
`java -jar` or deploying it to a servlet container.
|
||||
WARNING: Fully executable jars work by embedding an extra script at the front of the file.
|
||||
Currently, some tools do not accept this format, so you may not always be able to use this
|
||||
technique. For example, `jar -xf` may silently fail to extract a jar or war that has been
|
||||
made fully executable. It is recommended that you only make your jar or war fully
|
||||
executable if you intend to execute it directly, rather than running it with `java -jar`
|
||||
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"]
|
||||
----
|
||||
|
|
@ -473,7 +484,7 @@ To create a '`fully executable`' jar with Maven use the following plugin configu
|
|||
</plugin>
|
||||
----
|
||||
|
||||
With Gradle, the equivalent configuration is:
|
||||
The following example shows the equivalent Gradle configuration:
|
||||
|
||||
[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
|
||||
`my-application` is the name of your artifact). The directory containing the
|
||||
jar will be used as your application's working directory.
|
||||
You can then run your application by typing `./my-application.jar` (where `my-application`
|
||||
is the name of your artifact). The directory containing the jar is used as your
|
||||
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
|
||||
Ubuntu. Other platforms, such as OS X and FreeBSD, will require the use of a custom
|
||||
=== Supported Operating Systems
|
||||
The default script supports most Linux distributions and is tested on CentOS and Ubuntu.
|
||||
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 using either `init.d`
|
||||
or `systemd`.
|
||||
=== Unix/Linux Services
|
||||
Spring Boot application can be easily started as Unix/Linux services by using either
|
||||
`init.d` or `systemd`.
|
||||
|
||||
|
||||
[[deployment-initd-service]]
|
||||
==== Installation as an init.d service (System V)
|
||||
If you've configured Spring Boot's Maven or Gradle plugin to generate a
|
||||
<<deployment-install,fully executable jar>>, and you're not using a custom
|
||||
`embeddedLaunchScript`, then your application can be used as an `init.d` service. Simply
|
||||
symlink the jar to `init.d` to support the standard `start`, `stop`, `restart` and
|
||||
`status` commands.
|
||||
==== Installation as an `init.d` Service (System V)
|
||||
If you configured Spring Boot's Maven or Gradle plugin to generate a <<deployment-install,
|
||||
fully executable jar>>, and you do not use a custom `embeddedLaunchScript`, your
|
||||
application can be used as an `init.d` service. To do so, symlink the jar to `init.d` to
|
||||
support the standard `start`, `stop`, `restart` and `status` commands.
|
||||
|
||||
The script supports the following features:
|
||||
|
||||
* 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`
|
||||
|
||||
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"]
|
||||
----
|
||||
|
|
@ -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
|
||||
Debian based system:
|
||||
Debian based system, you could start it with the following command:
|
||||
|
||||
[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
|
||||
`/var/log/<appname>.log` for errors.
|
||||
|
||||
You can also flag the application to start automatically using your standard operating
|
||||
system tools. For example, on Debian:
|
||||
You can also flag the application to start automatically by using your standard operating
|
||||
system tools. For example, on Debian, you could use the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -544,44 +554,42 @@ system tools. For example, on Debian:
|
|||
|
||||
|
||||
[[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
|
||||
that's being run as an init.d service. It is not intended to be an exhaustive list of
|
||||
everything that should be done to harden an application and the environment in which it
|
||||
runs.
|
||||
NOTE: The following is a set of guidelines on how to secure a Spring Boot application that
|
||||
runs as an init.d service. It is not intended to be an exhaustive list of everything that
|
||||
should be done to harden an application and the environment in which it runs.
|
||||
|
||||
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
|
||||
file. You should never run a Spring Boot application as `root` so your application's jar
|
||||
file should never be owned by root. Instead, create a specific user to run your
|
||||
application and use `chown` to make it the owner of the jar file. For example:
|
||||
the default executable script runs the application as the user who owns the jar file. You
|
||||
should never run a Spring Boot application as `root`, so your application's jar file
|
||||
should never be owned by root. Instead, create a specific user to run your application and
|
||||
use `chown` to make it the owner of the jar file, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chown bootapp:bootapp your-app.jar
|
||||
----
|
||||
|
||||
In this case, the default executable script will run the application as the `bootapp`
|
||||
user.
|
||||
In this case, the default executable script runs the application as the `bootapp` user.
|
||||
|
||||
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
|
||||
`/usr/sbin/nologin`, for example.
|
||||
consider preventing it from using a login shell. For example, you can set the account's
|
||||
shell to `/usr/sbin/nologin`.
|
||||
|
||||
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
|
||||
executed by its owner:
|
||||
executed by its owner, as shown in the following example:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
$ chmod 500 your-app.jar
|
||||
----
|
||||
|
||||
Secondly, you should also take steps to limit the damage if your application or the
|
||||
account that's running it is compromised. If an attacker does gain access, they could make
|
||||
the jar file writable and change its contents. One way to protect against this is to make
|
||||
it immutable using `chattr`:
|
||||
Second, you should also take steps to limit the damage if your application or the account
|
||||
that's running it is compromised. If an attacker does gain access, they could make the jar
|
||||
file writable and change its contents. One way to protect against this is to make it
|
||||
immutable by using `chattr`, as shown in the following example:
|
||||
|
||||
[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
|
||||
<<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
|
||||
secured accordingly. Use `chmod` so that the file can only be read by the owner and use
|
||||
`chown` to make root the owner:
|
||||
startup, the `.conf` file is read and evaluated by the root user. It should be secured
|
||||
accordingly. Use `chmod` so that the file can only be read by the owner and use `chown` to
|
||||
make root the owner, as shown in the following example:
|
||||
|
||||
[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]]
|
||||
==== Installation as a systemd service
|
||||
Systemd is the successor of the System V init system, and is now being used by many modern
|
||||
Linux distributions. Although you can continue to use `init.d` scripts with `systemd`, it
|
||||
is also possible to launch Spring Boot applications using `systemd` '`service`' scripts.
|
||||
==== Installation as a `systemd` Service
|
||||
`systemd` is the successor of the System V init system and is now being used by many
|
||||
modern Linux distributions. Although you can continue to use `init.d` scripts with
|
||||
`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` using
|
||||
the following example and place it in `/etc/systemd/system` directory:
|
||||
Spring Boot application as a `systemd` service, create a script named `myapp.service` and
|
||||
place it in `/etc/systemd/system` directory. The following script offers an example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
|
|
@ -629,19 +638,19 @@ the following example and place it in `/etc/systemd/system` directory:
|
|||
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.
|
||||
|
||||
TIP: Note that `ExecStart` field does not declare the script action command, which means
|
||||
that `run` command is used by default.
|
||||
NOTE: The `ExecStart` field does not declare the script action command, which means that
|
||||
the `run` command is used by default.
|
||||
|
||||
Note that unlike when running as an `init.d` service, user that runs the application, PID
|
||||
file and console log file are managed by `systemd` itself and therefore must be configured
|
||||
using appropriate fields in '`service`' script. Consult the
|
||||
Note that, unlike when running as an `init.d` service, the user that runs the application,
|
||||
the PID file, and the console log file are managed by `systemd` itself and therefore must
|
||||
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.
|
||||
|
||||
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"]
|
||||
----
|
||||
|
|
@ -653,20 +662,20 @@ Refer to `man systemctl` for more details.
|
|||
|
||||
|
||||
[[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
|
||||
customized in a number of ways. For most people, using the default script along with
|
||||
a few customizations is usually enough. If you find you can't customize something that
|
||||
you need to, you can always use the `embeddedLaunchScript` option to write your own
|
||||
file entirely.
|
||||
customized in a number of ways. For most people, using the default script along with a few
|
||||
customizations is usually enough. If you find you cannot customize something that you need
|
||||
to, you can always use the `embeddedLaunchScript` option to write your own file entirely.
|
||||
|
||||
|
||||
|
||||
[[deployment-script-customization-when-it-written]]
|
||||
===== Customizing script when it's written
|
||||
It often makes sense to customize elements of the start script as it's written into the
|
||||
jar file. For example, init.d scripts can provide a "`description`" and, since you know
|
||||
this up front (and it won't change), you may as well provide it when the jar is generated.
|
||||
===== 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 the
|
||||
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
|
||||
Spring Boot Maven or Gradle plugins.
|
||||
|
|
@ -713,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
|
||||
any external config files are loaded.
|
||||
This can be used to set environmental variables such as `JAVA_OPTS` before any external
|
||||
config files are loaded.
|
||||
|
||||
|`logFolder`
|
||||
|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.
|
||||
|
||||
|`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.
|
||||
|
||||
|`useStartStopDaemon`
|
||||
|If the `start-stop-daemon` command, when it's available, should be used to control the
|
||||
process. Defaults to `true`.
|
||||
|Whether the `start-stop-daemon` command, when it's available, should be used to control
|
||||
the process. Defaults to `true`.
|
||||
|
||||
|`stopWaitTime`
|
||||
|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]]
|
||||
===== Customizing 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
|
||||
<<deployment-script-customization-conf-file, config file>>.
|
||||
===== 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 <<deployment-script-customization-conf-file, config
|
||||
file>>.
|
||||
|
||||
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
|
||||
|
||||
|`MODE`
|
||||
|The "`mode`" of operation. The default depends on the way the jar was built, but will
|
||||
usually be `auto` _(meaning it tries to guess if it is an init script by checking if it
|
||||
is a symlink in a directory called `init.d`)_. You can explicitly set it to `service` so
|
||||
that the `stop\|start\|status\|restart` commands work, or to `run` if you just want to
|
||||
run the script in the foreground.
|
||||
|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 is a
|
||||
symlink in a directory called `init.d`). You can explicitly set it to `service` so that
|
||||
the `stop\|start\|status\|restart` commands work or to `run` if you want to run the
|
||||
script in the foreground.
|
||||
|
||||
|`USE_START_STOP_DAEMON`
|
||||
|If the `start-stop-daemon` command, when it's available, should be used to control the
|
||||
process. Defaults to `true`.
|
||||
|Whether the `start-stop-daemon` command, when it's available, should be used to control
|
||||
the process. Defaults to `true`.
|
||||
|
||||
|`PID_FOLDER`
|
||||
|The root name of the pid folder (`/var/run` by default).
|
||||
|
||||
|`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`
|
||||
|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`
|
||||
|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,
|
||||
but if it is not a symlink, or you want to explicitly set the app name this can be
|
||||
useful.
|
||||
|The name of the app. If the jar is run from a symlink, the script guesses the app name if
|
||||
it is not a symlink or you want to explicitly set the app name, this can be useful.
|
||||
|
||||
|`RUN_ARGS`
|
||||
|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`
|
||||
|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`
|
||||
|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.
|
||||
|
||||
|`STOP_WAIT_TIME`
|
||||
|The time in seconds to wait when stopping the application before forcing a shutdown
|
||||
(`60` by default).
|
||||
|The time in seconds to wait when stopping the application before forcing a shutdown (`60`
|
||||
by default).
|
||||
|===
|
||||
|
||||
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`'
|
||||
script. Check the
|
||||
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`' 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 using
|
||||
a `.conf` file. The file is expected next to the jar file and have the same name but
|
||||
suffixed with `.conf` rather than `.jar`. For example, a jar named `/var/myapp/myapp.jar`
|
||||
will use the configuration file named `/var/myapp/myapp.conf`.
|
||||
With the exception of `JARFILE` and `APP_NAME`, the above settings can be configured by
|
||||
using a `.conf` file. The file is expected to be next to the jar file and have the same
|
||||
name but suffixed with `.conf` rather than `.jar`. For example, a jar named
|
||||
`/var/myapp/myapp.jar` uses the configuration file named `/var/myapp/myapp.conf`.
|
||||
|
||||
.myapp.conf
|
||||
[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
|
||||
----
|
||||
|
||||
TIP: You can use a `CONF_FOLDER` environment variable to customize the location of the
|
||||
config file if you don't like it living next to the jar.
|
||||
TIP: If you do not like having the config file next to the jar file, you can set a
|
||||
`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-windows]]
|
||||
=== Microsoft Windows services
|
||||
Spring Boot application can be started as Windows service using
|
||||
=== Microsoft Windows Services
|
||||
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]
|
||||
to the core of Spring Boot describes step-by-step how you can create a Windows service for
|
||||
your Spring Boot application.
|
||||
A sample (https://github.com/snicoll-scratches/spring-boot-daemon[maintained separately])
|
||||
describes step-by-step how you can create a Windows service for your Spring Boot
|
||||
application.
|
||||
|
||||
|
||||
|
||||
[[deployment-whats-next]]
|
||||
== What to read next
|
||||
== What to Read Next
|
||||
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
|
||||
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
|
||||
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 can freely consider other
|
||||
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
|
||||
_<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue