Spring Boot

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

Spring Boot CLI

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.

Installing the CLI

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

Manual installation

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).

Installation with GVM

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 v0.5.0.M6

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-0.5.0.BUILD-SNAPSHOT-bin/spring-0.5.0.BUILD-SNAPSHOT/
$ gvm use springboot dev
$ spring --version
Spring CLI v0.5.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
   * 0.5.0.M6

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

OSX Homebrew installation

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 update and try again.

Quick start script example

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!

Spring Boot with Java

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.

Quick start Maven POM

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>0.5.0.M6</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 0.5.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.

Quick start Java example

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!

Building Spring Boot from source

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_OPTS environment 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.)

Samples

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 build with maven and run use 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 @profile support
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 @Configuration whenever possible)

Guides

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.

tomflynn/spring-boot

Spring Boot

Spring Boot CLI

Installing the CLI

Manual installation

Installation with GVM

OSX Homebrew installation

Quick start script example

Spring Boot with Java

Quick start Maven POM

Quick start Java example

Building Spring Boot from source

Further Reading

spring-boot

spring-boot-autoconfigure

spring-boot-starters

spring-boot-cli

spring-boot-actuator

spring-boot-loader

Samples

Guides