mirror of
https://gitee.com/dcren/initializr.git
synced 2025-04-05 17:38:06 +08:00
620 lines
21 KiB
Plaintext
620 lines
21 KiB
Plaintext
[[configuration-guide]]
|
|
= Configuration Guide
|
|
|
|
[partintro]
|
|
--
|
|
This section describes how you can create your own instance of the service and tune it for
|
|
your needs, and also how you can configure an existing instance. You'll also find some
|
|
advanced tips to make sure the available options are consistent with the chosen Spring
|
|
Boot generation.
|
|
--
|
|
|
|
|
|
|
|
[[create-instance]]
|
|
== Creating your own instance
|
|
Spring Initializr is split across three main modules:
|
|
|
|
* `initializr-generator`: standalone project generation library that can be reused in
|
|
many environments (including embedded in your own project)
|
|
* `initializr-web`: API endpoints and web interface
|
|
* `initializr-actuator`: optional module to provide statistics and metrics on project
|
|
generation
|
|
|
|
Because it contains several auto-configurations, creating your own instance is quite easy,
|
|
actually you could get started using Spring Initializr itself to generate a starting point!
|
|
|
|
Create a new project with the `web` dependency and add the following dependency:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
<dependency>
|
|
<groupId>io.spring.initializr</groupId>
|
|
<artifactId>initializr-web</artifactId>
|
|
<version>{spring-initializr-version}</version>
|
|
</dependency>
|
|
----
|
|
|
|
Or if you are using Gradle:
|
|
|
|
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
compile("io.spring.initializr:initializr-web:{spring-initializr-version}")
|
|
----
|
|
|
|
If you start the application, you'll see the familiar interface but none of the drop down
|
|
lists have values (except the one for the Spring Boot version, we will
|
|
<<create-instance-boot-versions,come back to that later>>). In the rest of this section,
|
|
we will configure those basic settings.
|
|
|
|
[TIP]
|
|
====
|
|
Most of the settings are configured via `application.properties` using the `initializr`
|
|
namespace. Because the configuration is highly hierarchical, we recommend using the yaml
|
|
format that is more readable for such structure. If you agree, go ahead and rename
|
|
`application.properties` to `application.yml`.
|
|
====
|
|
|
|
|
|
|
|
[[create-instance-basic-settings]]
|
|
=== Configuring basic settings
|
|
Most of the drop-down lists are configured via a simple list-based structure where each
|
|
entry has an `id`, a `name` and whether that entry is the default or not. If no `name` is
|
|
provided, the `id` is used instead.
|
|
|
|
Let's configure the languages and the Java versions we want to support:
|
|
|
|
[source,yaml,indent=0]
|
|
----
|
|
initializr:
|
|
javaVersions:
|
|
- id: 9
|
|
default: false
|
|
- id: 1.8
|
|
default: true
|
|
languages:
|
|
- name: Java
|
|
id: java
|
|
default: true
|
|
- name: Kotlin
|
|
id: kotlin
|
|
default: false
|
|
----
|
|
|
|
If you click on the "Switch to the full version" link, the two drop down lists now offer
|
|
the options and default values defined above.
|
|
|
|
Spring Initializr supports `java`, `groovy` and `kotlin` and additional languages can be
|
|
added in your own customization.
|
|
|
|
The available packagings are also configurable that way:
|
|
|
|
[source,yaml,indent=0]
|
|
----
|
|
initializr:
|
|
packagings:
|
|
- name: Jar
|
|
id: jar
|
|
default: true
|
|
- name: War
|
|
id: war
|
|
default: false
|
|
----
|
|
|
|
These two packaging types are the only one explicitly supported at the moment.
|
|
|
|
|
|
|
|
[[create-instance-boot-versions]]
|
|
=== Configuring available Spring Boot versions
|
|
If you look at http://projects.spring.io/spring-boot[the project home page for Spring
|
|
Boot], the latest versions are displayed. And you've probably noticed that they match the
|
|
drop down list that you automatically get with a default instance of the Initializr. The
|
|
reason for that is that Spring Initializr calls an API on spring.io to retrieve the
|
|
latest versions automatically. This makes sure that you always get the latest available
|
|
versions.
|
|
|
|
If that's not what you want, you need to override the `InitializrMetadataProvider` bean to
|
|
provide your own metadata for the service. For instance, you could swap to an
|
|
implementation that always returns the contents of your configuration file:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
@Bean
|
|
public InitializrMetadataProvider initializrMetadataProvider(
|
|
InitializrProperties properties) {
|
|
InitializrMetadata metadata = InitializrMetadataBuilder
|
|
.fromInitializrProperties(properties).build();
|
|
return new SimpleInitializrMetadataProvider(metadata);
|
|
}
|
|
----
|
|
|
|
The thing to remember is that, by default, you don't have to worry about upgrading your
|
|
instance when a new Spring Boot version is released. However, you may need to
|
|
<<create-instance-advanced-config-caching,configure caching>> to avoid requesting that
|
|
service too often.
|
|
|
|
|
|
|
|
[[create-instance-types]]
|
|
=== Configuring available project types
|
|
The available project types mostly define the structure of the generated project and its
|
|
build system. Once a project type is selected, the related action is invoked to generate
|
|
the project.
|
|
|
|
By default, Spring Initializr exposes the following resources (all accessed via HTTP GET):
|
|
|
|
* `/pom.xml` generate a Maven `pom.xml`
|
|
* `/build.gradle` generate a Gradle build
|
|
* `/starter.zip` generate a complete project structure archived in a zip
|
|
* `/starter.tgz` generate a complete project structure archived in a tgz
|
|
|
|
Each type also defines one or more *tags*, that is additional metadata entries to qualify
|
|
the entry. The following standard tags exist:
|
|
|
|
* `build`: the name of the build system to use (e.g. `maven`, `gradle`)
|
|
* `format`: the format of the project (e.g. `project` for a full project, `build` for just
|
|
a build file).
|
|
|
|
By default, the HTML UI filters all the available types to only display the ones that have
|
|
a `format` tag with value `project`.
|
|
|
|
You can of course implement additional endpoints that generate whatever project structure
|
|
you need but, for now, we'll simply configure our instance to generate a Gradle or a Maven
|
|
project:
|
|
|
|
[source,yaml,indent=0]
|
|
----
|
|
initializr:
|
|
types:
|
|
- name: Maven Project
|
|
id: maven-project
|
|
description: Generate a Maven based project archive
|
|
tags:
|
|
build: maven
|
|
format: project
|
|
default: true
|
|
action: /starter.zip
|
|
- name: Gradle Project
|
|
id: gradle-project
|
|
description: Generate a Gradle based project archive
|
|
tags:
|
|
build: gradle
|
|
format: project
|
|
default: false
|
|
action: /starter.zip
|
|
----
|
|
|
|
NOTE: If you intend to build a custom client against your service, you can add as many
|
|
tags as you want, and process them in the client in a way that makes sense for your users.
|
|
|
|
For instance, the spring boot CLI uses them as a shortcut to the full type id. So rather
|
|
than having to create a Gradle project as follows:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring init --type=gradle-project my-project.zip
|
|
----
|
|
|
|
You can simply define a more convenient build parameter:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring init --build=gradle my-project.zip
|
|
----
|
|
|
|
|
|
With that configuration, you should be able to generate your first project,
|
|
congratulations! Let's now add dependencies so that you can start searching for them.
|
|
|
|
|
|
|
|
[[create-instance-dependencies]]
|
|
=== Configuring dependencies
|
|
The most basic `dependency` is composed of:
|
|
|
|
* An `id` used in clients to refer to it
|
|
* The full maven coordinates of the dependency (`groupId` and `artifactId`)
|
|
* A display `name` (used in the UI and the search results)
|
|
* A `description` can (and should) be added to provide more information about the
|
|
dependency
|
|
|
|
Spring Initializr automatically considers that a dependency without maven coordinates
|
|
defines an official Spring Boot starter. In such a case, the `id` is used to infer the
|
|
`artifactId`.
|
|
|
|
For instance, the following configures the `spring-boot-starter-web` Starter:
|
|
|
|
[source,yaml,indent=0]
|
|
----
|
|
initializr:
|
|
dependencies:
|
|
- name: Web
|
|
content:
|
|
- name: Web
|
|
id: web
|
|
description: Full-stack web development with Tomcat and Spring MVC
|
|
----
|
|
|
|
Each dependency is contained in a _group_ that gathers dependencies sharing a common
|
|
surface area or any other form of grouping. In the example above, a `Web` group holds our
|
|
unique dependency. A group can also provide default values for various settings, see the
|
|
<<howto-group-share-settings,dedicated how-to>> for more details.
|
|
|
|
In our `spring-boot-starter-web` example above, the dependency is _managed_ by Spring
|
|
Boot so there is no need to provide a `version` attribute for it. You'll surely need to
|
|
define additional dependencies that are not provided by Spring Boot and we strongly
|
|
recommend you to use a <<create-instance-boms,Bill Of Materials (or BOM)>>.
|
|
|
|
If no BOM is available you can specify a version directly:
|
|
|
|
[source,yaml,indent=0]
|
|
----
|
|
initializr:
|
|
dependencies:
|
|
- name: Tech
|
|
content:
|
|
- name: Acme
|
|
id: acme
|
|
groupId: com.example.acme
|
|
artifactId: acme
|
|
version: 1.2.0.RELEASE
|
|
description: A solid description for this dependency
|
|
----
|
|
|
|
If you add this configuration and search for "acme" (or "solid"), you'll find this extra
|
|
entry; generating a maven project with it should add the following to the pom
|
|
|
|
[source,xml,indent=0,subs="verbatim"]
|
|
----
|
|
<dependency>
|
|
<groupId>com.example.acme</groupId>
|
|
<artifactId>acme</artifactId>
|
|
<version>1.2.0.RELEASE</version>
|
|
</dependency>
|
|
----
|
|
|
|
The rest of this section will detail the other configuration options.
|
|
|
|
|
|
[[dependencies-version-range]]
|
|
==== Availability (version range)
|
|
|
|
A dependency can have a `versionRange`, which is a range of versions of Spring Boot which
|
|
are valid in combination with it. The versions are *not* applied to the dependency itself,
|
|
but rather used to filter out the dependency, or modify it, when different versions of
|
|
Spring Boot are selected for the generated project.
|
|
|
|
A version range has a lower and an upper bound, and if the bound is inclusive it is
|
|
denoted as a square bracket ("[" or "]"), otherwise it is exclusive and denoted by a
|
|
parenthesis ("(" or ")"). Example: "[1.1.6.RELEASE,1.3.0.M1)" means from all versions from
|
|
1.1.6 up to but not including 1.3.0.M1 (no not including any of the 1.3.x line.
|
|
|
|
A version range can be a single value, e.g. "1.2.0.RELEASE", which is short for "this
|
|
version or greater". It is an inclusive lower bound with an implied infinite upper bound.
|
|
|
|
The other shorthand notation that is available is to use "x" for the micro-version label,
|
|
e.g. "1.3.x" means all versions beginning with "1.3". This is mainly used in inclusive
|
|
bounds, like "[1.2.0.RELEASE,1.4.x.RELEASE)" for "all versions in 1.2.x and 1.3.x but not
|
|
1.4.0 or above".
|
|
|
|
Snapshots are naturally ordered higher than released versions, so if you are looking to
|
|
match a dependency to only the latest snapshots of Spring Boot, you could use a version
|
|
range of "1.5.x.BUILD-SNAPSHOT" (assuming 1.5 was the latest).
|
|
|
|
Remember to quote the values of a version range in YAML configuration files (with double
|
|
quotes "").
|
|
|
|
See below in the section on <<howto-link-boot-version,linking versions>> for more examples
|
|
and idioms.
|
|
|
|
[[dependencies-mappings]]
|
|
==== Map coordinates according to the Spring Boot version
|
|
|
|
|
|
[[dependencies-alias]]
|
|
==== Aliases
|
|
|
|
|
|
[[dependencies-repository]]
|
|
==== Repository
|
|
|
|
If the dependency is not available on Maven Central (or whatever default repository that
|
|
is configured on your end), you can also add a <<dependencies-repository,reference to a
|
|
repository>>. A repository is declared at the top level (under `env`) and given an id via
|
|
the key in the configuration. Example
|
|
|
|
[source,yml,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
env:
|
|
repositories:
|
|
my-api-repo-1:
|
|
name: repo1
|
|
url: http://example.com/repo1
|
|
----
|
|
|
|
he repository can then be referred back to in a dependency
|
|
|
|
[source,yml,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
dependencies:
|
|
- name: Other
|
|
content:
|
|
- name: Foo
|
|
groupId: org.acme
|
|
artifactId: foo
|
|
version: 1.3.5
|
|
repository: my-api-repo-1
|
|
----
|
|
|
|
It is usually preferable to have a BOM for every dependency, and attach the repository to
|
|
the BOM instead.
|
|
|
|
[[create-instance-boms]]
|
|
=== Configuring Bill of Materials
|
|
|
|
A Bill of Materials (BOM) is a special `pom.xml`, deployed to a Maven repository, and use
|
|
to control dependency management for a set of related artifacts. In the Spring Boot
|
|
ecosystem we usually use the suffix "-dependencies" on the artifact id of a BOM. In other
|
|
projects we see "-bom". It is recommended that all dependencies are included in a BOM of
|
|
some sort, since they provide nice high level features for users of the dependency. It is
|
|
also important that 2 BOMs used in a project do not contain conflicting versions for the
|
|
same dependency, so the best practice is to look at the existing BOMs in the Initializr
|
|
before you add a new one, and make sure that you aren't adding a conflict. Maven (3.5)
|
|
will report conflicts when it builds a project containing the two BOMs, even if the
|
|
dependency that conflicts is not used.
|
|
|
|
In the Initializr a BOM is declared at the `env` level, and given an id through the
|
|
configuration key. Example:
|
|
|
|
[source,yml,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
env:
|
|
boms:
|
|
my-api-bom:
|
|
groupId: org.acme
|
|
artifactId: my-api-dependencies
|
|
version: 1.0.0.RELEASE
|
|
repositories: my-api-repo-1
|
|
----
|
|
|
|
If a BOM requires a special, non-default repository, then it can be referred to here,
|
|
instead of having to explicitly list the repository again for each dependency. A
|
|
dependency, or a dependency group, can declare that it requires the use of one or more BOMs by referring to the id. Example:
|
|
|
|
[source,yml,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
dependencies:
|
|
- name: Other
|
|
content:
|
|
- name: My API
|
|
id : my-api
|
|
groupId: org.acme
|
|
artifactId: my-api
|
|
bom: my-api-bom
|
|
----
|
|
|
|
[[dependencies-facet]]
|
|
==== Facets
|
|
|
|
A "facet" is a label on a dependency which is used to drive a code modification in the
|
|
generated project. In the standard Initializr generator, there is only one facet that is
|
|
actually used ("web"), but custom installations might choose to use it for their own
|
|
purposes. The "web" facet is used to drive the inclusion of `spring-boot-starter-web` if
|
|
any other dependency with that facet is included. The value of the "facets" property of a
|
|
dependency is a list of strings.
|
|
|
|
[[create-instance-dependencies-link]]
|
|
==== Links
|
|
|
|
Links can be used to provide descriptive and hyperlink data to guide to user on how to
|
|
learn more about a dependency. A dependency has a "links" property which is a list of
|
|
`Link`. Each link has a "rel" label to identify it, an "href" and an optional (but
|
|
recommended) description. In the web UI the links are not currently rendered.
|
|
|
|
[[create-instance-dependencies-search]]
|
|
==== Improve search results
|
|
|
|
Each dependency can have a "weight" (a number >=0) and also "keywords" (list of string)
|
|
that are used to prioritize them in the search feature in the UI. If you type one of the keywords into the "Dependencies" box in the UI, those dependencies will be listed below, in order of decreasing weight, if they have one (unweighted dependencies come last).
|
|
|
|
|
|
[[configuration-howto]]
|
|
== '`How-to`' guides
|
|
|
|
This section provides answers to some common '`how do I do that...`' type of questions
|
|
that often arise when configuring Spring Initializr.
|
|
|
|
[[howto-add-a-new-checkbox]]
|
|
=== Add a new dependency checkbox
|
|
|
|
To add a new checkbox, first identify the Maven co-ordinates of the dependency you want to
|
|
add (`groupId:artifactId:version`) and then check which versions of Spring Boot it works
|
|
with. If there are multiple versions that work with different versions of Spring Boot,
|
|
then that's fine too.
|
|
|
|
* If there is a published BOM that manages the version of you dependency, then add that
|
|
first, in the `env` section (see the <<create-instance-boms>> section above).
|
|
|
|
* Then configure the dependency, fitting it into an existing group if you can, otherwise
|
|
creating a new group.
|
|
|
|
* If there is a BOM then omit the version.
|
|
|
|
* If there is a Spring Boot version range (or min or max) that you need for this
|
|
dependency, add that as a <<howto-link-boot-version,linked version>>.
|
|
|
|
[[howto-override-a-version]]
|
|
=== Override the version of a dependency
|
|
|
|
Sometimes it happens that the BOM that normally manages your dependency version is in
|
|
conflict with the newest version. Or maybe this is the case for only a range of Spring
|
|
Boot versions. Or maybe there just is no BOM, or it's not worth creating one for just one
|
|
dependency. In these cases you can specify the version manually for a dependency either at the top level, or in a <<howto-link-boot-version,version mapping>>. At the top level it looks like this (just a "version" property in a dependency):
|
|
|
|
[source,yml,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
dependencies:
|
|
- name: I/O
|
|
content:
|
|
- name: Activiti
|
|
id: activiti-basic
|
|
description: Activiti BPMN workflow engine
|
|
groupId: org.activiti
|
|
artifactId: activiti-spring-boot-starter-basic
|
|
version: 5.21.0
|
|
----
|
|
|
|
[[howto-link-boot-version]]
|
|
=== Link a Boot version to a version of your dependency
|
|
|
|
If your dependency requires a specific version of Spring Boot, ot different versions of
|
|
Spring Boot require different versions of your dependency there are a couple of mechanisms
|
|
to configure that.
|
|
|
|
The simplest is to put a "versionRange" in the dependency declaration. This is a range of versions of Spring Boot, not or your dependency. For example:
|
|
|
|
[source,yml,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
dependencies:
|
|
- name: Stuff
|
|
content:
|
|
- name: Atomikos (JTA)
|
|
id: jta-atomikos
|
|
description: JTA distributed transactions via Atomikos
|
|
versionRange: 1.2.0.M1
|
|
- name: Stormpath
|
|
id: stormpath
|
|
groupId: com.stormpath.spring
|
|
artifactId: stormpath-default-spring-boot-starter
|
|
versionRange: "[1.5.0.RC1,2.0.0.M1)"
|
|
bom: stormpath-bom
|
|
----
|
|
|
|
In this example Atomikos is available for Spring Boot 1.2.0 (or any milestone of 1.2.0) or
|
|
greater, and Stormpath is available for Spring Boot 1.5.0 up to, but not including 2.0.0.
|
|
|
|
If different versions of your dependency work with different versions of Spring Boot,
|
|
that's when you need the "mappings" property. A mapping is a combination of a `versionRange`
|
|
(for Spring Boot) and some or all of the other properties of the dependency, overriding
|
|
the values defined at the top level. For example:
|
|
|
|
[source,yml,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
dependencies:
|
|
- name: Stuff
|
|
content:
|
|
- name: Cloud Task
|
|
id: cloud-task
|
|
groupId: org.springframework.cloud
|
|
artifactId: spring-cloud-starter-task
|
|
versionRange: 1.3.0.RELEASE
|
|
bom: cloud-task-bom
|
|
mappings:
|
|
- versionRange: "[1.3.0.RELEASE,1.3.x.RELEASE]"
|
|
artifactId: spring-cloud-task-starter
|
|
- versionRange: "1.4.0.RELEASE"
|
|
----
|
|
|
|
This dependency is available only for Spring Boot 1.3.0 and above, but up to 1.4.0
|
|
(i.e. for 1.3.x only) its `artifactId` was actually different.
|
|
|
|
A mapping can also be applied to a BOM declaration. For example:
|
|
|
|
[source,yml,subs="verbatim,attributes"]
|
|
----
|
|
initializr:
|
|
env:
|
|
boms:
|
|
my-api-bom:
|
|
groupId: org.acme
|
|
artifactId: my-api-bom
|
|
additionalBoms: ['my-api-dependencies-bom']
|
|
mappings:
|
|
- versionRange: "[1.0.0.RELEASE,1.1.6.RELEASE)"
|
|
version: 1.0.0.RELEASE
|
|
repositories: my-api-repo-1
|
|
- versionRange: "1.2.1.RELEASE"
|
|
version: 2.0.0.RELEASE
|
|
repositories: my-api-repo-2
|
|
----
|
|
|
|
In this example Spring Boot versions up to 1.1.6 select version 1.0.0 of the BOM, and set
|
|
a different repository. Spring Boot versions 1.2.1 and above select 2.0.0 of the BOM and
|
|
yet another repository.
|
|
|
|
[[howto-add-snapshot-repository]]
|
|
=== Configure a snapshot repository
|
|
|
|
[[howto-dependency-starter-flag]]
|
|
=== Make sure a regular dependency brings the base starter
|
|
|
|
[[howto-group-share-settings]]
|
|
=== Share common dependency settings in a group
|
|
|
|
|
|
[[create-instance-advanced-config]]
|
|
== Advanced configuration
|
|
|
|
|
|
|
|
[[create-instance-advanced-config-caching]]
|
|
=== Caching configuration
|
|
If you use the service, you'll notice that the logs have lots of entries with the message
|
|
`Fetching boot metadata from https://spring.io/project_metadata/spring-boot`. To avoid
|
|
checking for the latest Spring Boot versions too often, you should enable caching on your
|
|
service. Spring Initializr has some auto-configuration to apply the proper caches if you
|
|
are willing to use a JCache (JSR-107) implementation.
|
|
|
|
Add the `javax.cache:cache-api` and your favorite JCache implementation and simply enable
|
|
caching by adding `@EnableCaching` to your `@SpringBootApplication`. For instance, you
|
|
could use `ehcache` by adding the following:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
<dependency>
|
|
<groupId>javax.cache</groupId>
|
|
<artifactId>cache-api</artifactId>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>org.ehcache</groupId>
|
|
<artifactId>ehcache</artifactId>
|
|
</dependency>
|
|
----
|
|
|
|
Or if you are using Gradle:
|
|
|
|
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
compile("javax.cache:cache-api")
|
|
compile("org.ehcache:ehcache")
|
|
----
|
|
|
|
You'll notice that the log entry is much more rare. If you do not want to use JSR-107, you
|
|
should configure the cache yourselves. Here are the caches used by the application (each
|
|
one will require some configuration to get it working):
|
|
|
|
.Cache configuration
|
|
|===
|
|
| cache name | Description
|
|
|
|
|`initializr`
|
|
|Cache the full metadata of the service. When the metadata expires, it is fully resolved
|
|
again (including a check on spring.io for the latest Spring Boot versions). Adapt the
|
|
expiration settings accordingly.
|
|
|
|
|`project-resources`
|
|
|Cache resources that are used to generate projects.
|
|
|
|
|`dependency-metadata`
|
|
|Cache dependency-specific metadata.
|
|
|===
|