Spring Initializr

Spring Initializr is a configurable service to generate a quickstart project. You can see our default instance at https://start.spring.io. It provides a simple web UI to configure the project to generate and endpoints that you can use via plain HTTP.

Spring Initializr also exposes an endpoint that serves its meta-data in a well-known format to allow third-party clients to provide the necessary assistance. Spring Boot CLI is using this mechanism to offer a command-line project generator; STS uses it in a similar way to offer a project creation wizard.

Finally, Initializr offers a configuration structure to define all the aspects related to the project to generate: list of dependencies, supported java and boot versions, etc. Check the configuration of our instance for an example. Such configuration is also described in details on the wiki.

Note	We use the continuous deployment technique to manage our instance; check the changelog for an overview of changes

Generating a project

There are many ways you can use to generate a project using Spring Initializr. You can obviously use the embedded web UI available from the root context. Recent versions of STS provide a wizard to assist you in the creation of your new project. As from Spring Boot 1.2, the CLI has an init command to create a new project from the command-line. Using the meta-data, one can easily create its own client.

If you click on "Generate Project" on the web ui of our instance, it will download a project archive with a Maven-based project and the necessary infrastructure to start a basic Spring Boot app.

You could achieve the same result with a simple curl command

$ curl https://start.spring.io/starter.zip -o demo.zip

The following request attributes are supported:

• Basic information for the generated project: groupId, artifactId, version, name, description and packageName

  • The name attribute is also used to generate a default application name. The logic is that the name of the application is equal to the name attribute with an Application suffix (unless said suffix is already present). Of course, if the specified name contains an invalid character for a java identifier, Application is used as fallback.

  • The artifactId attribute not only defines the identifier of the project in the build but also the name of the generated archive.

• dependencies (or style): the identifiers of the dependencies to add to the project. Such identifiers are defined through configuration and are exposed in the meta-data.

• type: the kind of project to generate (e.g. maven-project). Again, each service exposes an arbitrary number of supported types and these are available in the meta-data.

• javaVersion: the language level (e.g. 1.8).

• bootVersion: the Spring Boot version to use (e.g. 1.2.0.RELEASE).

• language: the programming language to use (e.g. java).

• packaging: the packaging of the project (e.g. jar).

• applicationName: the name of the application class (inferred by the name attribute by default).

• baseDir: the name of the base directory to create in the archive. By default, the project is stored in the root.

This command generates an another-project directory holding a Gradle web-based Groovy project using the actuator:

$ curl https://start.spring.io/starter.tgz -d dependencies=web,actuator \
-d language=groovy -d type=gradle-project -d baseDir=another-project | tar -xzvf -

Note	The /starter.tgz endpoint offers the same feature as /starter.zip but generates a compressed tarball instead.

You could use this infrastructure to create your own client since the project is generated via a plain HTTP call.

Service meta-data

The service meta-data is used by the web UI and is exposed to ease the creation of third-party clients. You can grab the meta-data by curling the root

$ curl -H 'Accept: application/json' https://start.spring.io

Note	If you use curl without an accept header, you’ll retrieve a human readable text version of the metadata. HTTPie is also supported.

The meta-data basically lists the capabilities of the service, that is the available options for all request parameters (dependencies, type, bootVersion, etc.) The web UI uses that information to initialize the select options and the tree of available dependencies.

The meta-data also lists the default values for simple text parameter (i.e. the default name for the project).

Note	More details about the structure of the meta-data are available on the wiki.

Running your own instance

You can easily run your own instance. Spring Initializr defines a library that provides all the default features. The library uses Spring Boot so when it is added to a project, it will trigger the necessary auto-configuration to deploy the service.

You first need to create or update your configuration to define the necessary attributes that your instance will use. Again, check the wiki for a description of the configuration and review our own config for a sample.

You can integrate the library in a traditional Java-based project or by writing the super-simple script below

package org.acme.myapp

@Grab('io.spring.initalizr:initializr:1.0.0.BUILD-SNAPSHOT')
class YourInitializrApplication { }

Note	Spring Initializr is not available on Maven central yet so you will have to build the library from source in order to use it in your own environment.

Once you have created that script (my-instance.groovy), place your configuration in the same directory and simply execute this command to start the service:

$ spring run my-instance.groovy

You may also want to run the default instance locally.

Building from Source

You need Java (1.6 or better) and a bash-like shell.

If you are on a Mac and using homebrew, all you need to do to install it is:

$ brew tap pivotal/tap
$ brew install springboot

It will install /usr/local/bin/spring. You can jump right to Running the app locally.

An alternative way to install the spring command line interface can be installed like this:

$ curl start.spring.io/install.sh | bash

After running that command you should see a spring directory:

$ ./spring/bin/spring --help

usage: spring [--help] [--version]
   <command> [<args>]
...

You could add that bin directory to your PATH (the examples below assume you did that).

If you don’t have curl or zip you can probably get them (for Windows users we recommend cygwin), or you can download the zip file and unpack it yourself.

Building

The library is located in the initializr directory.

$ cd initializr
$ mvn clean install

If you want to run the smoke tests using Geb, you need to enable the smokeTests profile. Firefox should also be installed on your machine

$ cd initializr
$ mvn verify -PsmokeTests

Running the app locally

Once you have built the library, you can easily start the app using the spring command from the initializr-service directory:

$ cd initializr-service
   $ spring run app.groovy

Deploying to Cloud Foundry

If you are on a Mac and using homebrew, install the Cloud Foundry CLI:

$ brew install cloudfoundry-cli

Alternatively, download a suitable binary for your platform from Pivotal Web Services.

An example Cloud Foundry manifest.yml file is provided. You should ensure that the application name and URL (name and host values) are suitable for your environment before running cf push.

You can jar up the app and make it executable in any environment.

$ spring jar start.jar app.groovy

Once the jar has been created, you can push the application:

$ cf push start -p start.jar -n start-<space>

Where <space> is the name of the space. As a failsafe, and a reminder to be explicit, the deployment will fail in production without the -n. It is needed to select the route because there is a manifest that defaults it to start-development.

License

Spring Initializr is Open Source software released under the Apache 2.0 license.