cleverbox/documentation/trunk

Documentation for cleverbox-trunk

  1. Documentation for cleverbox-trunk
    1. Installation
    2. Usage

Installation

Prerequisites

  • python-2.4+
  • apache-2.0+
  • mod_python-3.0+
  • trac-0.10+
  • subversion-1.2+
  • setuptools-0.6b1+

Installation

All operations must be performed as root.

Source install

  • Grab the latest sources from project's svn repository : 
    svn export http://www.clever-age.org/svn/cleverbox/trunk
  • Install sources : 
    python setup.py install
  • Enable the dav_fs and dav_svn apache modules

Initialisation

  • 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.

That's it !

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 : 

#
# Client  : %(client_name)s
# Project : %(project_name)s
#
# This cleverbox configuration file enables three services for each project :
#  - Subversion : a subversion repository
#  - Trac :  a Trac (http://trac.edgewall.org) instance, linked to the subversion repository
#  - Documents : a webdav share
#
# All the services require authentication.
#
# Authentication is common to all services
<Location "/%(client_name)s/%(project_name)s">
  # Digest authentication is still experimental in apache-2.2
  AuthType Basic
  # -- File based authentification
  # This file can be generated and updated using apache's `htpasswd` executable
  AuthUserFile %(clients_root)s/%(client_name)s/var/%(project_name)s-htusers
</Location>
# -- Subversion service
<Location /%(client_name)s/%(project_name)s/svn>
  DAV svn
  SVNPath %(clients_root)s/%(client_name)s/var/svn/%(project_name)s
  # This service requires authentication
  AuthName "%(client_name)s :: %(project_name)s :: SVN"
  require valid-user
</Location>
# -- Trac service
<Location /%(client_name)s/%(project_name)s/trac>
  SetHandler mod_python
  PythonHandler trac.web.modpython_frontend
  PythonOption TracEnv %(clients_root)s/%(client_name)s/var/trac/%(project_name)s
  PythonOption TracUriRoot /%(client_name)s/%(project_name)s/trac
  SetEnv PYTHON_EGG_CACHE %(clients_root)s/%(client_name)s/tmp
</Location>
# Note : the match against "timeline" is needed to provide authenticated RSS feeds
<LocationMatch /%(client_name)s/%(project_name)s/trac/(login|timeline)>
  # This service requires authentication
  AuthName "%(client_name)s :: %(project_name)s :: Trac"
  Require valid-user
</LocationMatch>
# -- Documents service
AliasMatch /%(client_name)s/%(project_name)s/documents(.*) %(clients_root)s/%(client_name)s/htdocs/%(project_name)s$1
<Location /%(client_name)s/%(project_name)s/documents>
  Dav On
  # This service requires authentication
  AuthName "%(client_name)s :: %(project_name)s :: Documents"
  Require valid-user
</Location>

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 : 

[attachment]
# 10M
max_size = 10485760
[components]
webadmin.* = enabled
themeengine.* = enabled
svnhooks.svnhooks = enabled

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 : 

[trac]
anonymous = SEARCH_VIEW TICKET_VIEW REPORT_VIEW TIMELINE_VIEW BROWSER_VIEW FILE_VIEW CHANGESET_VIEW LOG_VIEW WIKI_VIEW ROADMAP_VIEW MILESTONE_VIEW
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

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.

Go up :

Error: Failed to load processor ParentWiki
No macro or processor named 'ParentWiki' found