| 29 | | * Download sources : |
| 30 | | {{{ |
| 31 | | svn export http://lab.clever-age.net/svn/lab/cleverbox/tags/0.3 |
| 32 | | }}} |
| 33 | | * Install sources : |
| 34 | | {{{ |
| 35 | | python setup.py install |
| 36 | | }}} |
| 37 | | * Create the directory that will hold apache configuration and cleverobx preferences : |
| 38 | | {{{ |
| 39 | | mkdir /etc/cleverbox |
| 40 | | }}} |
| 41 | | * Initialize environment : |
| 42 | | {{{ |
| 43 | | cleverbox-admin /etc/cleverbox initenv |
| 44 | | }}} |
| 45 | | Provide informations required by script, follow its instructions regarding apache configuration. |
| 46 | | |
| 47 | | == Basic usage == |
| 48 | | |
| 49 | | The Cleverbox implements a "client has many projects" model. You must therefore create at least one client prior to creating a new project. |
| 50 | | |
| 51 | | Full documentation of available commands can be obtained with the command : |
| 52 | | {{{ |
| 53 | | cleverbox-admin /etc/cleverbox help |
| 54 | | }}} |
| 55 | | |
| 56 | | === Console launch === |
| 57 | | |
| 58 | | {{{ |
| 59 | | cleverbox-admin /etc/cleverbox |
| 60 | | }}} |
| 61 | | |
| 62 | | === Client creation === |
| 63 | | |
| 64 | | If client already exists, you can skip this step. |
| 65 | | |
| 66 | | {{{ |
| 67 | | client add <client_name> |
| 68 | | }}} |
| 69 | | |
| 70 | | When asked about enabling the client, answer "y" |
| 71 | | |
| 72 | | === Project creation === |
| 73 | | |
| 74 | | {{{ |
| 75 | | project add <client_name> <project_name> |
| 76 | | }}} |
| 77 | | |
| 78 | | * When asked about the project admin, enter your login |
| 79 | | * When asked about enabling the project, answer "y" |
| 80 | | |
| 81 | | Don't forget to reload Apache. |
| 82 | | |
| 83 | | == Advanced usage == |
| 84 | | |
| 85 | | === Creating your own configuration profile === |
| 86 | | |
| 87 | | The Cleverbox comes with a default set of configuration files. It is located in ``/etc/cleverbox/profiles/default/`. |
| 88 | | |
| 89 | | When creating a new project, the Cleverbox will ask the user what configuration profile should be used. |
| 90 | | It will then look for configuration files in `/etc/cleverbox/profiles/<profile>/` |
| 91 | | |
| 92 | | The `default` profile works out of the box, but you may want to create your own. |
| 93 | | Just copy `/etc/cleverbox/profiles/default/` to `/etc/cleverbox/profiles/<profile>/` and start modifying the files until they fit to your needs. |
| 94 | | |
| 95 | | A configuration profiles is composed of the following files : |
| 96 | | |
| 97 | | * `project.apache.conf` : Apache configuration for a project |
| 98 | | * `trac-defaults.ini` : Overriding of default Trac preferences |
| 99 | | * `permissions.ini` : Default Trac permissions |
| 100 | | |
| 101 | | Let's see how these files can be customised : |
| 102 | | |
| 103 | | ==== `project.apache.conf` ==== |
| 104 | | |
| 105 | | 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>`. |
| 106 | | |
| 107 | | At project creation, the file is parsed and variables are substituted with concrete values : |
| 108 | | |
| 109 | | * `client_name` : client's short name |
| 110 | | * `project_name` : project's short name |
| 111 | | * `clients_root` : directory holding Subversion and Trac data for each project |
| 112 | | * `authbackend_pass` : password for hypothetical authentication backend (ldap, etc) |
| 113 | | * `trac_install_dir` : directory where Trac is installed on the server |
| 114 | | * `domain_name` : host's domain name |
| 115 | | |
| 116 | | For instance, here's how the file provided by the `default` profile looks like : |
| 117 | | |
| 118 | | [[Include(source:cleverbox/trunk/assets/project.apache.conf, text/plain)]] |
| 119 | | |
| 120 | | ==== `trac-defaults.ini` ==== |
| 121 | | |
| 122 | | This file holds values that will override generated project's standard `trac.ini` values. |
| 123 | | |
| 124 | | At project creation, the file is parsed and variables are substituted with concrete values : |
| 125 | | |
| 126 | | * `client_name` : client's short name |
| 127 | | * `project_name` : project's short name |
| 128 | | * `clients_root` : directory holding Subversion and Trac data for each project |
| 129 | | * `authbackend_pass` : password for hypothetical authentication backend (ldap, etc) |
| 130 | | * `trac_install_dir` : directory where Trac is installed on the server |
| 131 | | * `domain_name` : host's domain name |
| 132 | | |
| 133 | | For instance, here's how the file provided by the `default` profile looks like : |
| 134 | | |
| 135 | | [[Include(source:cleverbox/trunk/assets/trac-defaults.ini, text/ini)]] |
| 136 | | |
| 137 | | It rises the allowed attachment size to 10M and enables ``webadmin` and ``themeengine` plugins by default. |
| 138 | | |
| 139 | | === `permissions.ini` === |
| 140 | | |
| 141 | | At project creation, the Cleverbox removes the `anonymous` permission profile and creates new profiles based on the contents of the |
| 142 | | `permissions.ini`. |
| 143 | | |
| 144 | | For instance, here's how the file provided by the `default` profile looks like : |
| 145 | | |
| 146 | | [[Include(source:cleverbox/trunk/assets/permissions.ini, text/ini)]] |
| 147 | | |
| 148 | | == Design documentation == |
| 149 | | |
| 150 | | === The environment directory === |
| 151 | | |
| 152 | | '''Default directory is `/etc/cleverbox`'''. |
| 153 | | |
| 154 | | This directory holds configuration information about one Cleverbox environment. It looks like this : |
| 155 | | |
| 156 | | * `clients-available` : holds apache configuration available for every client. |
| 157 | | * `clients-enabled` : contains symlinks to files located in the ''clients-available'' dir. Each file located in this directory is loaded at apache startup. |
| 158 | | * `projects-available` : holds apache configuration available for every project. |
| 159 | | * `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''). |
| 160 | | * `VERSION` : this files contains the version number of the Cleverbox used to initiliaze the environment |
| 161 | | * `cleverbox.ini` : this file holds configuration for the Cleverbox environment |
| 162 | | |
| 163 | | === The data directory === |
| 164 | | |
| 165 | | '''Default directory is `/var/cleverbox`'''. |
| 166 | | |
| 167 | | Each client has a dedicated project environment. It looks like this : |
| 168 | | |
| 169 | | {{{ |
| 170 | | |- htdocs |
| 171 | | |- <project> |
| 172 | | |- logs |
| 173 | | |- tmp |
| 174 | | |- uploads |
| 175 | | |- var |
| 176 | | |- svn |
| 177 | | |- <project> |
| 178 | | |- trac |
| 179 | | |- <project> |
| 180 | | }}} |
| 181 | | |
| 182 | | === The assets directory === |
| 183 | | |
| 184 | | '''Default directory is `/usr/share/cleverbox/assets`'''. |
| 185 | | |
| 186 | | It holds the files used to generate the `default` configuration profile when instanciating a new Cleverbox environment. |
| 187 | | |
| 188 | | Usage and customisation of these files is explained in the "Advanced usage" section above. |
| 189 | | |
| 190 | | == Roadmap == |
| 191 | | |
| 192 | | === Unplanned === |
| 193 | | |
| 194 | | * [ticket:3 Integrate import / export capabilities] |
| 195 | | * [ticket:9 More integrty checking] |
| 196 | | |
| 197 | | === 0.4-beta === |
| 198 | | |
| 199 | | * [ticket:1 trac.ini-defaults should be interpolated] |
| 200 | | * [ticket:2 Rework apache templates handling] |
| 201 | | * [ticket:4 Use setuptools over distutils] |
| 202 | | * [ticket:10 Subversion hooks handling] |
| 203 | | |
| 204 | | == Changelog == |
| 205 | | |
| 206 | | === 2007-08-10 | trunk === |
| 207 | | |
| 208 | | * Added documentation about design |
| 209 | | * Removed hardcoded paths in apache configuration templates (backported to 0.3) |
| 210 | | * Rewrote documentation for new "configuration profiles". Tried to make it a bit clearer |
| 211 | | * '''[BC BREAK]''' Implemented "[ticket:2 Rework apache templates handling]" |
| 212 | | * fixed [ticket:10 Subversion hooks handling] : http://trac-hacks.org/wiki/TracSvnHooksPlugin is enabled by default |
| 213 | | |
| 214 | | === 2007-08-07 | 0.3-beta === |
| 215 | | |
| 216 | | * '''[BC BREAK]''' Implemented overridable trac and apache configuration |
| 217 | | * Wrote better documentation |
| 218 | | * Got read of hardcoded Clever Age stuff |
| 219 | | * Implemented distutils installation |
| 220 | | * Adopted GPLv3 |
| 221 | | * Fixed "Iteration over a non-sequence" bug |
| 222 | | |
| 223 | | == Maintainer == |
| 224 | | |
| 225 | | Tristan Rivoallan (trivoallan AT clever-age DOT com) |
| | 32 | * Project homepage : http://www.clever-age.org/trac/wiki/cleverbox |
| | 33 | * Project's maintainer is Tristan Rivoallan (trivoallan AT clever-age DOT com) <-- insults and love letters go there |
