= Cleverbox =

The Cleverbox sits on top of [http://trac.edgewall.org Trac] and [http://subversion.tigris.org Subversion].
It provides an interactive shell for deploying and maintaining instances of both projects.

== Features ==

 * Apache configuration templates
 * `trac.ini` configuration templates
 * Easy to setup
 * Easy to use 
 
== Prerequisites ==

 * Python-2.4+
 * Apache-2.0+
 * mod_python-3.0+
 * Trac-0.10+
 * Subversion-1.2+

== Installation ==

All operations should be performed as root.

 * Download sources :
{{{
svn export http://lab.clever-age.net/svn/lab/cleverbox/tags/0.3
}}}
 * Install sources :
{{{
python setup.py install
}}}
 * Create the directory that will hold apache configuration and cleverobx preferences :
{{{
mkdir /etc/cleverbox
}}}
 * Initialize environment :
{{{
cleverbox-admin /etc/cleverbox initenv
}}}
Provide informations required by script, follow its instructions regarding apache configuration.

== Basic usage ==

The Cleverbox implements a "client has many projects" model. You must therefore create at least one client prior to creating a new project.

Full documentation of available commands can be obtained with the command :
{{{
cleverbox-admin /etc/cleverbox help
}}}

=== Console launch ===

{{{
cleverbox-admin /etc/cleverbox
}}}

=== Client creation ===

If client already exists, you can skip this step.

{{{
client add <client_name>
}}}

When asked about enabling the client, answer "y"

=== Project creation ===

{{{
project add <client_name> <project_name>
}}}

 * When asked about the project admin, enter your login
 * When asked about enabling the project, answer "y"

Don't forget to reload Apache.

== Advanced usage ==

=== Customising Apache configuration templates for your needs ===

When creating a new project, the cleverbox will look for Apache configuration templates in directory referenced by `assets_dir` configuration directive.

Provided defaults work out of the box, but you may want to use custom configuration templates. 
You just have to change the value of `assets_dir` configuration directive and the Cleverbox will look for configuration templates in this new directory.

The available configuration templates are `apache.conf.single` or `apache.conf.multi` (depending on the value of `vhost_mode` cleverbox directive).

At project creation, the selected template's variables are subtituted with concrete values :
 * `client_name` : client's short name
 * `project_name` : project's short name
 * `clients_root` : directory holding Subversion and Trac data for each project
 * `authbackend_pass` : password for hypothetical authentication backend (ldap, etc)
 * `trac_install_dir` : directory where Trac is installed on the server
 * `domain_name` : if in "single" `vhost_mode`, host's domain name

=== Customising `trac-defaults.ini` configuration for your needs ===

This file resides in Cleverbox's `assets_dir` directory.  It holds values that will override standard's trac.ini values.

For instance, you may want The webadmin plugin to be enabled by default in all new project instances.
You just have to add these lines to the file :
{{{
[components]
webadmin.* = enabled
}}}

=== Defining defaut permission profiles ===

At project creation, the Cleverbox removes the `anonymous` permission profile and creates new profiles based on the contents of the
`permissions.ini` file (which resides in `assets_dir` directory). Example file :
{{{
[trac]
authenticated = BROWSER_VIEW CHANGESET_VIEW FILE_VIEW LOG_VIEW MILESTONE_VIEW REPORT_SQL_VIEW REPORT_VIEW ROADMAP_VIEW SEARCH_VIEW TICKET_CREATE TICKET_MODIFY TICKET_VIEW TIMELINE_VIEW WIKI_CREATE WIKI_MODIFY WIKI_VIEW
privileged = TRAC_ADMIN
}}}

== Roadmap ==

=== 0.4-beta ===

 * Integrity checks prior to environment initialisation in `ìnitenv` task
 * Better unix rights usage
 * Integration of `cleverbox-backup.sh` script

== Changelog ==

=== 2007-08-07 | trunk ===

 * '''[BC BREAK]''' Implemented overridable trac and apache configuration
 * Wrote better documentation
 * Got read of hardcoded Clever Age stuff
 * Implemented distutils installation
 * Adopted GPLv3
 * Fixed "Iteration over a non-sequence" bug

== Maintainer ==

Tristan Rivoallan (trivoallan AT clever-age DOT com)