[[configuration-format]]
# Configuration Format
This section describes the configuration structure that is used by the initializr.
The metadata provided through configuration are driving the options exposed by a
particular instance and <<metadata-format.adoc#metadata-format,the project metadata
format>>.

TIP: A good way to get started with the configuration is to look at the
{sc-initializr-service}/resources/application.yml[configuration of the production
instance] and check the end-result on https://start.spring.io

The configuration is split in several sections:

* An `env` section used to provide various global settings.
* A `dependencies` section lists the available dependencies. This is the most
important section of the service as it defines the "libraries" that the user can
choose.
* The `groupId`, `artifactId`, `version`, `name`, `description` and `packageName`
provide default values for these project settings.
* The `types`, `packagings`, `javaVersions`, `languages` and `bootVersions` provide
the list of available option for each setting and which one is the default.



## Env section
TIP: Check {sc-initializr-generator}/metadata/InitializrConfiguration.java#L142[the code]
for a full list of the available configuration options.

The `env` element defines environment option that the service uses:

* `artifactRepository`: the URL of the (maven) repository that should be used to
download the Spring Boot CLI distribution bundle. This is only used by the `/spring`
endpoint at the moment.
* `springBootMetadataUrl` the URL of the resource that provides the list of available
Spring Boot versions..
* `forceSsl`: a boolean flag that determines if we should use `https` even when
browsing a resource via `http`. This is _enabled_ by default.
* `fallbackApplicationName`: the name of the _default_ application. Application names
are generated based on the project's name. However, some user input may result in an
invalid identifier for a Java class name for instance.
* `invalidApplicationNames`: a fixed list of invalid application names. If a project
generation uses one of these names, the fallback is used instead.
* `invalidPackageNames`: a fixed list of invalid package names. If a project
generation uses one of these names, the default is used instead.
* `googleAnalyticsTrackingCode`: the Google Analytics code to use. If this is set,
Google analytics is automatically enabled.
* `kotlin`: kotlin-specific settings. For now, only the kotlin version to use can be
configured.
* `maven`: maven-specified settings. A custom maven parent POM can be defined and
whether or not the `spring-boot-dependencies` BOM should be automatically added to
the project.

If some of your dependencies require a custom Bill of Materials (BOM) and/or a custom
repository, you can add them here and use the id as a reference. For instance, let's
say that you want to integrate with library `foo` and it requires a `foo-bom` and a
`foo-repo`. You can configure things as follows:

```yml
initializr:
  env:
    boms:
      foo-bom:
        groupId: com.example
        artifactId: foo-bom
        version: 1.2.3
    repositories:
      foo-repo:
        name: foo-release-repo
        url: https://repo.example.com/foo
        snapshotsEnabled: false
```

You can then use the `foo-bom` and `foo-repo` in a "dependency" or "dependency group"
section.

NOTE: The `spring-milestones` and `spring-snapshots` repositories are available by
default. Please note that these are just references and won't impact the project
unless you choose a dependency that explicitly refer to a bom and/or repo by id.
Check the example below for more details.

## Dependencies section

The `dependencies` section allows you define a list of groups, each group having one
more `dependency`. A group gather dependencies that share a common characteristics
(i.e. all web-related dependencies for instance).

A `dependency` has the following basic characteristics:

* A mandatory identifier. If no further information is provided, a Spring Boot starer
with that id is assumed.
* A `name` and `description` used in the generated meta-data and the web ui.
* A `groupId` and `artifactId` to define the coordinates of the dependency.
* A `version` if Spring Boot does not already provide a dependency management for
that dependency.
* A `scope` (can be `compile`, `runtime`, `provided` or `test`).
* The reference to a `bom` or a `repository` that must be added to the project once
that dependency is added.
* A `versionRange` used to determine the Spring Boot versions that are compatible
with the dependency.
* Links to resources such as a guide or a reference doc section.

TIP: Check {sc-initializr-generator}/metadata/Dependency.java[the code] for a full
list of the available configuration options.

Here is the most basic dependency entry you could have

```yml
initializr:
  dependencies:
    - name: Core
      content:
        - id: security
          name: Security
          description: Secure your application via spring-security
```

TIP: The `security` dependency is held within a group called "Core".

This adds an option name `Security` with a tooltip showing the description above. If
a project is generated with that dependency, the
`org.springframework.boot:spring-boot-starter-security` dependency will be added to
the project.

Let's now add a custom dependency that is not managed by Spring Boot and that only
work from Spring Boot `1.2.0.RELEASE` and onwards but should not be used in the 1.3
lines and further for some reason.

```yml
initializr:
  dependencies:
    - name: Core
      content:
        - id: my-lib-id
          name: My lib
          description: Secure your application via spring-security
          groupId: com.example.foo
          artifactId: foo-core
          bom: foo-bom
          repository: foo-repo
          versionRange: "[1.2.0.RELEASE,1.3.0.M1)"
```

If one selects this entry, the `com.example.foo:foo-core}` dependency will be added
and the Bill of Materials and repository for `foo` will be added automatically to
the project as well (see the "Env section" above for a reference to those
identifiers). Because the bom provides a dependency management for `foo-core` there
is no need to hard code the version in the configuration.

The `versionRange` syntax follows some simple rules: a square bracket "[" or "]"
denotes an inclusive end of the range and a round bracket "(" or ")" denotes an
exclusive end of the range. A range can also be unbounded by defining a a single
version. In the example above, the dependency will be available as from
`1.2.0.RELEASE` up to, not included, `1.3.0.M1` (which is the first milestone of the
1.3 line).

### Dependency group

A dependency group gather a set of dependencies as well as some common settings:
`bom`, `repository` and `versionRange`. If one of them is set, it is applied for all
dependencies within that group. It is still possible to override a particular value
at the dependency level.

## Other sections

The other section defines the default and the list of available options in the web
UI. This also drives how the meta-data for your instance are generated and tooling
support is meant to react to that.

For instance, if you want your groupId to default to `org.acme` and the
`javaVersions` to only be `1.7` and `1.8` you would write the following config:

```yml
initializr:
  groupId:
    value: org.acme
  javaVersions:
    - id: 1.8
      default: true
    - id: 1.7
      default: false
```
