Cheyenne's configuration file (httpd.cfg) must be in the same folder as Cheyenne binary or %cheyenne.r file, if run from sources.
Cheyenne's configuration file uses a REBOL dialect as data storage format. This choice provides a simple format to read/write both for humans and for Cheyenne's config file parser. The file is structured using REBOL blocks in, at least, 3 sections.
Typical httpd.cfg file structure :
modules [...] globals [...] default [...]
Minimal configuration file :
modules [static] globals  default [root-dir %www/]
This minimal file would make Cheyenne serve only static content from Cheyenne's www/ local folder.
Modules are the heart of Cheyenne's server abilities, they work in conjunction to provide all the features. This section lists all the loaded modules in given order of loading. You can comment or uncomment (using a semicolon) the ones you want. Usually, just keep the default list unless you know exactly what you're doing, this list is critical to the well-behaviour of Cheyenne.
Each module brings its own set of configuration directives. Be aware of that when removing a module from the list, you might loose some directives and trigger syntax errors when loading the configuration file.
Note that the embed module, if activated, will disable all the other ones (required for proper working of embedded mode).
A typical module list will look like this:
modules [ userdir internal extapp static upload action fastcgi rsp ssi alias socket ; embed ]
The globals section contains all the directives that apply globally on all virtual hosts or not related to virtual hosts. For example, the BIND? and BIND-EXTERN? directives are used to associate an handler with one or several file extensions, making them processed automatically by Cheyenne.
Typical directives in globals section:
listen [80 8000] ;-- listen to ports 80 & 8000 bind SSI to [.shtml .shtm] ;-- process files with .shtml or .shtm suffix with SSI module bind-extern CGI to .cgi ;-- process files with .cgi suffix with CGI worker handler bind-extern RSP to .rsp ;-- process files with .rsp suffix with RSP worker handler worker-libs [ %libs/mysql-protocol.r ;-- load this library in all worker processes when launched ]
This section defines the default configuration for requests that don't match any other virtual host. It acts a "catch all" net to avoid sending an HTTP error to clients requesting e.g., a not defined sub-domain. It has the same syntax rules as other Host sections (see below).
This section is not mandatory, but it is often used when setting up a new Cheyenne instance before deciding on the domain(s) name to use.
Host sections are used to define virtual hosts. You should at least have one defined (or having a default section defined) for Cheyenne to be able to serve content. You can add as much virtual hosts as you wish in the configuration file, there's no explicit limit.
A host section is defined as a virtual host identifier followed by a configuration block.
Minimal Host section definition:
domain.com [ root-dir %www/ ;-- defines the root folder for this virtual host ]
The virtual host identifier can be:
Notice the double quoting for the last option, it's mandatory to avoid a syntax error
The root-dir directive is the only mandatory part in a virtual host definition. It can be a relative or absolute path (don't forget the % prefix). Put your static content to be served for that virtual host, in that folder. The root of your folder will be accessible from http://domain.com/.
If you want that a default file be served or a default script be called when the requests ends with a slash (no explicit target resource), add a default directive listing the default files to be searched for when required.
Here's a more sophisticated example of virtual host definition:
softinnov.org [ root-dir %/c/dev/si-org/ ;-- root folder using an absolute path default %index.shtml ;-- default file when no target disable-log ;-- HTTP access logs disabled for this virtual host debug ;-- debug mode activated for RSP scripts alias "/test" %show.rsp ;-- map /test path to %show.rsp script socket-app "/chat.rsp" chat ;-- declare a web socket application on-status-code [ ;-- capture some HTTP code 404 "/404.rsp" ;-- redirect 404 return codes to a custom script ] webapp [ ;-- RSP webapp definition virtual-root "/testapp" ;-- URL path associated to this webapp root-dir %www/testapp/ ;-- root folder of the webapp auth "/testapp/login.rsp" ;-- webapp protection activated (authentication required) ;debug ;-- debug mode commented (disactivated) timeout 02:00:00 ;-- RSP session timeout changed to 2h (instead of 20mn) ] ]
Have a look in the Options pages to see what directives are available to populate the configuration file.