Kiss A simpler, smarter web application framework for Ruby


Config Files Application Directories Database Settings User Authentication File Caching Rack Handler Rack Builder Options Environments

Config Files

You can change your application's behavior and specify resource details by setting configuration directives. All directives are in YAML format. You'll add these directives to files in the config directory of your application: either in a file specific to a particular environment (described below), or the common.yml file, which applies to all environments.

Application Directories

Project Directory

The directory that contains your application is called your project directory. Usually your project is run from a script in the bin subdirectory or by a CGI script in the public_html directory. In both cases, the project directory is one-level up, so the project_dir setting defaults to '..'. However, if you start your app with a CGI script in public_html/cgi-bin, you'll need to change the project_dir setting. However, this setting cannot be made in a config file, since Kiss needs to know where the project directory is before it can find the config files. So we make it in the CGI script itself:


require 'rubygems'
require 'kiss'
  :rack_handler => :CGI,
  :project_dir => '../..'  # here's where we set the project_dir

Template Directory

By default, Kiss expects your templates to be stored in the same directory as your actions. If you wish to put them in a different place, such as directory named templates, set template_dir:

:template_dir: templates

Other Directories

You can also change locations of other directories:

:action_dir: somewhere
:config_dir: somewhere_else
:evolution_dir: another_place
:public_dir: yet_another_place

These paths are all relative to the project directory.

Database Settings

The database configuration directive sets a hash of information needed by Sequel to open a database connection:

  :adapter: mysql
  :host: localhost
  :database: webstore
  :user: webuser
  :password: j27fSD%2bfS#d
  :encoding: utf8

User Authentication

If you have defined an authenticate method (see the Actions chapter), you can tell Kiss to call it before running any action. You can also list which actions should be excluded from this app-wide authentication:

:authenticate_all: true
  - login
  - logout
  - register

File Caching

When Kiss reads action, model, and template files, it caches them in memory, so they can be accessed even faster if they are needed again. This is especially beneficial when running your application as a persistent server handling multiple requests, as then the files read on previous requests do not need to be read again.

By default, to facilitate development, Kiss will check the filesystem each time a file is needed, to make sure the cached version in memory is not out of date. If a requested file has been added, modified, or removed, the memory cache will be updated to match.

For higher performance, you may wish to disable the filesystem check on cached files by setting file_cache_no_reload to true:

:file_cache_no_reload: true

Rack Handler

Application Server or CGI

Kiss runs on top of Rack, which provides a variety of web server interfaces. By default, Kiss applications run on the WEBrick server, but you can change this by using the rack_handler directive. Acceptable options are: WEBrickMongrelLSWSCGIFastCGI, and SCGI. You can also use Thin if you install the Rack handler for Thin.

Here's how to configure your application to work from a CGI script:

:rack_handler: CGI

Rack Handler Options

If you need to configure Rack handler options, such as the server port number, set the rack_handler_options hash:

:rack_handler: WEBrick
  :Port: 4000

Rack Builder Options

Kiss includes several Rack builder modules. See the Rack::* classes in the Kiss rDoc for details.

To include any of the Rack builders, specify them in an array using the rack_builder directive:

 - :EmailErrors
 - :FileNotFound


As in Ruby, Merb, and other frameworks, you can build Kiss applications to run differently in distinct environments. To do this, create a directory named environments inside your config directory. Then add a YAML config file for each environment, with a .yml extension:


To set the environment, add a text file named environment (no extension) to the config directory, containing only the name of the environment to run (for example: development). If you use Subversion, Git, Rsync, or other means to copy your application files between environments, then this file should be excluded from the sync, as each environment should have its own distinct environment file, giving the name of the environment so Kiss can load the correct environment configuration file.