==============
Cherokee intro
==============

Installation
------------
The installation of Cherokee is quite similar to any free software
package based on the autoconf/automake tools. It's just the usual
"./configure ; make install".

Additionally you have some parameters to compile it. I suggest that
you use the `prefix' and `sysconfdir' ones so you can decide where to
install the server files. It would be something like:

./configure --prefix=/usr --sysconfdir=/etc

You can also set some compilation flags to improve the server
performance using the CFLAGS parameter in the compilation phase. For
example, if you have a Pentium-3, something like this would be great:

make CFLAGS="-march=pentium3 -O3 -pipe" install


Configuration file
------------------
If you use Cherokee as a webserver (not like an embedded web server
library), it will read a configuration file to configure itself. By
default this file is /etc/cherokee.conf, but it depends on where you
have the server installed.

These files contain some options about the configuration and how the
server should work. The configuration file is fully commented, so it
will be a good point to start with. :-)

NOTE: At this moment, we're working hard on Cherokee, so we add new
configuration parameters from time to time. :)

There is an important concept in Cherokee's configuration system: the
handlers.  These handlers are the way to add a correspondence between
a directory and how do you want it to act on it's content.

The movement is being displayed further, so I'm to expose some
examples:

Directory /public {
    Handler common
}

Directory / {
    Handler file
}

When Cherokee gets a request it looks in its internal rules searching
for one that matches. If you access http://localhost/public/thing it
will match the first rule, so your request will be attended by the
"common" handler.  There is a `special' case, the root directory "/".
If Cherokee attends a request for an object stored at an unknown
directory, it will use the default handler (in this case the "file"
handler).

You can make the directory configuration as complex or as easy as you
want.


Handlers
--------
Previously, we have seen how to set up the correspondence between directory 
and handlers. At this point I'm going to explain what is a handler.
Basically each handler is a independent module of Cherokee that manages a 
request in a specific manner.
At this moment, there are the following handlers:

* file:    It replies with files. If the handler finds the requested
	      file, it sends it. You have to have in mind that this
	      *only* sends files.
* dirlist: It works listing the directory contents. Be careful, It
		 doesn't send files.
* common:  It's a mix of the previous ones. If the request is for file,
		 it will be sent, but if the request is for a directory it
		 will send the content list.
* redir:   It works redirecting the request to a new URL.
* nn:      It implements the nearest neighbor algorithm.  If the request
           doesn't exist it will look for the closer match.
* phpcgi:  Execute .php files
* cgi:     Execute CGI files

NOTE: At this moment, there are some unfinished handlers. We're working 
hard to finish the following ones:

* mono:    run/evaluate ASPX files.


Virtual hosts
-------------
The newer versions of Cherokee have virtual servers support.  You can
add as many servers as you want in the configuration system. The
configuration syntax to do this is quite similar to the rest. For
example:

Server host.example.com {
          DocumentRoot /tmp

          Directory / {
                          Handler common
          }
}

There is a basic parameter "DocumentRoot" that specifies the default
path to the content of this virtual server.

Inside the config file of the server you can add again as many
Directory-to-handler entries as you want.

To add a default server just add a DocumentRoot and at least one
directory entry outside of the existent server entries. If any virtual
server configuration matches a request, Cherokee will use the default
entry.


Log files
---------
Cherokee uses syslog to log information. It is flexible, clean and the
standard way to do it.

Logging can be (de)activated with the "Log" configuration parameter of
the config file. Usually you'll want to keep it activated, but in some
situations (like benchmarking) it's better to keep it turned off.


User directories
----------------
From release 0.4.2 Cherokee can work with personal contents of users.
Basically it is done by adding the entry "UserDir" to the
configuration file (a virtual server is ok).

Example:
UserDir public_html

If Cherokee is going to reply to the request
http://www.example.com/~user/thing it will search for the object
"thing" in the "public_html" directory of the home directory of
"user".
If no UserDir is specified, this feature will be turned off.


For developers: how to write a new handler
------------------------------------------
Writing a new handler is a simple task.

I suggest to read the "handler.h" header file. You'll see one
structure and 4-5 prototype functions.

Usually, the handler has to implement every function. The better way
to see how it works is to read the current handlers code. It's easy
and clean.


--
Alvaro Lopez Ortega
alvaro@alobbs.com
