Installation

Araneida is distributed as an ASDF System. You may want to investigate whether there is a convertor from ASDF systems to your platform's package standard, in which case installation will be a simple matter of asdf-install or apt-get or pkg_add or something and you can skip to Use. Otherwise, read on ...

  1. You need an SBCL that has asdf loaded into it. In SBCL 0.8 or later, asdf is bundled and you should just be able to type (require 'asdf) to ensure this is the case.
  2. From your favourite cCLan mirror, download net-telent-date and araneida, and untar them somewhere (for simplicity, have them share a common parent directory)
  3. Create symlinks to the unpacked .asd files in a directory on your asdf *central-registry* list. For example
    * asdf::*central-registry*
    (*DEFAULT-PATHNAME-DEFAULTS* "/home/dan/src/defsystems/")
    
    $ cd /home/dan/src/defsystems/
    $ ln -s ../telent/araneida/araneida.asd ../telent/net-telent-date/net-telent-date.asd ../telent/db-sockets/db-sockets.asd .
    
  4. You should now be able to compile and load the systems with
    * (asdf:operate 'asdf:load-op 'araneida)
    
  5. If that gave you error messages, another system dependency was probably added since these instructions were last updated. Grab the extra package from cclan and add it in much the same way, then report this bug in the documentation.
  6. Congratulations. It's now working.

Use

Oh, you wanted to be able to actually use it?

;;; we need to tell araneida about one or more servers first
(defvar *araneida-site-name* "my.host.name.example.com")
(defvar *araneida-url* 
   (make-instance 'http-url :host *araneida-site-name*
                            :port 8000))
(defvar *araneida-server*
  (make-instance 'server
                 :name *araneida-site-name*
                 :base-url *araneida-url* :port 8000))
(export-server *araneida-server*)

;;; if we're going to serve static files, we could configure the known
;;; MIME types to something useful
(setf *content-types* (read-mime-types "/etc/mime.types"))

;;; At any time after Araneida knows about the
;;; my.host.name.example.com site, we can install handlers that
;;; refer to it.  For example, 

(install-handler *root-handler* 
                 (make-instance 'static-file-handler 
 	                        :pathname #p"/var/www/html/") 
                 "http://my.host.name.example.com/static-files/" 
                 nil) ;T - exact matches only, NIL - also match URLs
                      ;that this is a prefix for

;;; ready to rock?  Set up threads or SERVE-EVENT handlers (depending
;;; on what's available and/or personal preference) to handle requests
;;; in the background

#+sb-threads (install-thread-handlers)
#-sb-threads (install-serve-event-handlers)

Point your browser at http://my.host.name.example.com:8000/ to test

Use with a proxy

  • You need *araneida-url* (the external published URL of the site) to refer to the hostname and port of the proxy instead of the actual Araneida server.
    (defvar *araneida-url* 
       (make-instance 'http-url :host *araneida-site-name*))
    
    ;;; then export a server using this url, as previously 
    
    ;;; now make araneida write out some file for Apache to include
    (with-open-file (conf "/etc/apache.conf.include"
                          :direction :output
                          :if-does-not-exist :create)
      (output-apache-conf conf))
    
  • Now prepare an Apache installation with proxy support. Configure it to include /etc/apache.conf.include or whatever file you wrote out above.

    Configuring Apache is Outside The Scope of these instructions, but as a start, here are the relevant lines from my Debian laptop:

    LoadModule proxy_module /usr/lib/apache/1.3/libproxy.so
    NameVirtualHost noetboot.telent.net
    Include /etc/apache.conf.include
    
  • Start or restart Apache
  • Fire up a web browser. Browse.
  • Observe that the toplevel also still works
  • Look at the Handlers documentation to see how to write your own handlers
  • Send me mail and tell me how badly broken these instructions are. And, ideally, in what ways.