<commit_before>= Spring Cloud Config
:github: https://github.com/spring-cloud/spring-cloud-config
:githubmaster: {github}/tree/master
:docslink: {githubmaster}/docs/src/main/asciidoc
:toc:
:nofooter:
:special-string: _

*{spring-cloud-version}*

include::intro.adoc[]

== Quick Start

include::quickstart.adoc[]

== Spring Cloud Config Server

Spring Cloud Config Server provides an HTTP resource-based API for external configuration (name-value pairs or equivalent YAML content).
The server is embeddable in a Spring Boot application, by using the `@EnableConfigServer` annotation.
Consequently, the following application is a config server:

.ConfigServer.java
[source,java]
----
@SpringBootApplication
@EnableConfigServer
public class ConfigServer {
  public static void main(String[] args) {
    SpringApplication.run(ConfigServer.class, args);
  }
}
----

Like all Spring Boot applications, it runs on port 8080 by default, but you can switch it to the more conventional port 8888 in various ways.
The easiest, which also sets a default configuration repository, is by launching it with `spring.config.name=configserver` (there is a `configserver.yml` in the Config Server jar).
Another is to use your own `application.properties`, as shown in the following example:

.application.properties
[source,properties]
----
server.port: 8888
spring.cloud.config.server.git.uri: file://${user.home}/config-repo
----

where `${user.home}/config-repo` is a git repository containing YAML and properties files.

NOTE: On Windows, you need an extra "/" in the file URL if it is absolute with a drive prefix (for example,`file:///${user.home}/config-repo`).

[TIP]
====
The following listing shows a recipe for creating the git repository in the preceding example:

----
$ cd $HOME
$ mkdir config-repo
$ cd config-repo
$ git init .
$ echo info.foo: bar > application.properties
$ git add -A .
$ git commit -m "Add application.properties"
----
====

WARNING: Using the local filesystem for your git repository is intended for testing only.
You should use a server to host your configuration repositories in production.

WARNING: The initial clone of your configuration repository can be quick and efficient if you keep only text files in it.
If you store binary files, especially large ones, you may experience delays on the first request for configuration or encounter out of memory errors in the server.

=== Environment Repository

Where should you store the configuration data for the Config Server?
The strategy that governs this behaviour is the `EnvironmentRepository`, serving `Environment` objects.
This `Environment` is a shallow copy of the domain from the Spring `Environment` (including `propertySources` as the main feature).
The `Environment` resources are parametrized by three variables:


* `{application}`, which maps to `spring.application.name` on the client side.
* `{profile}`, which maps to `spring.profiles.active` on the client (comma-separated list).
* `{label}`, which is a server side feature labelling a "versioned" set of config files.

Repository implementations generally behave like a Spring Boot application, loading configuration files from a `spring.config.name` equal to the `{application}` parameter, and `spring.profiles.active` equal to the `{profiles}` parameter.
Precedence rules for profiles are also the same as in a regular Spring Boot application: Active profiles take precedence over defaults, and, if there are multiple profiles, the last one wins (similar to adding entries to a `Map`).

The following sample client application has this bootstrap configuration:

[source,yaml]
----
spring:
  application:
    name: foo
  profiles:
    active: dev,mysql
----

(As usual with a Spring Boot application, these properties could also be set by environment variables or command line arguments).

If the repository is file-based, the server creates an
`Environment` from `application.yml` (shared between all clients) and
`foo.yml` (with `foo.yml` taking precedence).
If the YAML files have documents inside them that point to Spring profiles, those are applied with higher precedence (in order of the profiles listed).
If there are profile-specific YAML (or properties) files, these are also applied with higher precedence than the defaults.
Higher precedence translates to a `PropertySource` listed earlier in the `Environment`.
(These same rules apply in a standalone Spring Boot application.)

You can set spring.cloud.config.server.accept-empty to false so that Server would return a HTTP 404 status, if the application is not found.By default, this flag is set to true.

==== Git Backend

The default implementation of `EnvironmentRepository` uses a Git backend, which is very convenient for managing upgrades and physical environments and for auditing changes.
To change the location of the repository, you can set the `spring.cloud.config.server.git.uri` configuration property in the Config Server (for example in `application.yml`).
If you set it with a `file:` prefix, it should work from a local repository so that you can get started quickly and easily without a server. However, in that case, the server operates directly on the local repository without cloning it (it does not matter if it is not bare because the Config Server never makes changes to the "remote" repository).
To scale the Config Server up and make it highly available, you need to have all instances of the server pointing to the same repository, so only a shared file system would work.
Even in that case, it is better to use the `ssh:` protocol for a shared filesystem repository, so that the server can clone it and use a local working copy as a cache.

This repository implementation maps the `{label}` parameter of the HTTP resource to a git label (commit id, branch name, or tag).
If the git branch or tag name contains a slash (`/`), then the label in the HTTP URL should instead be specified with the special string `({special-string})` (to avoid ambiguity with other URL paths).
For example, if the label is `foo/bar`, replacing the slash would result in the following label: `foo({special-string})bar`.
The inclusion of the special string `({special-string})` can also be applied to the `{application}` parameter.
If you use a command-line client such as curl, be careful with the brackets in the URL -- you should escape them from the shell with single quotes ('').

===== Skipping SSL Certificate Validation

The configuration server's validation of the Git server's SSL certificate can be disabled by setting the `git.skipSslValidation` property to `true` (default is `false`).

[source,yaml]
----
spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          skipSslValidation: true
----

===== Setting HTTP Connection Timeout

You can configure the time, in seconds, that the configuration server will wait to acquire an HTTP connection. Use the `git.timeout` property.

[source,yaml]
----
spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          timeout: 4
----

===== Placeholders in Git URI

Spring Cloud Config Server supports a git repository URL with placeholders for the `{application}` and `{profile}` (and `{label}` if you need it, but remember that the label is applied as a git label anyway).
So you can support a "`one repository per application`" policy by using a structure similar to the following:

[source,yaml]
----
spring:<commit_msg>docs(-): git.timeout default is 5 (#2079)<commit_after>= Spring Cloud Config
:github: https://github.com/spring-cloud/spring-cloud-config
:githubmaster: {github}/tree/master
:docslink: {githubmaster}/docs/src/main/asciidoc
:toc:
:nofooter:
:special-string: _

*{spring-cloud-version}*

include::intro.adoc[]

== Quick Start

include::quickstart.adoc[]

== Spring Cloud Config Server

Spring Cloud Config Server provides an HTTP resource-based API for external configuration (name-value pairs or equivalent YAML content).
The server is embeddable in a Spring Boot application, by using the `@EnableConfigServer` annotation.
Consequently, the following application is a config server:

.ConfigServer.java
[source,java]
----
@SpringBootApplication
@EnableConfigServer
public class ConfigServer {
  public static void main(String[] args) {
    SpringApplication.run(ConfigServer.class, args);
  }
}
----

Like all Spring Boot applications, it runs on port 8080 by default, but you can switch it to the more conventional port 8888 in various ways.
The easiest, which also sets a default configuration repository, is by launching it with `spring.config.name=configserver` (there is a `configserver.yml` in the Config Server jar).
Another is to use your own `application.properties`, as shown in the following example:

.application.properties
[source,properties]
----
server.port: 8888
spring.cloud.config.server.git.uri: file://${user.home}/config-repo
----

where `${user.home}/config-repo` is a git repository containing YAML and properties files.

NOTE: On Windows, you need an extra "/" in the file URL if it is absolute with a drive prefix (for example,`file:///${user.home}/config-repo`).

[TIP]
====
The following listing shows a recipe for creating the git repository in the preceding example:

----
$ cd $HOME
$ mkdir config-repo
$ cd config-repo
$ git init .
$ echo info.foo: bar > application.properties
$ git add -A .
$ git commit -m "Add application.properties"
----
====

WARNING: Using the local filesystem for your git repository is intended for testing only.
You should use a server to host your configuration repositories in production.

WARNING: The initial clone of your configuration repository can be quick and efficient if you keep only text files in it.
If you store binary files, especially large ones, you may experience delays on the first request for configuration or encounter out of memory errors in the server.

=== Environment Repository

Where should you store the configuration data for the Config Server?
The strategy that governs this behaviour is the `EnvironmentRepository`, serving `Environment` objects.
This `Environment` is a shallow copy of the domain from the Spring `Environment` (including `propertySources` as the main feature).
The `Environment` resources are parametrized by three variables:


* `{application}`, which maps to `spring.application.name` on the client side.
* `{profile}`, which maps to `spring.profiles.active` on the client (comma-separated list).
* `{label}`, which is a server side feature labelling a "versioned" set of config files.

Repository implementations generally behave like a Spring Boot application, loading configuration files from a `spring.config.name` equal to the `{application}` parameter, and `spring.profiles.active` equal to the `{profiles}` parameter.
Precedence rules for profiles are also the same as in a regular Spring Boot application: Active profiles take precedence over defaults, and, if there are multiple profiles, the last one wins (similar to adding entries to a `Map`).

The following sample client application has this bootstrap configuration:

[source,yaml]
----
spring:
  application:
    name: foo
  profiles:
    active: dev,mysql
----

(As usual with a Spring Boot application, these properties could also be set by environment variables or command line arguments).

If the repository is file-based, the server creates an
`Environment` from `application.yml` (shared between all clients) and
`foo.yml` (with `foo.yml` taking precedence).
If the YAML files have documents inside them that point to Spring profiles, those are applied with higher precedence (in order of the profiles listed).
If there are profile-specific YAML (or properties) files, these are also applied with higher precedence than the defaults.
Higher precedence translates to a `PropertySource` listed earlier in the `Environment`.
(These same rules apply in a standalone Spring Boot application.)

You can set spring.cloud.config.server.accept-empty to false so that Server would return a HTTP 404 status, if the application is not found.By default, this flag is set to true.

==== Git Backend

The default implementation of `EnvironmentRepository` uses a Git backend, which is very convenient for managing upgrades and physical environments and for auditing changes.
To change the location of the repository, you can set the `spring.cloud.config.server.git.uri` configuration property in the Config Server (for example in `application.yml`).
If you set it with a `file:` prefix, it should work from a local repository so that you can get started quickly and easily without a server. However, in that case, the server operates directly on the local repository without cloning it (it does not matter if it is not bare because the Config Server never makes changes to the "remote" repository).
To scale the Config Server up and make it highly available, you need to have all instances of the server pointing to the same repository, so only a shared file system would work.
Even in that case, it is better to use the `ssh:` protocol for a shared filesystem repository, so that the server can clone it and use a local working copy as a cache.

This repository implementation maps the `{label}` parameter of the HTTP resource to a git label (commit id, branch name, or tag).
If the git branch or tag name contains a slash (`/`), then the label in the HTTP URL should instead be specified with the special string `({special-string})` (to avoid ambiguity with other URL paths).
For example, if the label is `foo/bar`, replacing the slash would result in the following label: `foo({special-string})bar`.
The inclusion of the special string `({special-string})` can also be applied to the `{application}` parameter.
If you use a command-line client such as curl, be careful with the brackets in the URL -- you should escape them from the shell with single quotes ('').

===== Skipping SSL Certificate Validation

The configuration server's validation of the Git server's SSL certificate can be disabled by setting the `git.skipSslValidation` property to `true` (default is `false`).

[source,yaml]
----
spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          skipSslValidation: true
----

===== Setting HTTP Connection Timeout

You can configure the time, in seconds, that the configuration server will wait to acquire an HTTP connection. Use the `git.timeout` property (default is `5`).

[source,yaml]
----
spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          timeout: 4
----

===== Placeholders in Git URI

Spring Cloud Config Server supports a git repository URL with placeholders for the `{application}` and `{profile}` (and `{label}` if you need it, but remember that the label is applied as a git label anyway).
So you can support a "`one repository per application`" policy by using a structure similar to the following:

[source,yaml]
----
spring:
{'fraction_non_alphanumeric': 0.07939785519216679, 'fraction_numerical': 0.0025311396789449146, 'mean_word_length': 4.398777418194894, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6194353', 'n_tokens_mistral': 3771, 'n_tokens_neox': 3651, 'n_words': 2021}