Updated README. Renamed nginx.conf to nginx.sample.conf

Author: Taytay

README.md

@@ -8,41 +8,58 @@ This is a sample app showing how to run a [3Scale](http://3Scale.com) API Proxy
 Usage
 ---------
 
-First:
-Get a free [3Scale](http://3Scale.com) account and a free [Heroku.com](http://Heroku.com) account if you don't already have them.
+#### Step 1: Get 3Scale and Heroku Accounts ####
+Get a free [3Scale](http://3Scale.com) account. (When prompted, I suggest letting 3Scale generate a sample application and account for you.)
+Get a free [Heroku.com](http://Heroku.com) account. [Download the Heroku toolbelt](https://toolbelt.heroku.com/)
 
-Follow [3Scale's instructions](https://support.3scale.net/howtos/api-configuration/nginx-proxy) on setting up an Nginx proxy. Once you've configured your sandbox proxy, you can download two Nginx config files as a zip file.
-You'll skip 3scale's instructions for deploying on AWS. We'll be deploying on Heroku
+#### Step 2: Configure 3Scale Api Proxy and download Nginx config files ####
+Follow [3Scale's instructions](https://support.3scale.net/howtos/api-configuration/nginx-proxy) on setting up an Nginx proxy. Once you've configured your sandbox proxy, download the Nginx config files. (Skip 3scale's instructions for deploying on AWS since we'll be deploying on Heroku)
 
-
-Example usage
-----------------------
+#### Step 3: Clone this repo ####
 
     #Clone this repo, or your own fork of it (use your repo's URL obviously)
     $ git clone https://github.com/Taytay/api-proxy-3scale-heroku.git
 
     #go into newly cloned folder
     $ cd api-proxy-3scale-heroku
 
-Modify the nginx.conf file that 3Scale gave you to look like the nginx.conf file here.
-(Search for "HEROKU CHANGE" in my nginx.conf file to see the changes I made
 
-Paste the contents of the generated .lua file into nginx_3scale_access.lua file
+#### Step 4: Rename the generated .conf files ####
+
+When you unzip the config files that 3Scale gave you, they will look something like:
+
+    $ ls ~/proxy_configs
+    nginx_1234567890123.conf nginx_1234567890123.lua
+
+Copy them into your newly cloned folder and rename them to `nginx.conf` and `nginx_3scale_access.lua`
+
+    #Copy and rename the generated .conf and .lua files
+    $ cp ~/proxy_configs/nginx_1234567890123.conf ./nginx.conf
+    $ cp ~/proxy_configs/nginx_1234567890123.lua ./nginx_3scale_access.lua
+
+
+#### Step 5: Modify nginx.conf ####
+Make the following mandatory modifications to the nginx.conf file:
+
+    #1. Add this line to the top of the file
+    daemon off;
+    #2. replace 'listen 80;' with:
+    listen ${{PORT}};
+    #3. replace 'access_by_lua_file lua_tmp.lua;' with:
+    access_by_lua_file nginx_3scale_access.lua;
 
+See the sample **nginx.sample.conf** file for details, and for notes on other optional changes you can make.
+
+#### Step 5: Create Heroku app ####
 Create your heroku app, using the heroku-buildpack-lua buildpack:
 
-    $ heroku apps:create --buildpack http://github.com/leafo/heroku-buildpack-lua.git heroku-app-name
+    $ heroku apps:create --buildpack http://github.com/leafo/heroku-buildpack-lua.git <heroku-app-name>
 
 Commit your changes to git
 
     $ git add .
     $ git commit -m "Configuring the proxy with generated files from 3Scale"
 
-Create the 3SCALE\_PROVIDER\_KEY config variable using your secret 3Scale
-provider key. It's in the .conf file that 3Scale generates for you
-
-    $ heroku config:set 3SCALE_PROVIDER_KEY=1239832745abcde
-
 Deploy the app to heroku
 
     $ git push heroku master
@@ -55,27 +72,34 @@ Deploy the app to heroku
 
     -----> Compiled slug size: 5.0MB
     -----> Launching... done, v14
-           http://heroku-app-name.herokuapp.com deployed to Heroku
+           http://<heroku-app-name>.herokuapp.com deployed to Heroku
 
 
 Test your API proxy using an app_id and app_key you get from your 3scale control panel. More info about these credentials [here](https://support.3scale.net/howtos/api-configuration/nginx-proxy)
 
-    $ curl http://heroku-app-name.herokuapp.com:80/v1/word/awesome.json\?app_id\=12345678\&app_key\=12355abcdef12355abcdef12355abcdef
+    $ curl http://<heroku-app-name>.herokuapp.com/v1/word/awesome.json\?app_id\=YOUR_USER_APP_ID\&app_key\=YOUR_USER_APP_KEY
+
+    {"word":"awesome","sentiment":4}%
 
+Troubleshooting
+----------------------
+If something goes wrong when nginx starts up, just run `heroku logs`
+You should see something like:
+
+    2013-05-04T09:30:04.199607+00:00 heroku[web.1]: Starting process with command `start_nginx.sh`
+    2013-05-04T09:30:10.112438+00:00 heroku[web.1]: State changed from starting to up
 
 
 Motivations
 -----------
-I wanted a free way to host 3Scale's Nginx API proxy. They have a hosted proxy,
-but it's only for sandbox/testing use. Nginx is very efficient, so you won't need
-to deploy another Heroku dyno unless you're pushing insane API traffic.
-That keeps this within the free usage tier on Heroku.
-
-3Scale's AWS instructions are great, but it's even more appealing to me to run Nginx on Heroku because 
-+ It's free
-+ More stuff is managed for me
-+ It's on AWS under the hood anyway
-+ My Nginx config files are guaranteed to be revisioned
+I wanted a free way to host 3Scale's Nginx API proxy. They have a hosted proxy, but it's only for sandbox/testing use. Nginx is very efficient, so you won't need to deploy another Heroku dyno unless you're pushing insane API traffic. That keeps this within the free usage tier on Heroku.
+
+3Scale's AWS instructions are great, but it's even more appealing to me to run Nginx on Heroku because
+
++  It's free
++  More stuff is managed for me
++  It's on AWS under the hood anyway
++  My Nginx config files are guaranteed to be revisioned in Git
 
 
 Credits

nginx.conf nginx.sample.conf

@@ -5,8 +5,8 @@
 ## A few minor modifications are necessary to get the generated config
 ## to work on Heroku. Search for 'HEROKU CHANGE:' in this file and make the same
 ## changes to your nginx.conf file
-## Note that 3Scale puts their own change markers in the generated called
-## "NEED CHANGE", so you will see some of those below too.
+## Note that 3Scale puts their own CHANGE markers in the generated file,
+## so you will see some of those below too.
 
 ## NEED CHANGE (defines the user of the nginx workers)
 # user user group;
@@ -49,8 +49,9 @@ http {
       ## HEROKU CHANGE: (OPTIONAL)
       ## 3Scale normally hardcodes the provider_key here, but if you want to avoid
       ## checking that into source code, you can create a Heroku config
-      ## environment variable called "3SCALE_PROVIDER_KEY" and uncomment the
-      ## following line.
+      ## environment variable called "3SCALE_PROVIDER_KEY" like so:
+      ## $ heroku config:set 3SCALE_PROVIDER_KEY=1239832745abcde
+      ## Then, you can uncomment the following line.
       #set $provider_key "${{3SCALE_PROVIDER_KEY}}";
       set $provider_key "hardcoded_secret_3scale_providerkey";