initializr/README.adoc

= Spring Initializr image:https://badges.gitter.im/spring-io/initializr.svg[link="https://gitter.im/spring-io/initializr?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]

:boot-doc: http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle
:code: https://github.com/spring-io/initializr/blob/master
:docs: http://docs.spring.io/initializr/docs/current-SNAPSHOT/reference

Spring Initializr provides an extensible API to generate quickstart projects. It also
provides a configurable service: you can see our default instance at
link: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 metadata in a well-known
format to allow third-party clients to provide the necessary assistance.

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 {code}/initializr-service/src/main/resources/application.yml[configuration of our
instance] for an example. Such configuration is also described in details in the
documentation.

NOTE: We use the continuous deployment technique to manage our instance; check the
https://github.com/spring-io/initializr/milestones[milestones page] for an overview
of changes

== Installation and Getting Started
The {docs}/htmlsingle/[reference documentation] is published in
{docs}/htmlsingle/[HTML] and {docs}/epub/spring-initializr-reference.epub[EPUB] formats.


== Modules
Spring Initializr has the following modules:

* `initializr-generator`: standalone project generation library that can be reused
in many environments (including embedded in your own project)
* `initializr-web`: REST endpoints and web interface
* `initializr-actuator`: optional module to provide statistics and metrics on project
generation
* `initializr-docs`: documentation

`initializr-service` is an additional module that represents the production instance
that is available at link:https://start.spring.io[]. It is not enabled by default but
you can enable the `full` profile in your IDE to easily run it locally.

== Supported interfaces

Spring Initializr can be used as follows:

* With your browser (i.e. link:https://start.spring.io[])
* In your IDE if you are using STS, IntelliJ IDEA Ultimate or NetBeans (with
https://github.com/AlexFalappa/nb-springboot[this plugin])
* On the command-line with {boot-doc}/#cli-init[the Spring Boot CLI] or simply with
`cURL` or `HTTPie`

[TIP]
====
You can "curl" an instance to get a usage page with examples (try
`curl start.spring.io`)
====

== Generating a project
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

[source,bash]
----
$ curl https://start.spring.io/starter.zip -o demo.zip
----

The web ui exposes a bunch of options that you can configure. These are mapped to the
following request attributes:

* 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
<<metadata,metadata>>.
* `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
<<metadata,metadata>>.
* `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:

[source,bash]
----
$ 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.

[[customize-form]]
== Customize form inputs

You can share or bookmark URLs that will automatically customize form inputs. For
instance, the following URL from the default instance uses `groovy` by default and
set the name to `Groovy Sample`:

[source,bash]
----
https://start.spring.io/#!language=groovy&name=Groovy%20Sample
----

The following hashbang parameters are supported: `type`, `groupId`, `artifactId`,
`name`, `description`, `packageName`, `packaging`, `javaVersion` and `language`.
Review the section above for a description of each of them.

[[metadata]]
== Service metadata

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

[source,bash]
----
$ curl -H 'Accept: application/json' https://start.spring.io
----

NOTE: As stated above, if you use `curl` without an accept header, you'll retrieve a
human readable text version of the metadata. `HTTPie` is also supported:

[source,bash]
----
$ http https://start.spring.io Accept:application/json
----

The metadata 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 metadata 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 metadata are
{docs}/htmlsingle/#metadata-format[available in the documentation].

== Running your own instance

You can easily run your own instance. The `initializr-web` modules 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 documentation for a
{docs}/htmlsingle/#configuration-format[description of the configuration] and
{code}/initializr-service/application.yml[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:

[source,groovy]
----
package org.acme.myapp

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

NOTE: Spring Initializr is not available on Maven central yet so you will have to
build it <<build,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:

[source,bash]
----
$ spring run my-instance.groovy
----

You may also want to <<run-app,run the default instance locally>>.


[[build]]
== Building from Source

You need Java (1.8 or better), Maven 3.2+ and a bash-like shell.

[[building]]
=== Building

Just invoke the build at the root of the project

[indent=0]
----
    $ ./mvnw 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:

[indent=0]
----
    $ mvn verify -PsmokeTests
----

If you want to build both the library and the service, you can enable the `full`
profile:

[indent=0]
----
    $ ./mvnw clean install -Pfull
----


[[run-app]]
=== Running the app locally

Once you have <<building, built the library>>, you can easily start the app as any
other Spring Boot app from the `initializr-service` directory:

[indent=0]
----
    $ cd initializr-service
    $ ./mvnw spring-boot:run
----

[[run-ide]]
=== Running the app in an IDE

You should be able to import the projects into your IDE with no problems. Once there you
can run the `initializr-service` from its main method, debug it, and it will reload if
you make changes to other modules. (You may need to manually enable the "full" profile.)
This is the recommended way to operate while you are developing the application,
especially the UI.


## Deploying to Cloud Foundry

If you are on a Mac and using http://brew.sh/[homebrew], install the Cloud Foundry
CLI:

[indent=0]
----
    $ brew install cloudfoundry-cli
----

Alternatively, download a suitable binary for your platform from
https://console.run.pivotal.io/tools[Pivotal Web Services].

You should ensure that the application name and URL (name and host values) are
suitable for your environment before running `cf push`.

First, make sure that you have <<building, built the library>>, then make sure first
that the jar has been created:

[indent=0]
----
    $ cd initializr-service
    $ ./mvnw package
----

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

[indent=0]
----
    $ cf push your-initializr -p target/initializr-service.jar
----

== License
Spring Initializr is Open Source software released under the
http://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].