root/cleverbox/tags/0.4.2/docs/USAGE

== 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 ==

=== Creating your own configuration profile ===

The Cleverbox comes with a default set of configuration files. It is located in ``/etc/cleverbox/profiles/default/`.

When creating a new project, the Cleverbox will ask the user what configuration profile should be used. 
It will then look for configuration files in `/etc/cleverbox/profiles/<profile>/`

The `default` profile works out of the box, but you may want to create your own.
Just copy `/etc/cleverbox/profiles/default/` to `/etc/cleverbox/profiles/<profile>/` and start modifying the files until they fit to your needs.

A configuration profiles is composed of the following files :

 * `project.apache.conf` : Apache configuration for a project
 * `trac-defaults.ini` : Overriding of default Trac preferences
 * `permissions.ini` : Default Trac permissions

Let's see how these files can be customised :

==== `project.apache.conf` ====

This file is used as a basis for creating project's Apache configuration. Resulting file will be stored in `/etc/cleverbox/projects-available/<client>-<project>`.

At project creation, the file is parsed and variables are substituted 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` : host's domain name

For instance, here's how the file provided by the `default` profile looks like :

[[Include(source:cleverbox/trunk/assets/project.apache.conf, text/plain)]]

==== `trac-defaults.ini` ====

This file holds values that will override generated project's standard `trac.ini` values.

At project creation, the file is parsed and variables are substituted 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` : host's domain name

For instance, here's how the file provided by the `default` profile looks like :

[[Include(source:cleverbox/trunk/assets/trac-defaults.ini, text/ini)]]

It rises the allowed attachment size to 10M and enables ``webadmin` and ``themeengine` plugins by default.

==== `permissions.ini` ====

At project creation, the Cleverbox removes the `anonymous` permission profile and creates new profiles based on the contents of the
`permissions.ini`.

For instance, here's how the file provided by the `default` profile looks like :

[[Include(source:cleverbox/trunk/assets/permissions.ini, text/ini)]]

== Design documentation ==

=== The environment directory ===

'''Default directory is `/etc/cleverbox`'''.

This directory holds configuration information about one Cleverbox environment. It looks like this :

 * `clients-available` : holds apache configuration available for every client.
 * `clients-enabled` : contains symlinks to files located in the ''clients-available'' dir. Each file located in this directory is loaded at apache startup.
 * `projects-available` : holds apache configuration available for every project.
 * `projects-enabled` : contains symlinks to files located in the ''projects-available'' dir. Each file located in this directory is included by the client's apache configuration file (located in ''clients-available'').
 * `VERSION` : this files contains the version number of the Cleverbox used to initiliaze the environment
 * `cleverbox.ini` : this file holds configuration for the Cleverbox environment 

=== The data directory ===

'''Default directory is `/var/cleverbox`'''.

Each client has a dedicated project environment. It looks like this :

{{{
 |- htdocs
    |- <project>
 |- logs
 |- tmp
 |- uploads
 |- var
    |- svn
       |- <project>
    |- trac
       |- <project>
}}}

=== The assets directory ===

'''Default directory is `/usr/share/cleverbox/assets`'''.

It holds the files used to generate the `default` configuration profile when instanciating a new Cleverbox environment.

Usage and customisation of these files is explained in the "Advanced usage" section above.