Tutorials

Most easily installable through the GNU ELPA, run M-x package-list-packages select web-server and install. Alternately, install from the git repository at https://github.com/eschulte/emacs-web-server and update your the load.

1. Ensure that you have Emacs version 24 or greater installed.

   emacs --version
   

   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 emacs-web-server-master.zip or clone the source code repository with git.

   git clone https://github.com/eschulte/emacs-web-server.git
   

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.

   make
   make check
   

4. From the root of the emacs-web-server/ directory, start an instance of Emacs with web-server loaded.

   emacs -Q -L . -l web-server
   

   Alternately, from an already running Emacs instance, add this directory to the load path and load the web server with the following.

   (add-to-list 'load-path "path/to/emacs-web-server")
   (require 'web-server)
   

5. Evaluate the following code in *scratch* buffer of this Emacs instance.

   (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)
   

6. Browse to http://localhost:9000/ to see that the web-server is running.
7. Read the web-server manual and work through other Usage Examples.

Public-facing instance of the Emacs web-server should be run behind a more established web server such as Apache or 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.

<VirtualHost *:80>
  ServerName  yourserver.com

  ProxyPass / http://localhost:8888/
</VirtualHost>

A similar Nginx configuration is available at http://wiki.nginx.org/LoadBalanceExample.

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.