Skip to content

Commit

Permalink
Merge branch 'spring-projectsgh-1117'
Browse files Browse the repository at this point in the history
  • Loading branch information
philwebb committed Apr 9, 2015
2 parents ffc5d56 + ed57adb commit ba2ea30
Show file tree
Hide file tree
Showing 25 changed files with 907 additions and 39 deletions.
12 changes: 12 additions & 0 deletions spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -383,6 +383,18 @@ want the other Boot features but not this one)
|`customConfiguration`
|The name of the custom configuration which is used to populate the nested lib directory
(without specifying this you get all compile and runtime dependencies).

|`executable`
|Boolean flag to indicate if jar files are fully executable on Unix like operating
systems. Defaults to `true`.

|`embeddedLaunchScript`
|The embedded launch script to prepend to the front of the jar if it is fully executable.
If not specified the 'Spring Boot' default script will be used.

|`embeddedLaunchScriptProperties`
|Additional properties that to be expanded in the launch script. The default script
supports a `mode` property which can contain the values `auto`, `service` or `run`.
|===


Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,20 @@
[[cloud-deployment]]
= Deploying to the cloud
[[deployment]]
== Deploying Spring Boot applications

[partintro]
--
Spring Boot's flexible packaging options provide a great deal of choice when it comes to
deploying your application. You can easily deploy Spring Boot applications to a variety
of cloud platforms, to a container images (such as Docker) or to virtual/real machines.

This section covers some of the more common deployment scenarios.
--



[[cloud-deployment]]
== Deploying to the cloud

Spring Boot's executable jars are ready-made for most popular cloud PaaS
(platform-as-a-service) providers. These providers tend to require that you
"`bring your own container`"; they manage application processes (not Java applications
Expand All @@ -23,12 +35,11 @@ to run packaged within it.
In this section we'll look at what it takes to get the
<<getting-started.adoc#getting-started-first-application, simple application that we
developed>> in the "`Getting Started`" section up and running in the Cloud.
--



[[cloud-deployment-cloud-foundry]]
== Cloud Foundry
=== Cloud Foundry
Cloud Foundry provides default buildpacks that come into play if no other buildpack is
specified. The Cloud Foundry https://github.com/cloudfoundry/java-buildpack[Java buildpack]
has excellent support for Spring applications, including Spring Boot. You can deploy
Expand Down Expand Up @@ -102,7 +113,7 @@ able to hit the application at the URI given, in this case


[[cloud-deployment-cloud-foundry-services]]
=== Binding to services
==== Binding to services
By default, metadata about the running application as well as service connection
information is exposed to the application as environment variables (for example:
`$VCAP_SERVICES`). This architecture decision is due to Cloud Foundry's polyglot
Expand Down Expand Up @@ -142,7 +153,7 @@ auto-configuration support and a `spring-boot-starter-cloud-connectors` starter


[[cloud-deployment-heroku]]
== Heroku
=== Heroku
Heroku is another popular PaaS platform. To customize Heroku builds, you provide a
`Procfile`, which provides the incantation required to deploy an application. Heroku
assigns a `port` for the Java application to use and then ensures that routing to the
Expand Down Expand Up @@ -225,7 +236,7 @@ Your application should now be up and running on Heroku.


[[cloud-deployment-openshift]]
== Openshift
=== Openshift
https://www.openshift.com/[Openshift] is the RedHat public (and enterprise) PaaS solution.
Like Heroku, it works by running scripts triggered by git commits, so you can script
the launching of a Spring Boot application in pretty much any way you like as long as the
Expand Down Expand Up @@ -288,14 +299,85 @@ run the app.


[[cloud-deployment-gae]]
== Google App Engine
=== Google App Engine
Google App Engine is tied to the Servlet 2.5 API, so you can't deploy a Spring Application
there without some modifications. See the <<howto.adoc#howto-servlet-2-5, Servlet 2.5 section>>
of this guide.


[[deployment-service]]
== Installing Spring Boot applications
In additional to running Spring Boot applications using `java -jar` it is also possible
to execute applications directly on Unix systems (Linux, OSX, FreeBSD etc). This makes it
very easy to install and manage Spring Boot applications in common production
environments. As long as you are generating '`fully executable`' jars from your build, and
you are not using a custom `embeddedLaunchScript`, the following techniques can be used.



=== Unix/Linux services
Spring Boot application can be easily started as Unix/Linux services using either `init.d`
or `systemd`.



==== Installation as a init.d (system v) service
The default executable script that is embedded into Spring Boot executable jars will act
as an `init.d` script when it is symlinked to `/etc/init.d`. The standard `start`, `stop`,
`restart` and `status` commands can be used. The script supports the following features:

* Starts the services as the user that owns the jar file
* Tracks application PIDs using `/var/run/<appname>.pid`
* Writes console logs to `/var/log/<appname>.log`

Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a
Spring Boot application as an `init.d` service simply create a symlink:

[indent=0,subs="verbatim,quotes,attributes"]
----
$ sudo link -s /var/myapp/myapp.jar /etc/init.d/myapp
----

TIP: It is advisable to create a specific user account to run you application. Ensure
that you have set the owner of the jar file using `chown` before installing your service.

[[cloud-deployment-whats-next]]
Once installed, you can start and stop the service in the usual way. You can also flag the
application to start automatically using your standard operating system tools. For example,
if you use Debian:

[indent=0,subs="verbatim,quotes,attributes"]
----
$ update-rc.d myapp defaults <priority>
----



==== Installation as a systemd service
Systemd is the successor to `init.d` scripts, and now being used by many many modern Linux
distributions. Although you can continue to use `init.d` script with `systemd`, it is also
possible to launch Spring Boot applications using `systemd` '`service`' scripts.

For example, to run a Spring Boot application installed in `var/myapp` you can add the
following script in `/etc/systemd/system/myapp.service`:

[indent=0]
----
[Unit]
Description=myapp
After=syslog.target
[Service]
ExecStart=/var/myapp/myapp.jar
[Install]
WantedBy=multi-user.target
----

TIP: Remember to change the `Description` and `ExecStart` fields for your application.



[[deployment-whats-next]]
== What to read next
Check out the http://www.cloudfoundry.com/[Cloud Foundry], https://www.heroku.com/[Heroku]
and https://www.openshift.com[Openshift] web sites for more information about the kinds of
Expand All @@ -307,6 +389,3 @@ The next section goes on to cover the _<<spring-boot-cli.adoc#cli, Spring Boot C
or you can jump ahead to read about
_<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.




Original file line number Diff line number Diff line change
Expand Up @@ -136,10 +136,9 @@ When you're ready to push your Spring Boot application to production, we've got
== Advanced topics
Lastly, we have a few topics for the more advanced user.

* *Deploy to the cloud:*
<<cloud-deployment.adoc#cloud-deployment-cloud-foundry, Cloud Foundry>> |
<<cloud-deployment.adoc#cloud-deployment-heroku, Heroku>> |
<<cloud-deployment.adoc#cloud-deployment-cloudbees, CloudBees>>
* *Deploy Spring Boot Applications:*
<<deployment.adoc#cloud-deployment, Cloud Deployment>> |
<<deployment.adoc#deployment-service, OS Service>>
* *Build tool plugins:*
<<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven>> |
<<build-tool-plugins.adoc#build-tool-plugins-gradle-plugin, Gradle>>
Expand Down
2 changes: 1 addition & 1 deletion spring-boot-docs/src/main/asciidoc/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ include::getting-started.adoc[]
include::using-spring-boot.adoc[]
include::spring-boot-features.adoc[]
include::production-ready-features.adoc[]
include::cloud-deployment.adoc[]
include::deployment.adoc[]
include::spring-boot-cli.adoc[]
include::build-tool-plugins.adoc[]
include::howto.adoc[]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1043,7 +1043,7 @@ If you want to explore some of the concepts discussed in this chapter, you can t
look at the actuator {github-code}/spring-boot-samples[sample applications]. You also
might want to read about graphing tools such as http://graphite.wikidot.com/[Graphite].

Otherwise, you can continue on, to read about <<cloud-deployment.adoc#cloud-deployment,
'`cloud deployment options`'>> or jump ahead
Otherwise, you can continue on, to read about <<deployment.adoc#deployment,
'`deployment options`'>> or jump ahead
for some in-depth information about Spring Boot's
_<<build-tool-plugins.adoc#build-tool-plugins, build tool plugins>>_.
4 changes: 2 additions & 2 deletions spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
[partintro]
--
This section goes into more detail about how you should use Spring Boot. It covers topics
such as build systems, auto-configuration and run/deployment options. We also cover some
Spring Boot best practices. Although there is nothing particularly special about
such as build systems, auto-configuration and how to run your applications. We also cover
some Spring Boot best practices. Although there is nothing particularly special about
Spring Boot (it is just another library that you can consume), there are a few
recommendations that, when followed, will make your development process just a
little easier.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@

package org.springframework.boot.gradle

import java.io.File;
import java.util.Map;

import org.springframework.boot.loader.tools.Layout
import org.springframework.boot.loader.tools.Layouts

Expand Down Expand Up @@ -130,4 +133,21 @@ public class SpringBootPluginExtension {
*/
boolean applyExcludeRules = true;

/**
* If a fully executable jar (for *nix machines) should be generated by prepending a
* launch script to the jar.
*/
boolean executable = true;

/**
* The embedded launch script to prepend to the front of the jar if it is fully
* executable. If not specified the 'Spring Boot' default script will be used.
*/
File embeddedLaunchScript;

/**
* Properties that should be expanded in the embedded launch script.
*/
Map<String,String> embeddedLaunchScriptProperties;

}
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@
import org.gradle.api.tasks.TaskAction;
import org.gradle.api.tasks.bundling.Jar;
import org.springframework.boot.gradle.SpringBootPluginExtension;
import org.springframework.boot.loader.tools.DefaultLaunchScript;
import org.springframework.boot.loader.tools.LaunchScript;
import org.springframework.boot.loader.tools.Repackager;
import org.springframework.util.FileCopyUtils;

Expand Down Expand Up @@ -80,6 +82,10 @@ public void setClassifier(String classifier) {
this.classifier = classifier;
}

void setOutputFile(File file) {
this.outputFile = file;
}

@TaskAction
public void repackage() {
Project project = getProject();
Expand Down Expand Up @@ -170,7 +176,8 @@ private void repackage(File file) {
}
repackager.setBackupSource(this.extension.isBackupSource());
try {
repackager.repackage(file, this.libraries);
LaunchScript launchScript = getLaunchScript();
repackager.repackage(file, this.libraries, launchScript);
}
catch (IOException ex) {
throw new IllegalStateException(ex.getMessage(), ex);
Expand Down Expand Up @@ -201,6 +208,15 @@ else if (getProject().getTasks().getByName("run").hasProperty("main")) {
getLogger().info("Setting mainClass: " + mainClass);
repackager.setMainClass(mainClass);
}

private LaunchScript getLaunchScript() throws IOException {
if (this.extension.isExecutable()) {
return new DefaultLaunchScript(this.extension.getEmbeddedLaunchScript(),
this.extension.getEmbeddedLaunchScriptProperties());
}
return null;
}

}

/**
Expand Down Expand Up @@ -228,10 +244,7 @@ protected String findMainMethod(java.util.jar.JarFile source) throws IOException
}
}
}
}

void setOutputFile(File file) {
this.outputFile = file;
}

}
Loading

0 comments on commit ba2ea30

Please sign in to comment.