Table of Contents

The following tutorials walk through common usage scenarios including installing the Emacs web-server and running it behind a proxy. Install the Emacs web-server and run (info "web-server") to browse the full manual within Emacs, or view the HTML version at emacs-web-server.

1 Installation and running a server

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 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.
     (lambda (request)
       (with-slots (process headers) request
         (ws-response-header process 200 '("Content-type" . "text/plain"))
         (process-send-string process "hello world")))
  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.

2 Running behind a proxy

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/

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

3 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.

3.1 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.

<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/

3.2 Nginx

Created: 2014-03-10 Mon 10:46

Emacs (Org mode 8.2.5h)