Spring Boot makes it easy to create Spring-powered, production-grade applications and services with absolute minimum fuss. It takes an opinionated view of the Spring platform so that new and existing users can quickly get to the bits they need.
You can use Spring Boot to create stand-alone Java applications that can be started using
java -jar or more traditional WAR deployments. We also provide a command line tool
that runs spring scripts.
Our primary goals are:
- Provide a radically faster and widely accessible getting started experience for all Spring development
- Be opinionated out of the box, but get out of the way quickly as requirements start to diverge from the defaults
- Provide a range of non-functional features that are common to large classes of projects (e.g. embedded servers, security, metrics, health checks, externalized configuration)
- Absolutely no code generation and no requirement for XML configuration
A good place for further reading is the compendium of micro HOWTO guides covering many common use cases.
The Spring Boot CLI is a command line tool that can be used if you want to quickly prototype with Spring. It allows you to run Groovy scripts, which means that you have a familiar Java-like syntax, without so much boilerplate code.
You don't need to use the CLI to work with Spring Boot but it's definitely the quickest way to get a Spring application off the ground.
Note: If you don't want to use the CLI, jump ahead to the Java example.
You need Java SDK v1.6 or higher to run the command line tool
(there are even some issues with the 1.7.0_25 build of openjdk, so stick to earlier
builds or use 1.6 for preference). You should check your current Java installation
before you begin:
$ java -version
You can download the Spring CLI distribution from the Spring software repository:
Cutting edge snapshot distributions are also available.
Once downloaded, follow the
INSTALL instructions
from the unpacked archive. In summary: there is a spring script
(spring.bat for Windows) in a bin/ directory in the .zip file,
or alternatively you can use java -jar with the .jar file (the
script helps you to be sure that the classpath is set correctly).
GVM (the Groovy Environment Manager) can be used for managing multiple
versions of verious Groovy and Java binary packages, including Groovy
itself and the Spring Boot CLI. Get gvm from
the gvm home page and install Spring Boot with
$ gvm install springboot
$ spring --version
Spring Boot v1.0.0.RC1
Note: If you are developing features for the CLI and want easy access to the version you just built, follow these extra instructions.
$ gvm install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.0.0.BUILD-SNAPSHOT-bin/spring-1.0.0.BUILD-SNAPSHOT/
$ gvm use springboot dev
$ spring --version
Spring CLI v1.0.0.BUILD-SNAPSHOT
This will install a local instance of spring called the dev instance inside your gvm repository. It points at your target build location, so every time you rebuild Spring Boot, spring will be up-to-date.
You can see it by doing this:
$ gvm ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 1.0.0.RC1
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
If you are on a Mac and using homebrew, all you need to do to install the Spring Boot CLI is:
$ brew tap pivotal/tap
$ brew install springboot
Homebrew will install spring to /usr/local/bin. Now you can jump right to a
quick start example.
Note: If you don't see the formula, you're installation of brew might be out-of-date. Just execute
brew updateand try again.
Here's a really simple web application. Create a file called app.groovy:
@Controller
class ThisWillActuallyRun {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!"
}
}Then run it from a shell:
$ spring run app.groovy
Note: It will take some time when you first run the application as dependencies are downloaded, subsequent runs will be much quicker.
Open http://localhost:8080 in your favorite web browser and you should see the following output:
Hello World!
If you don't want to use the command line tool, or you would rather work using Java and an IDE you can. Here is how you build the same example using Java.
You will need to install Apache Maven v3.0.5 or above to build this example.
Create a pom.xml to import the appropriate Spring Boot starters:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.0.0.RC1</version>
</parent>
<!-- Add typical dependencies for a web application -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<!-- Package as an executable JAR -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<!-- Allow access to Spring milestones and snapshots -->
<!-- (you don't need this if you are using anything after 1.0.0.RELEASE) -->
<repositories>
<repository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
</project>Note: If you prefer Gradle as your build system, we provide a plugin that can help you package an executable JAR.
Here is the main class for a simple web application (just save the content to
src/main/java/SampleController.java):
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
import org.springframework.web.bind.annotation.*;
@Controller
@EnableAutoConfiguration
public class SampleController {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!";
}
public static void main(String[] args) throws Exception {
SpringApplication.run(SampleController.class, args);
}
}Other than import statements, the main difference between this
example and the earlier Groovy script is the main() method that calls
SpringApplication and the @EnableAutoConfiguration annotation.
You can run this application by building a jar and executing it:
$ mvn package
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
Open http://localhost:8080 in your favorite web browser and you should see the following output:
Hello World!
You don't need to build from source to use Spring Boot (it's in repo.spring.io), but if you want to try out the latest and greatest, Spring Boot can be built with maven v3.0.5 or above.
$ mvn clean install
NOTE: You may need to increase the amount of memory available to Maven by setting a
MAVEN_OPTSenvironment variable with the value-Xmx512m -XX:MaxPermSize=128m
Also see CONTRIBUTING.md if you wish to submit pull requests, and in particular please fill out the Contributor's Agreement before your first change however trivial. (Or if you filed such an agreement already for another project just mention that in your pull request.)
There are a number of modules in Spring Boot, if you want learn more about each one please refer to the appropriate README.md file:
Note: We are currently still working on documentation for Spring Boot.
The main library providing features that support the other parts of Spring Boot, these include:
- The
SpringApplicationclass, providing static convenience methods that make it easy to write a stand-alone Spring Application. Its sole job is to create and refresh an appropriate SpringApplicationContext - Embedded web applications with a choice of container (Tomcat or Jetty for now)
- First class externalized configuration support
- Convenience
ApplicationContextinitializers, including support for sensible logging defaults
Spring Boot can configure large parts of common applications based on the content
of their classpath. A single @EnableAutoConfiguration annotation triggers
auto-configuration of the Spring context.
Auto-configuration attempts to deduce which beans a user might need. For example, If
HSQLDB is on the classpath, and the user has not configured any database connections,
then they probably want an in-memory database to be defined. Auto-configuration will
always back away as the user starts to define their own beans.
See spring-boot-autoconfigure/README.md.
Starters are a set of convenient dependency descriptors that you can include in
your application. You get a one-stop-shop for all the Spring and related technology
that you need without having to hunt through sample code and copy paste loads of
dependency descriptors. For example, if you want to get started using Spring and JPA for
database access just include the spring-boot-starter-data-jpa dependency in your
project, and you are good to go.
See spring-boot-starters/README.md.
The Spring command line application compiles and runs Groovy source, making it super easy to write the absolute minimum of code to get an application running. Spring CLI can also watch files, automatically recompiling and restarting when they change.
See spring-boot-cli/README.md.
Spring Boot Actuator provides additional auto-configuration to decorate your application with features that make it instantly deployable and supportable in production. For instance if you are writing a JSON web service then it will provide a server, security, logging, externalized configuration, management endpoints, an audit abstraction, and more. If you want to switch off the built in features, or extend or replace them, it makes that really easy as well.
See spring-boot-actuator/README.md.
Spring Boot Loader provides the secret sauce that allows you to build a single jar file
that can be launched using java -jar. Generally you will not need to use
spring-boot-loader directly, but instead work with the
Gradle or
Maven plugin.
See spring-boot-loader/README.md.
Groovy samples for use with the command line application are available in
spring-boot-cli/samples. To run the CLI samples type
spring run <sample>.groovy from samples directory.
Java samples are available in spring-boot-samples and should
be built with maven and run by invoking java -jar target/<sample>.jar. The following java
samples are provided:
- spring-boot-sample-simple - A simple command line application
- spring-boot-sample-tomcat - Embedded Tomcat
- spring-boot-sample-jetty - Embedded Jetty
- spring-boot-sample-actuator - Simple REST service with production features
- spring-boot-sample-actuator-ui - A web UI example with production features
- spring-boot-sample-web-ui - A thymeleaf web application
- spring-boot-sample-web-static - A web application service static files
- spring-boot-sample-batch - Define and run a Batch job in a few lines of code
- spring-boot-sample-data-jpa - Spring Data JPA + Hibernate + HSQLDB
- spring-boot-sample-integration - A spring integration application
- spring-boot-sample-profile -
example showing Spring's
@profilesupport - spring-boot-sample-traditional -
shows more traditional WAR packaging
(but also executable using
java -jar) - spring-boot-sample-xml -
Example show how Spring Boot can be mixed with traditional XML configuration (we
generally recommend using Java
@Configurationwhenever possible)
The spring.io site contains several guides that show how to use Spring Boot step-by-step:
- Building an Application with Spring Boot is a very basic guide that shows you how to create a simple application, run it and add some management services.
- Building a RESTful Web Service with Spring Boot Actuator is a guide to creating a REST web service and also shows how the server can be configured.
- Converting a Spring Boot JAR Application to a WAR shows you how to run applications in a web server as a WAR file.