diff --git a/Guardfile b/Guardfile index 286d79c1..f42889b4 100644 --- a/Guardfile +++ b/Guardfile @@ -1,11 +1,11 @@ require 'asciidoctor' require 'erb' -options = {:to_dir => 'target/docs', :mkdirs => true, :safe => :unsafe, :attributes => 'linkcss'} +options = {:mkdirs => true, :safe => :unsafe, :attributes => 'linkcss'} guard 'shell' do watch(/^[A-Za-z].*\.adoc$/) {|m| - Asciidoctor.render_file('README.adoc', options) - Asciidoctor.render_file('src/main/adoc/spring-cloud-config.adoc', options) + Asciidoctor.render_file('src/main/adoc/README.adoc', options.merge(:to_dir => '.')) + Asciidoctor.render_file('src/main/adoc/spring-cloud-config.adoc', options.merge(:to_dir => 'target/docs')) } end diff --git a/README.html b/README.html new file mode 100644 index 00000000..fd82b1cf --- /dev/null +++ b/README.html @@ -0,0 +1,233 @@ + + + + + + + +Spring Cloud Config + + + + + +
+
+
+
+

Spring Cloud Config provides server and client-side support for +externalized configuration in a distributed system. With the Config +Server you have a central place to manage external properties for +applications across all environments. The concepts on both client and +server map identically to the Spring Environment and +PropertySource abstractions, so they fit very well with Spring +applications, but can be used with any application running in any +language. As an application moves through the deployment pipeline from +dev to test and into production you can manage the configuration +between those environments and be certain that applications have +everything they need to run when they migrate. The default +implementation of the server storage backend uses git so it easily +supports labelled versions of configuration environments, as well as +being accessible to a wide range of tooling for managing the content. +It is easy to add alternative implementations and plug them in with +Spring configuration.

+
+
+
+
+

Features

+
+
+

Spring Cloud Config Server features:

+
+
+
    +
  • +

    HTTP, resource-based API for external configuration (name-value pairs, or equivalent YAML content)

    +
    • +
  • +

    Encrypt and decrypt property values (symmetric or asymmetric)

    +
    • +
  • +

    Embeddable easily in a Spring Boot application using @EnableConfigServer

    +
    • +
+
+
+

Config Client features (for Spring applications):

+
+
+
    +
  • +

    Bind to Config Server and initialize Spring Environment with remote property sources

    +
    • +
  • +

    Encrypt and decrypt property values (symmetric or asymmetric)

    +
    • +
  • +

    @RefreshScope for Spring @Beans that want to be re-initialized when configuration changes

    +
    • +
  • +

    Management endpoints:

    +
    +
      +
    • +

      /env/ for updating Environment and rebinding @ConfigurationProperties

      +
      • +
    • +

      /refresh for refreshing the @RefreshScope beans

      +
      • +
    • +

      /restart for restarting the Spring context (disabled by default)

      +
      • +
    • +

      /pause and /resume for calling the Lifecycle methods (stop() and start() on the ApplicationContext)

      +
      • +
    +
    +
    • +
  • +

    Bootstrap appplication context: a parent context for the main application that can be trained to do anything (by default it binds to the Config Server, and decrypts property values)

    +
    • +
+
+
+
+
+

Quick Start

+
+
+

Start the server:

+
+
+
+
$ cd spring-cloud-config-server
+$ mvn spring-boot:run
+
+
+
+

The server is a Spring Boot application so you can build the jar file +and run that (java -jar …​) or pull it down from a Maven +repository. Then try it out as a client:

+
+
+
+
$ curl localhost:8888/foo/development
+{"name":"development","label":"master","propertySources":[
+  {"name":"https://github.com/scratches/config-repo/foo-development.properties","source":{"bar":"spam"}},
+  {"name":"https://github.com/scratches/config-repo/foo.properties","source":{"foo":"bar"}}
+]}
+
+
+
+

The default strategy for locating property sources is to clone a git +repository (at "spring.platform.config.server.uri") and use it to +initialize a mini SpringApplication. The mini-application’s +Environment is used to enumerate property sources and publish them +via a JSON endpoint. The service has resources in the form:

+
+
+
+
/{application}/{profile}[/{label}]
+
+
+
+

where the "application" is injected as the "spring.config.name" in the +SpringApplication (i.e. what is normally "application" in a regular +Spring Boot app), "profile" is an active profile (or comma-separated +list of properties), and "label" is an optional git label (defaults to +"master").

+
+
+

Client Side Usage

+
+

To use these features in an application, just build it as a Spring +Boot application that depends on spring-cloud-config-client +(e.g. see the test cases for the config-client, or the sample app). +When it runs it will pick up the external configuration from the +default local config server on port 8888 if it is running. To modify +the startup behaviour you can change the location of the config server +using bootstrap.properties (like application.properties but for +the bootstrap phase of an application context), e.g.

+
+
+
+
spring.platform.config.uri: http://myconfigserver.com
+
+
+
+

The bootstrap properties will show up in the /env endpoint as a +high-priority property source, e.g.

+
+
+
+
$ curl localhost:8080/env
+{
+  "profiles":[],
+  "configService:https://github.com/scratches/config-repo/bar.properties":{"foo":"bar"},
+  "servletContextInitParams":{},
+  "systemProperties":{...},
+  ...
+}
+
+
+
+

(a property source called "configService:<URL of remote +repository>/<file name>" contains the property "foo" with value +"bar" and is highest priority).

+
+
+
+

Sample Application

+
+

There is a sample application +here. It +is a Spring Boot application so you can run it using the usual +mechanisms (for instance "mvn spring-boot:run"). When it runs it will +look for the config server on "http://localhost:8888" by default, so +you could run the server as well to see it all working together.

+
+
+

The sample has a test case where the config server is also started in +the same JVM (with a different port), and the test asserts that an +environment property from the git configuration repo is present. To +change the location of the config server just set +"spring.platform.config.uri" in "bootstrap.yml" (or via System +properties etc.).

+
+
+

The test case has a main() method that runs the server in the same +way (watch the logs for its port), so you can run the whole system in +one process and play with it (e.g. right click on the main in your IDE +and run it). The main() method uses target/config for the working +directory of the git repository, so you can make local changes there +and see them reflected in the running app.

+
+
+
+
$ curl localhost:8080/env/foo
+bar
+$ vi target/config/bar.properties
+.. change value of "foo", optionally commit
+$ curl localhost:8080/refresh
+["foo"]
+$ curl localhost:8080/env/foo
+baz
+
+
+
+

The refresh endpoint reports that the "foo" property changed.

+
+
+
+
+
+ + + \ No newline at end of file diff --git a/README.adoc b/src/main/adoc/README.adoc similarity index 89% rename from README.adoc rename to src/main/adoc/README.adoc index ca8b2a1e..280e6fc4 100644 --- a/README.adoc +++ b/src/main/adoc/README.adoc @@ -1,6 +1,6 @@ = Spring Cloud Config -include::./src/main/adoc/intro.adoc[] +include::intro.adoc[] == Features @@ -8,6 +8,7 @@ Spring Cloud Config Server features: * HTTP, resource-based API for external configuration (name-value pairs, or equivalent YAML content) * Encrypt and decrypt property values (symmetric or asymmetric) +* Embeddable easily in a Spring Boot application using `@EnableConfigServer` Config Client features (for Spring applications): @@ -23,4 +24,4 @@ Config Client features (for Spring applications): == Quick Start -include::./src/main/adoc/quickstart.adoc[] +include::quickstart.adoc[]