diff --git a/README.adoc b/README.adoc
index 23c73f27..cbd2b4ef 100644
--- a/README.adoc
+++ b/README.adoc
@@ -17,6 +17,233 @@ Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Brea
(Hystrix) are provided by integration with Spring Cloud Netflix.
+== Quick Start
+
+This quick start walks through using Spring Cloud Consul for Service Discovery and Distributed Configuration.
+
+First, run Consul Agent on your machine, then you can access it and use as Service Registry and Configuration source with Spring Cloud Consul.
+
+=== Discovery Client Usage
+
+To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-consul-core`.
+The most convenient way to add the dependency is with a Spring Boot starter `org.springframework.cloud:spring-cloud-starter-consul-discovery`.
+We recommend using dependency management and `spring-boot-starter-parent`.
+The following example shows a typical Maven configuration:
+
+[source,xml,indent=0]
+.pom.xml
+----
+
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ {spring-boot-version}
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-starter-consul-discovery
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-dependencies
+ ${spring-cloud.version}
+ pom
+ import
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
+----
+
+The example below shows a typical Gradle setup:
+
+[source,groovy,indent=0]
+.build.gradle
+----
+plugins {
+ id 'org.springframework.boot' version ${spring-boot-version}
+ id 'io.spring.dependency-management' version ${spring-dependency-management-version}
+ id 'java'
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation 'org.springframework.cloud:spring-cloud-starter-consul-discovery'
+ testImplementation 'org.springframework.boot:spring-boot-starter-test'
+}
+dependencyManagement {
+ imports {
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
+ }
+}
+----
+
+Now you can create a standard Spring Boot application, such as the following HTTP server:
+
+----
+@SpringBootApplication
+@RestController
+public class Application {
+
+ @GetMapping("/")
+ public String home() {
+ return "Hello World!";
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(Application.class, args);
+ }
+
+}
+----
+
+When this HTTP server runs, it connects to Consul Agent running at the default local 8500 port.
+To modify the startup behavior, you can change the location of Consul Agent by using `application.properties` as shown in the following example:
+
+----
+spring:
+ cloud:
+ consul:
+ host: localhost
+ port: 8500
+----
+
+You can now use `DiscoveryClient`, `@LoadBalanced RestTemplate` or `@LoadBalanced WebClient.Builder` to retrieve services and instances data from Consul, as shown in the following example:
+
+[source,java,indent=0]
+----
+@Autowired
+private DiscoveryClient discoveryClient;
+
+public String serviceUrl() {
+ List list = discoveryClient.getInstances("STORES");
+ if (list != null && list.size() > 0 ) {
+ return list.get(0).getUri().toString();
+ }
+ return null;
+}
+----
+
+=== Distributed Configuration Usage
+
+To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-consul-core` and `spring-cloud-consul-config`.
+The most convenient way to add the dependency is with a Spring Boot starter `org.springframework.cloud:spring-cloud-starter-consul-config`.
+We recommend using dependency management and `spring-boot-starter-parent`.
+The following example shows a typical Maven configuration:
+
+[source,xml,indent=0]
+.pom.xml
+----
+
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ {spring-boot-version}
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-starter-consul-config
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-dependencies
+ ${spring-cloud.version}
+ pom
+ import
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
+----
+
+The example below shows a typical Gradle setup:
+
+[source,groovy,indent=0]
+.build.gradle
+----
+plugins {
+ id 'org.springframework.boot' version ${spring-boot-version}
+ id 'io.spring.dependency-management' version ${spring-dependency-management-version}
+ id 'java'
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation 'org.springframework.cloud:spring-cloud-starter-consul-config'
+ testImplementation 'org.springframework.boot:spring-boot-starter-test'
+}
+dependencyManagement {
+ imports {
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
+ }
+}
+----
+
+Now you can create a standard Spring Boot application, such as the following HTTP server:
+
+----
+@SpringBootApplication
+@RestController
+public class Application {
+
+ @GetMapping("/")
+ public String home() {
+ return "Hello World!";
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(Application.class, args);
+ }
+
+}
+----
+
+The application will retrieve configuration data from Consul.
+
== Consul overview
Features of Consul
diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc
index f0d0c4a2..28efbc4a 100644
--- a/docs/src/main/asciidoc/README.adoc
+++ b/docs/src/main/asciidoc/README.adoc
@@ -3,6 +3,10 @@ image::https://codecov.io/gh/spring-cloud/spring-cloud-consul/branch/master/grap
include::intro.adoc[]
+== Quick Start
+
+include::quickstart.adoc[]
+
== Consul overview
Features of Consul
diff --git a/docs/src/main/asciidoc/quickstart.adoc b/docs/src/main/asciidoc/quickstart.adoc
new file mode 100644
index 00000000..19143069
--- /dev/null
+++ b/docs/src/main/asciidoc/quickstart.adoc
@@ -0,0 +1,224 @@
+This quick start walks through using Spring Cloud Consul for Service Discovery and Distributed Configuration.
+
+First, run Consul Agent on your machine. Then you can access it and use it as a Service Registry and Configuration source with Spring Cloud Consul.
+
+=== Discovery Client Usage
+
+To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-consul-core`.
+The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-consul-discovery`.
+We recommend using dependency management and `spring-boot-starter-parent`.
+The following example shows a typical Maven configuration:
+
+[source,xml,indent=0]
+.pom.xml
+----
+
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ {spring-boot-version}
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-starter-consul-discovery
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-dependencies
+ ${spring-cloud.version}
+ pom
+ import
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
+----
+
+The following example shows a typical Gradle setup:
+
+[source,groovy,indent=0]
+.build.gradle
+----
+plugins {
+ id 'org.springframework.boot' version ${spring-boot-version}
+ id 'io.spring.dependency-management' version ${spring-dependency-management-version}
+ id 'java'
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation 'org.springframework.cloud:spring-cloud-starter-consul-discovery'
+ testImplementation 'org.springframework.boot:spring-boot-starter-test'
+}
+dependencyManagement {
+ imports {
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
+ }
+}
+----
+
+Now you can create a standard Spring Boot application, such as the following HTTP server:
+
+----
+@SpringBootApplication
+@RestController
+public class Application {
+
+ @GetMapping("/")
+ public String home() {
+ return "Hello World!";
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(Application.class, args);
+ }
+
+}
+----
+
+When this HTTP server runs, it connects to Consul Agent running at the default local 8500 port.
+To modify the startup behavior, you can change the location of Consul Agent by using `application.properties`, as shown in the following example:
+
+----
+spring:
+ cloud:
+ consul:
+ host: localhost
+ port: 8500
+----
+
+You can now use `DiscoveryClient`, `@LoadBalanced RestTemplate`, or `@LoadBalanced WebClient.Builder` to retrieve services and instances data from Consul, as shown in the following example:
+
+[source,java,indent=0]
+----
+@Autowired
+private DiscoveryClient discoveryClient;
+
+public String serviceUrl() {
+ List list = discoveryClient.getInstances("STORES");
+ if (list != null && list.size() > 0 ) {
+ return list.get(0).getUri().toString();
+ }
+ return null;
+}
+----
+
+=== Distributed Configuration Usage
+
+To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-consul-core` and `spring-cloud-consul-config`.
+The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-consul-config`.
+We recommend using dependency management and `spring-boot-starter-parent`.
+The following example shows a typical Maven configuration:
+
+[source,xml,indent=0]
+.pom.xml
+----
+
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ {spring-boot-version}
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-starter-consul-config
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+
+
+
+ org.springframework.cloud
+ spring-cloud-dependencies
+ ${spring-cloud.version}
+ pom
+ import
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
+----
+
+The following example shows a typical Gradle setup:
+
+[source,groovy,indent=0]
+.build.gradle
+----
+plugins {
+ id 'org.springframework.boot' version ${spring-boot-version}
+ id 'io.spring.dependency-management' version ${spring-dependency-management-version}
+ id 'java'
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation 'org.springframework.cloud:spring-cloud-starter-consul-config'
+ testImplementation 'org.springframework.boot:spring-boot-starter-test'
+}
+dependencyManagement {
+ imports {
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
+ }
+}
+----
+
+Now you can create a standard Spring Boot application, such as the following HTTP server:
+
+----
+@SpringBootApplication
+@RestController
+public class Application {
+
+ @GetMapping("/")
+ public String home() {
+ return "Hello World!";
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(Application.class, args);
+ }
+
+}
+----
+
+The application retrieves configuration data from Consul.
diff --git a/docs/src/main/asciidoc/spring-cloud-consul.adoc b/docs/src/main/asciidoc/spring-cloud-consul.adoc
index 82107fce..a273b64f 100644
--- a/docs/src/main/asciidoc/spring-cloud-consul.adoc
+++ b/docs/src/main/asciidoc/spring-cloud-consul.adoc
@@ -5,6 +5,10 @@ include::_attributes.adoc[]
include::intro.adoc[]
+== Quick Start
+
+include::quickstart.adoc[]
+
[[spring-cloud-consul-install]]
== Install Consul
Please see the https://www.consul.io/intro/getting-started/install.html[installation documentation] for instructions on how to install Consul.