From 18a69a62471191e97c096fe849e22d87ab93fa06 Mon Sep 17 00:00:00 2001 From: Chad Thompson Date: Sat, 10 Oct 2015 13:36:23 -0500 Subject: [PATCH 1/7] First commit of the QuickStart --- docs/quickstart.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/quickstart.md diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 000000000..10a940540 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,57 @@ +# A QuickStart Guide to the NGINX Module + +The goal of this module is to simplify the deployment and management of + +## Why NGINX? + +Before going too far, make sure that the [NGINX][] web server is appropriate for your needs. NGINX +was designed to be a scalable web and proxy server with the abiilty to handle +thousands of concurrent connections, but it is not designed to manage dynamic content. For dynamic +web applications, NGINX must be configured to _proxy_ connections to a different process. For +example, a PHP application in the common "LAMP Stack" configuration with Apache and PHP only requires a +few dynamic modules and configuration changes. Running the same application with an NGINX infrastructure + requires the configuration of a NGINX proxy layer and a secondary runtime such as [PHP-FPM][phpfpm]. This + can add complexity to setting up the infrastructure, but it does allow you to scale application layers + independently. For a good comparison of how NGINX differs from Apache, [DigitalOcean][] published + a [good article][nginxvsapache] detailing some of the differences between the two. + +**NOTE**: At this point, the module only supports Debian or RedHat based linux distributions. + +## Basic NGINX Installation and Configuration + +Installing NGINX and setting up your first web host is relatively straightforward. To install +NGINX with the puppet module, simply call the class in a puppet manifest: +``` + class{'nginx': } +``` +This will install the NGINX package from the software repository of your Linux distribution, which can often be quite dated. If you would like to install NGINX from repositories maintained by the NGINX project directly, allow the `nginx` class to manage package repositories: + +``` +class{'nginx': + manage_repo => true, + package_source => 'nginx-mainline' +} +``` +The choices here are `nginx-stable` (the current 'production' level release) and `nginx-mainline` (where active development is occuring) - you can read a full explanation of the differences [here][nginxpackages]. + +### Creating Your First Virtual Host + +Calling the `nginx` class from your manifest simply installs the NGINX software and puts some basic configuration in place. In this state, NGINX will not serve web pages or proxy to other services - for that, we need to define a *server*. In NGINX terminology, a *server* is how we define our services (such as websites) with a name. (If you are used to configuring Apache, a server is identical to an Apache *virtual host*.) A simple virtual host that serves static web pages can be defined with a server name and a *web root*, or the directory where our HTML pages are located. + +``` + nginx::resource::vhost{'www.myhost.com': + www_root => '/opt/html/', + } +``` +In this example, the DNS address `www.myhost.com` will serve pages from the `/opt/html` directory. + +### Defining + + +[nginx]: http://nginx.org +[phpfpm]: http://php-fpm.org +[nginxpackages]: http://nginx.org/packages/mainline +[nginxdocs]: http://nginx.org/en/docs/ +[puppetlabsapache]: https://forge.puppetlabs.com/puppetlabs/apache +[digitalocean]: https://www.digitalocean.com +[nginxvsapache]: https://www.digitalocean.com/community/tutorials/apache-vs-nginx-practical-considerations \ No newline at end of file From 3084787f777285245cf390526fdee68133b4e587 Mon Sep 17 00:00:00 2001 From: Chad Thompson Date: Sat, 10 Oct 2015 14:13:22 -0500 Subject: [PATCH 2/7] Add sections to the quickstart --- docs/quickstart.md | 69 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 66 insertions(+), 3 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 10a940540..8d7374945 100644 --- a/docs/quickstart.md +++ b/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/ From f743ef65afe2806a4256228ee517b9afb5a3b0f6 Mon Sep 17 00:00:00 2001 From: Chad Thompson Date: Sat, 10 Oct 2015 14:21:17 -0500 Subject: [PATCH 3/7] Remove the preamble as unnecessary --- docs/quickstart.md | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 8d7374945..9c7c97d4d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,21 +1,4 @@ -# A QuickStart Guide to the NGINX Module - -The goal of this module is to simplify the deployment and management of - -## Why NGINX? - -Before going too far, make sure that the [NGINX][] web server is appropriate for your needs. NGINX -was designed to be a scalable web and proxy server with the abiilty to handle -thousands of concurrent connections, but it is not designed to manage dynamic content. For dynamic -web applications, NGINX must be configured to _proxy_ connections to a different process. For -example, a PHP application in the common "LAMP Stack" configuration with Apache and PHP only requires a -few dynamic modules and configuration changes. Running the same application with an NGINX infrastructure - requires the configuration of a NGINX proxy layer and a secondary runtime such as [PHP-FPM][phpfpm]. This - can add complexity to setting up the infrastructure, but it does allow you to scale application layers - independently. For a good comparison of how NGINX differs from Apache, [DigitalOcean][] published - a [good article][nginxvsapache] detailing some of the differences between the two. - -**NOTE**: At this point, the module only supports Debian or RedHat based linux distributions. +# A QuickStart Guide to the NGINX Puppet Module ## Basic NGINX Installation and Configuration From 70091da1f5cd69637226b416f751a6f1902b0388 Mon Sep 17 00:00:00 2001 From: Chad Thompson Date: Sat, 10 Oct 2015 14:29:32 -0500 Subject: [PATCH 4/7] Add a link to the QuickStart guide --- README.markdown | 12 +++++++++--- docs/quickstart.md | 10 ++++++++-- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/README.markdown b/README.markdown index 59765c595..8d4f629cd 100644 --- a/README.markdown +++ b/README.markdown @@ -15,21 +15,24 @@ Forge](http://img.shields.io/puppetforge/v/jfryman/nginx.svg)](https://forge.pup This module manages NGINX configuration. -## Quick Start - ### Requirements * Puppet-2.7.0 or later * Facter 1.7.0 or later * Ruby-1.9.3 or later (Support for Ruby-1.8.7 is not guaranteed. YMMV). +### Additional Documentation + +* [A Quickstart Guide to the NGINX Puppet Module]['/docs/quickstart.md'] + + ### Install and bootstrap an NGINX instance ```puppet class { 'nginx': } ``` -### Setup a new virtual host +### Creating a new virtual host ```puppet nginx::resource::vhost { 'www.puppetlabs.com': @@ -53,6 +56,9 @@ nginx::resource::vhost { 'rack.puppetlabs.com': } ``` + + + ### Add a smtp proxy ```puppet diff --git a/docs/quickstart.md b/docs/quickstart.md index 9c7c97d4d..8dd314757 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -89,14 +89,20 @@ Combining our configurations above into a single manifest, our code block looks } ``` -This puppet code block will: +In summary, 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`. +## References +There are a number of resources available for learning how to use NGINX effectively. Here are a few that you may find useful: +[nginx.org][nginx]: The NGNIX homepage. +[NGINX Documentation][ngixdocs]: Open Source NGINX Documentation +[NGINX vs. Apache][nginxvsapache]: A good article from [DigitalOcean][] describing the key differences between the use and architecture of NGINX vs. the Apache HTTPD server. This is a good article if you are new to NGINX or want a simple overview of the NGINX event driven architecture. + +[nginx]: http://ngnix.org [phpfpm]: http://php-fpm.org -[nginxpackages]: http://nginx.org/packages/mainline [nginxdocs]: http://nginx.org/en/docs/ [puppetlabsapache]: https://forge.puppetlabs.com/puppetlabs/apache [digitalocean]: https://www.digitalocean.com From e534823cc342f4ab9f2c7cbedd7cc8d1de726bd6 Mon Sep 17 00:00:00 2001 From: Chad Thompson Date: Sat, 10 Oct 2015 14:31:29 -0500 Subject: [PATCH 5/7] Fix the link to the QuickStart Guice This should make the link to the QuickStart pull request ready. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.markdown b/README.markdown index 8d4f629cd..29d973080 100644 --- a/README.markdown +++ b/README.markdown @@ -23,7 +23,7 @@ This module manages NGINX configuration. ### Additional Documentation -* [A Quickstart Guide to the NGINX Puppet Module]['/docs/quickstart.md'] +* [A Quickstart Guide to the NGINX Puppet Module]['https://github.com/jfryman/puppet-nginx/blob/master/docs/quickstart.md'] ### Install and bootstrap an NGINX instance From 350a1c9698f64c47d2b253d209a48a9e941446f8 Mon Sep 17 00:00:00 2001 From: Chad Thompson Date: Sat, 10 Oct 2015 14:31:57 -0500 Subject: [PATCH 6/7] Fix the link to the QuickStart Guice --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.markdown b/README.markdown index 29d973080..204363821 100644 --- a/README.markdown +++ b/README.markdown @@ -23,7 +23,7 @@ This module manages NGINX configuration. ### Additional Documentation -* [A Quickstart Guide to the NGINX Puppet Module]['https://github.com/jfryman/puppet-nginx/blob/master/docs/quickstart.md'] +* [A Quickstart Guide to the NGINX Puppet Module][https://github.com/jfryman/puppet-nginx/blob/master/docs/quickstart.md] ### Install and bootstrap an NGINX instance From 3a813ca085888c3899945c629452adde7e155851 Mon Sep 17 00:00:00 2001 From: Chad Thompson Date: Sat, 10 Oct 2015 14:33:11 -0500 Subject: [PATCH 7/7] Break the link to a variable --- README.markdown | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.markdown b/README.markdown index 204363821..f0efc9977 100644 --- a/README.markdown +++ b/README.markdown @@ -23,7 +23,8 @@ This module manages NGINX configuration. ### Additional Documentation -* [A Quickstart Guide to the NGINX Puppet Module][https://github.com/jfryman/puppet-nginx/blob/master/docs/quickstart.md] +* [A Quickstart Guide to the NGINX Puppet Module][quickstart] +[quickstart]: https://github.com/jfryman/puppet-nginx/blob/master/docs/quickstart.md ### Install and bootstrap an NGINX instance