From 669dfb0e12da73a3e89a72582606e0faa1310685 Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Fri, 26 Sep 2014 11:06:43 +0100 Subject: [PATCH] Start on docs in asciidoctor --- .gitignore | 1 + Guardfile | 11 ++++++ README.adoc | 26 +++++++++++++ src/main/adoc/intro.adoc | 16 ++++++++ README.md => src/main/adoc/quickstart.adoc | 45 ++++++++-------------- src/main/adoc/spring-cloud-config.adoc | 7 ++++ 6 files changed, 76 insertions(+), 30 deletions(-) create mode 100644 Guardfile create mode 100644 README.adoc create mode 100644 src/main/adoc/intro.adoc rename README.md => src/main/adoc/quickstart.adoc (78%) create mode 100644 src/main/adoc/spring-cloud-config.adoc diff --git a/.gitignore b/.gitignore index 0e4720a3..69acfd0b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ /application.yml /application.properties +asciidoctor.css *~ .#* *# diff --git a/Guardfile b/Guardfile new file mode 100644 index 00000000..286d79c1 --- /dev/null +++ b/Guardfile @@ -0,0 +1,11 @@ +require 'asciidoctor' +require 'erb' + +options = {:to_dir => 'target/docs', :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) + } +end diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..ca8b2a1e --- /dev/null +++ b/README.adoc @@ -0,0 +1,26 @@ += Spring Cloud Config + +include::./src/main/adoc/intro.adoc[] + +== 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) + +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 + +include::./src/main/adoc/quickstart.adoc[] diff --git a/src/main/adoc/intro.adoc b/src/main/adoc/intro.adoc new file mode 100644 index 00000000..f04ccd41 --- /dev/null +++ b/src/main/adoc/intro.adoc @@ -0,0 +1,16 @@ +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. diff --git a/README.md b/src/main/adoc/quickstart.adoc similarity index 78% rename from README.md rename to src/main/adoc/quickstart.adoc index 3e83d65e..48dd25a5 100644 --- a/README.md +++ b/src/main/adoc/quickstart.adoc @@ -1,36 +1,21 @@ -Spring Platform 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. 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 uses git so it easily supports -labelled versions of configuration environments. - -## 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 @@ -38,9 +23,9 @@ 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 @@ -48,7 +33,7 @@ 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 +=== 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 @@ -59,14 +44,14 @@ 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":[], @@ -75,16 +60,16 @@ $ curl localhost:8080/env "systemProperties":{...}, ... } -``` +---- (a property source called "configService:/" contains the property "foo" with value "bar" and is highest priority). -## Sample Application +=== Sample Application There is a sample application -[here](https://github.com/spring-cloud/spring-cloud-config-sample). It +https://github.com/spring-cloud/spring-cloud-config-sample[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 @@ -104,7 +89,7 @@ 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 @@ -113,6 +98,6 @@ $ curl localhost:8080/refresh ["foo"] $ curl localhost:8080/env/foo baz -``` +---- The refresh endpoint reports that the "foo" property changed. diff --git a/src/main/adoc/spring-cloud-config.adoc b/src/main/adoc/spring-cloud-config.adoc new file mode 100644 index 00000000..04b2e5d4 --- /dev/null +++ b/src/main/adoc/spring-cloud-config.adoc @@ -0,0 +1,7 @@ += Spring Cloud Config + +include::intro.adoc[] + +== Quick Start + +include::quickstart.adoc[]