[elpa] 90/119: tutorials

[Eric Schulte]

eschulte pushed a commit to branch master
in repository elpa.

commit 358d0e53c8a6b4b767f581c2b7a64bd08cf01411
Author: Eric Schulte <address@hidden>
Date:   Fri Jan 10 17:47:24 2014 -0700

    tutorials
---
 NOTES  |  169 +++++++++++++++++++++++++++++++++++++++++++++++++---------------
 README |   17 ++++--
 2 files changed, 141 insertions(+), 45 deletions(-)

diff --git a/NOTES b/NOTES
index a81e92c..8e72006 100644
--- a/NOTES
+++ b/NOTES
@@ -1,7 +1,10 @@
                                                            -*- org -*-
+#+Title: Notes and Tasks
+#+HTML_HEAD: <style>pre{background:#232323; color:#E6E1DC;} table{margin:auto; 
width:50%;} @media(min-width:800px){div#content{max-width:800px; padding:2em; 
margin:auto;}}</style>
+#+Options: ^:{}
 
 * Notes
-* Tasks [15/24]
+* Tasks [15/21]
 ** DONE web sockets
 - http://en.wikipedia.org/wiki/WebSocket
 - http://tools.ietf.org/html/rfc6455
@@ -58,44 +61,6 @@ against common attacks.
   server nonce values to prevent reuse.
 #+end_quote
 
-** TODO tutorial or usage section in documentation [0/3]
-*** TODO running behind a proxy
-*** TODO running behind an https proxy
-**** Nginx
-http://www.cyberciti.biz/faq/howto-linux-unix-setup-nginx-ssl-proxy/
-
-**** Apache
-The following example configuration will cause Apache to act as an
-HTTPS proxy for an instance of the Emacs web server running on the
-same machine.  With this setup Apache speaks HTTPS to the outside
-world, and communicates with the Emacs web server using HTTP.  This
-requires that Apache has =mod_proxy= and =mod_ssl= enabled, and that
-the certificate and key files required for SSL are present.
-
-Assuming the Emacs web server is listening on port 8888 and is running
-on the same machine as Apache an Apache virtual host configuration
-along the same lines as the following should work.
-
-: <VirtualHost *:443>
-:     ProxyPreserveHost On
-:     ServerName yourserver.com
-: 
-:     SSLEngine On
-:     SSLCertificateFile /etc/httpd/conf/server.crt
-:     SSLCertificateKeyFile /etc/httpd/conf/server.key
-: 
-:     # Require SSL for all pages
-:     <Location/>
-:         SSLRequireSSL
-:     </Location>
-: 
-:     ProxyPass / http://127.0.0.1:8888/
-:     ProxyPassReverse / http://127.0.0.1:8888/
-: </VirtualHost>
-
-*** TODO documentation for running in a chroot jail
-see https://wiki.archlinux.org/index.php/nginx#Installation_in_a_chroot
-
 ** incremental handler calls
 not sure if the extra performance is worth the added complexity
 
@@ -167,6 +132,132 @@ low priority -- just 
[[*running%20behind%20an%20https%20proxy][run behind an htt
 This will be a pain, and will require expanding [[info:emacs-gnutls]] to
 add support for starting server processes, currently only client
 processes are supported.
+* Tutorials
+The following tutorials walk through common steps including installing
+and running instances of the Emacs web-server.
+
+** Simple installation and execution
+The following instructions 
+
+1. Ensure that you have Emacs version 24 or greater installed.
+
+   #+begin_src sh :results scalar
+     emacs --version
+   #+end_src
+
+   : GNU Emacs 24.3.1
+   : Copyright (C) 2013 Free Software Foundation, Inc.
+   : GNU Emacs comes with ABSOLUTELY NO WARRANTY.
+   : You may redistribute copies of Emacs
+   : under the terms of the GNU General Public License.
+   : For more information about these matters, see the file named COPYING.
+
+2. Download and unpack the zip archive of the Emacs web-server code
+   from 
[[https://github.com/eschulte/emacs-web-server/archive/master.zip][emacs-web-server-master.zip]]
 or clone the source code
+   repository with [[http://git-scm.com/][git]].
+
+   #+begin_src sh
+     git clone https://github.com/eschulte/emacs-web-server.git
+   #+end_src
+
+3. Move into the root of the =emacs-web-server/= directory and
+   optionally run =make= to compile the web-server code, and run =make
+   check= to test your web-server install.
+
+4. From the root of the =emacs-web-server/= directory, start an
+   instance of Emacs with web-server loaded.
+
+   #+begin_src sh
+     emacs -Q -L. -l web-server
+   #+end_src
+
+   Alternately, from an already running Emacs instance, add
+   emacs-web-server to the load path and load the web server with the
+   following.
+
+   #+begin_src emacs-lisp
+     (add-to-list 'load-path "path/to/emacs-web-server")
+     (require 'web-server)
+   #+end_src
+
+5. Evaluate the following code in =*scratch*= buffer of this Emacs
+   instance.
+
+   #+begin_src emacs-lisp
+     (ws-start
+      (lambda (request)
+        (with-slots (process headers) request
+          (ws-response-header process 200 '("Content-type" . "text/plain"))
+          (process-send-string process "hello world")))
+      9000)   
+   #+end_src
+
+6. Browse to http://localhost:9000 to see that the web-server is
+   running.
+
+7. Read the web-server 
[[http://eschulte.github.io/emacs-web-server/index.html#Top][manual]] and work 
through other 
[[http://eschulte.github.io/emacs-web-server/Usage-Examples.html#Usage-Examples][Usage
 Examples]].
+
+** Running behind a proxy
+Public-facing instance of the Emacs web-server should be run behind a
+more established web server such as [[http://httpd.apache.org/][Apache]] or 
[[http://wiki.nginx.org][Nginx]] to provide
+additional robustness and security.
+
+The following example Apache configuration may be used to have a
+public facing Apache server listening on port 80 proxy requests to a
+local web-server instance running on port 8888 of the same machine.
+
+#+begin_src conf
+  <VirtualHost *:80>
+    ServerName  yourserver.com
+  
+    ProxyPass / http://localhost:8888/
+  </VirtualHost>
+#+end_src
+
+A similar Nginx configuration is available at
+http://wiki.nginx.org/LoadBalanceExample.
+
+** Running behind an https proxy
+The following example configurations will cause Apache or Nginx to act
+as an HTTPS proxy for an instance of the Emacs web server running on
+the same machine.  With this setup Apache speaks HTTPS to the outside
+world, and communicates with the Emacs web server using HTTP.  This
+allows use of HTTPS even though the Emacs web server does not
+implement HTTPS itself.  This setup is recommended for any setup, but
+should be considered *required* for sites using BASIC HTTP
+Authentication.
+
+*** Apache
+This requires that Apache has =mod_proxy= and =mod_ssl= enabled, and
+that the certificate and key files required for SSL are present.  This
+these requirements satisfied, and assuming the Emacs web server is
+listening on port 8888 and is running on the same machine as the
+Apache web server an Apache virtual host configuration such as the
+following.
+
+#+begin_src conf
+  <VirtualHost *:443>
+      ProxyPreserveHost On
+      ServerName yourserver.com
+  
+      SSLEngine On
+      SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
+      SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
+  
+      ProxyPass / http://localhost:8888/
+      ProxyPassReverse / http://localhost:8888/
+  </VirtualHost>
+#+end_src
+
+*** Nginx
+See the following for instructions configuring Nginx as an HTTPS
+proxy.
+- http://wiki.nginx.org/SSL-Offloader#sslproxy.conf
+- http://www.cyberciti.biz/faq/howto-linux-unix-setup-nginx-ssl-proxy/
+
+** COMMENT documentation for running in a chroot jail
+See https://wiki.archlinux.org/index.php/nginx#Installation_in_a_chroot.
+
 * Bugs [1/1]
 ** DONE Sometimes servers don't stop cleanly
 - specifically servers with active client process
diff --git a/README b/README
index 573a70e..559b2cb 100644
--- a/README
+++ b/README
@@ -17,16 +17,21 @@ STATUS
 
     [1]  http://eschulte.github.io/emacs-web-server/benchmark/
 
-EXAMPLES
-    See the examples/ directory in this repository.  The Emacs Web
-    Server is also used to run a paste server [2] and serve editable
-    Org-mode pages [3].
+USAGE
+    See the examples/ directory in this repository for examples
+    demonstrating usage.  The Emacs web-server is also used to run a
+    paste server [2] and serve editable Org-mode pages [3].
 
     [2]  https://github.com/eschulte/el-sprunge
     [3]  https://github.com/eschulte/org-ehtml
 
+    The tutorials page [4] walks through usage scenarios including
+    installation and running the Emacs web-server behind a proxy.
+
+    [4]  http://eschulte.github.io/emacs-web-server/tutorials/
+
 DOCUMENTATION
     Run `make doc' to build the texinfo documentation, also available
-    online [4].
+    online [5].
 
-    [4]  http://eschulte.github.io/emacs-web-server
+    [5]  http://eschulte.github.io/emacs-web-server