Fix documentation to supply more information for help to setup basic auth with NGINX

yoonjs2 · yoonjs2 · commit 3d48de43df9c · 2016-05-09T00:29:40.000+09:00
diff --git a/docs/security/authentication.md b/docs/security/authentication.md
@@ -34,42 +34,43 @@ This instruction based on Ubuntu 14.04 LTS but may work with other OS with few c
 
 1. Install NGINX server on your server instance
 
-    You can install NGINX server with same machine where zeppelin installed or separate machine where it is dedicated to serve as proxy server.
+    You can install NGINX server with same box where zeppelin installed or separate box where it is dedicated to serve as proxy server.
 
     ```
     $ apt-get install nginx
     ```
+    *Important: On pre 1.3.13 version of NGINX, Proxy for Websocket may not fully works. Please use latest version of NGINX. See: [NGINX documentation](https://www.nginx.com/blog/websocket-nginx/)*
 
 1. Setup init script in NGINX
 
     In most cases, NGINX configuration located under `/etc/nginx/sites-available`. Create your own configuration or add your existing configuration at `/etc/nginx/sites-available`.
 
     ```
     $ cd /etc/nginx/sites-available
-    $ touch my-basic-auth
+    $ touch my-zeppelin-auth-setting
     ```
 
-    Now add this script into `my-basic-auth` file. You can comment out `optional` lines If you want serve Zeppelin under regular HTTP 80 Port.
+    Now add this script into `my-zeppelin-auth-setting` file. You can comment out `optional` lines If you want serve Zeppelin under regular HTTP 80 Port.
 
     ```
     upstream zeppelin {
-        server [YOUR-ZEPPELIN-SERVER-IP]:8080;
+        server [YOUR-ZEPPELIN-SERVER-IP]:[YOUR-ZEPPELIN-SERVER-PORT];   # For security, It is highly recommended to make this address/port as non-public accessible
     }
 
     # Zeppelin Website
     server {
         listen [YOUR-ZEPPELIN-WEB-SERVER-PORT];
-        listen 443 ssl;  # optional, to serve HTTPS connection
-        server_name [YOUR-ZEPPELIN-SERVER-HOST];    # for example: zeppelin.mycompany.com
+        listen 443 ssl;                                      # optional, to serve HTTPS connection
+        server_name [YOUR-ZEPPELIN-SERVER-HOST];             # for example: zeppelin.mycompany.com
 
         ssl_certificate [PATH-TO-YOUR-CERT-FILE];            # optional, to serve HTTPS connection
         ssl_certificate_key [PATH-TO-YOUR-CERT-KEY-FILE];    # optional, to serve HTTPS connection
 
         if ($ssl_protocol = "") {
-            rewrite ^ https://$host$request_uri? permanent;        # optional, force to use HTTPS
+            rewrite ^ https://$host$request_uri? permanent;  # optional, to force use of HTTPS
         }
 
-        location / {
+        location / {    # For regular websever support
             proxy_pass http://zeppelin;
             proxy_set_header X-Real-IP $remote_addr;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -80,7 +81,7 @@ This instruction based on Ubuntu 14.04 LTS but may work with other OS with few c
             auth_basic_user_file /etc/nginx/.htpasswd;
         }
 
-        location /ws {
+        location /ws {  # For websocket support
             proxy_pass http://zeppelin;
             proxy_http_version 1.1;
             proxy_set_header Upgrade websocket;
@@ -93,7 +94,7 @@ This instruction based on Ubuntu 14.04 LTS but may work with other OS with few c
     Then make a symbolic link to this file from `/etc/nginx/sites-enabled/` to enable configuration above when NGINX reloads.
 
     ```
-    $ ln -s /etc/nginx/sites-enabled/my-basic-auth /etc/nginx/sites-available/my-basic-auth
+    $ ln -s /etc/nginx/sites-enabled/my-zeppelin-auth-setting /etc/nginx/sites-available/my-zeppelin-auth-setting
     ```
 
 1. Setup user credential into `.htpasswd` file and restart server
@@ -102,11 +103,11 @@ This instruction based on Ubuntu 14.04 LTS but may work with other OS with few c
 
     ```
     $ cd /etc/nginx
-    $ htpasswd -c htpasswd [YOUR_ID]
-    $ NEW passwd: [YOUR_PASSWORD]
-    $ RE-type new passwd: [YOUR_PASSWORD_AGAIN]
+    $ htpasswd -c htpasswd [YOUR-ID]
+    $ NEW passwd: [YOUR-PASSWORD]
+    $ RE-type new passwd: [YOUR-PASSWORD-AGAIN]
     ```
-    Or you can use your own apache `.htpasswd` files in other location by setup property `auth_basic_user_file`
+    Or you can use your own apache `.htpasswd` files in other location for setting up property: `auth_basic_user_file`
 
     Restart NGINX server.
 
@@ -115,9 +116,6 @@ This instruction based on Ubuntu 14.04 LTS but may work with other OS with few c
     ```
     Then check HTTP Basic Authentication works in browser. If you can see regular basic auth popup and then able to login with credential you entered into `.htpasswd` you are good to go.
 
-    <img src="/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png" />
-    <img src="/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png" />
-
 1. More security consideration
 
 * Using HTTPS connection with Basic Authentication is highly recommended since basic auth without encryption may expose your important credential information over the network.
