Add sections to the quickstart

docs/quickstart.md

@@ -43,12 +43,75 @@ Calling the `nginx` class from your manifest simply installs the NGINX software
     www_root => '/opt/html/',
   }
 ```
-In this example, the DNS address `www.myhost.com` will serve pages from the `/opt/html` directory.
+In this example, the DNS address `www.myhost.com` will serve pages from the `/opt/html` directory.  The module creates some sensible defaults (such as a root location and the choice of port `*:80) with this simple definition.
 
-### Defining 
+### Defining a Proxy
 
+Setting up a simple static webserver is straightforward, but is usually not the reason we implement NGINX to serve our web applications.  NGINX is a powerful *proxy* server that can manage large numbers of connections to one or more services that can serve dynamic web applications or even provide a simple technque for load balancing requests between multiple webservers.  For this example, let's define a proxy that serves a resource from a directory on our website. (A common use of this redirect may be to define a 'blog' link or a third party web application from your main site.)  We can define this proxy as follows:
+
+```
+  nginx::resource::location{'/blog':
+    proxy => 'http://192.168.99.1/' ,
+    vhost => 'www.myhost.com'
+   }
+```
+This will proxy any requests made to `http://www.myhost.com/blog` to the URL `http://192.168.99.1/`.  Pay special attention to the use of `/` at the end of the URL we are proxying to - that will allow your query parameters or subfolder structure on your secondary webserver to remain intact.  
+
+### Defining Backend Resources
+
+We can expand on these simple proxies by defining *upstream* resources for our web applications.  Defining upstream resources allow us to define more complex scenarios such as configuration parameters, load balancing, or even the ability to share resources between virtual hosts. An upstream resource is defined with the `nginx::resource::upstream` class.  We can define a simple upstream resource by naming the resource and a single *member*.  To define an upstream resource for our previous proxy example, declare a class of type `nginx::resource::upstream` named `upstream_app`:
+
+```
+  nginx::resource::upstream { 'upstream_app':
+    members => [
+      '192.168.99.1:80',
+    ],
+  }
+  ```
+  This will define an upstream resource with our server IP of `192.168.99.1`.  To use the upstream in our previous proxy, modify the location block as follows:
+  
+  ```
+    nginx::resource::location{'/blog':
+    proxy => 'http://upstream_app/' ,
+    vhost => 'www.myhost.com'
+   }
+```
+Now `/blog` will proxy requests to services defined in our `upstream_app` resource.
+
+### Putting the pieces together
+
+Combining our configurations above into a single manifest, our code block looks like this:
+
+```
+  class{"nginx":
+    manage_repo => true,
+    package_source => 'nginx-mainline'
+
+}
+
+  nginx::resource::upstream { 'upstream_app':
+    members => [
+      '192.168.99.1:80',
+    ],
+  }
+
+  nginx::resource::vhost{'www.myhost.com':
+    www_root => '/opt/html/',
+  }
+
+  nginx::resource::location{'/proxy':
+    proxy => 'http://upstream_app/' ,
+    vhost => 'www.myhost.com',
+
+  }
+```  
+
+This puppet code block will:
+* Install the latest version of nginx from the 'mainline' nginx distributino.
+* Define a virtual host `www.myhost.com` for our website.
+* Define an *upstream* service that consists of a single external IP address.
+* Define a URL that will proxy to the upstream resource.  In this case,  `http://www.myhost.com/blog` will proxy to an external resource hosted at `http://192.168.99.1`.
 
-[nginx]: http://nginx.org
 [phpfpm]: http://php-fpm.org
 [nginxpackages]: http://nginx.org/packages/mainline
 [nginxdocs]: http://nginx.org/en/docs/