eschulte pushed a commit to branch master
in repository elpa.
commit 358d0e53c8a6b4b767f581c2b7a64bd08cf01411
Author: Eric Schulte <schulte.e...@gmail.com>
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
