==============
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".
Aditionally you have some parameters to compile it.  I suggest that you use the `prefix' and `sysconfdir' ones; it points you to where to install the server files.  It would be something like:

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

Cherokee also has its own parameters to add some extended features:

--with-php active the PHP4 support. 
--with-mono active the ASPX support (using Mono).

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 had installed the server.
These files contents some options about the configuration and how the server should work.  The configuration file is full 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 time to time. :)

There're an important concept in the Cherokee's configuration system: the handlers.
This handlers are the way to add a conrespondence betwen a directory how do you want it to act with the content in it.
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 one for that matches.  If you access http://localhost/public/thing it will match with the first rule, so you request will be attended by the "common" handler.
There're an `special' case, the root directory "/".  If cherokee attend a request for an object stored in an unknown directory, it will use the default handler, in this case the "file" handler.
You make the directory configuration as complex or as easy as you want.


Handlers
--------
Previusly, we'd seen how to set up the correspondence betwen directory and handlers.  In this point I'm going to explain what is a handler.
Basically each handler is a independent module of cherokee that manage a request in a concret way.
At this moment, there're the flowing handlers:

* file:    It reply with files.  If the handler finds the file of the request, it send it. You have to think that this *only* send files.
* dirlist: It works listing the directory contents.  Be careful, It doesn't send files.
* common:  It's a mix of previous ones.  If the request is of a file, it will send it, 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 don't exist it will look for the clouser match.

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

* php:     If execute/evaluate PHP files.
* mono:    If execute/evaluate ASPX files.


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

Server tesoro.alobbs.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 of the server you can add again as much Directory-to-handler entries as you want.

To add a default server, just add a DocumentRoot and at least one directory entry outside of any server entry.  If any virtual server configuration match with a request, cherokee will use the default entry.


Log files
---------
Cherokee uses syslog to log information.  It is a more flexible, cleanier and the standard way to do it.
Logging can be (de)actived with the "Log" configuration parameter of the config file.  Usually you'll want to keep it actived, but in some situations (like benchmarking) it's better to keep it turned off.


User directories
----------------
Form the 0.4.2 release of Cherokee, it can work with user's personal contents.
Basically, if you add the entry "UserDir" the configuration file (a virtual server is ok).

Example:
UserDir public_html

If Cherokee is going to reply to the request http://www.alobbs.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 reading the "handler.h" header file.  You'll see one structure and 4-5 prototipe of functions.
Usually, the handler has to implement all of the functions.  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
