initializr/README.adoc

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

Spring Initializr is a configurable service to generate a quickstart project. 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
{wiki}/Metadata-format[meta-data] in a well-known format to allow third-party
clients to provide the necessary assistance. {boot-doc}/#cli-init[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 {code}/initializr-service/application.yml[configuration of our instance] for an example. Such
configuration is {wiki}/Configuration-format[also described in details on the wiki].

NOTE: We use the continuous deployment technique to manage our instance; check the
link:CHANGELOG.adoc[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 https://start.spring.io[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,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

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

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

[[meta-data]]
== 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

[source,bash]
----
$ 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 {wiki}/Metadata-format[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 {wiki}/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.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 <<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.6 or better) and a bash-like shell.

If you are on a Mac and using http://brew.sh/[homebrew], all you need to do to install it is:

[indent=0]
----
    $ brew tap pivotal/tap
    $ brew install springboot
----

It will install `/usr/local/bin/spring`. You can jump right to <<run-app>>.

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

[indent=0]
----
    $ curl start.spring.io/install.sh | bash
----

After running that command you should see a `spring` directory:

[indent=0]
----
    $ ./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 http://cygwin.org[cygwin]), or you can
download the http://start.spring.io/spring.zip[zip file] and unpack
it yourself.

[[building]]
=== Building

The library is located in the `initializr` directory.

[indent=0]
----
    $ 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

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


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

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

[indent=0]
----
	$ cd initializr-service
    $ spring run app.groovy
----

## 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].

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.

[indent=0]
----
    $ spring jar start.jar app.groovy
----

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

[indent=0]
----
    $ 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
http://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].