Changeset 143

Timestamp:

08/10/07 13:54:50 (4 years ago)

Author:

trivoallan

Message:

cleverbox :

• Rewrote documentation for new "configuration profiles". Tried to make it a bit clearer
• [BC BREAK] Implemented "Rework apache templates handling"
• Fixed Subversion hooks handling :  http://trac-hacks.org/wiki/TracSvnHooksPlugin is enabled by default
• Removed "ssh_user" concept

fixes #2, #10

Location:

cleverbox/trunk

Files:

• README (modified) (5 diffs)
• assets/apache.conf.multi (deleted)
• assets/project.apache.conf (moved) (moved from cleverbox/trunk/assets/apache.conf.single) (1 diff)
• assets/trac-defaults.ini (modified) (1 diff)
• cleverbox/scripts/admin.py (modified) (10 diffs)

cleverbox/trunk/README

@@ -1 +1 @@
 = Cleverbox =
+
+[[PageOutline]]
 
 The Cleverbox sits on top of [http://trac.edgewall.org Trac] and [http://subversion.tigris.org Subversion].
@@ -6 +8 @@
 == Features ==
 
- * Apache configuration templates
- * `trac.ini` configuration templates
+ * Configuration profiles :
+   * Apache configuration templates
+   * `trac.ini` configuration template
+   * Default permissions
  * Easy to setup
- * Easy to use 
+ * Easy to use
  
 == Prerequisites ==
@@ -79 +83 @@
 == 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 :
+=== 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
@@ -94 +112 @@
  * `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 ===
+ * `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` 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
-}}}
+`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.
 
 == Roadmap ==
 
+=== Unplanned ===
+
+ * [ticket:3 Integrate import / export capabilities]
+ * [ticket:9 More integrty checking]
+
 === 0.4-beta ===
 
- * Integrity checks prior to environment initialisation in `ìnitenv` task
- * Better unix rights usage
- * Integration of `cleverbox-backup.sh` script
+ * [ticket:1 trac.ini-defaults should be interpolated] 
+ * [ticket:2 Rework apache templates handling]
+ * [ticket:4 Use setuptools over distutils]
+ * [ticket:10 Subversion hooks handling]
 
 == Changelog ==
@@ -129 +206 @@
 === 2007-08-07 | trunk ===
 
- * removed hardcoded paths in apache configuration templates (backported to 0.3)
+ * Added documentation about design
+ * Removed hardcoded paths in apache configuration templates (backported to 0.3)
+ * Rewrote documentation for new "configuration profiles". Tried to make it a bit clearer
+ * '''[BC BREAK]''' Implemented "[ticket:2 Rework apache templates handling]"
+ * fixed [ticket:10 Subversion hooks handling] : http://trac-hacks.org/wiki/TracSvnHooksPlugin is enabled by default
 
 === 2007-08-07 | 0.3-beta ===

cleverbox/trunk/assets/project.apache.conf

@@ -34 +34 @@
   # -- File based authentification
   # -- Users can be used using :
-  # --  htpasswd2 %(clients_root)s/%(client_name)s/var/trac/%(project_name)s/.htusers <username>
+  # --  htpasswd %(clients_root)s/%(client_name)s/var/trac/%(project_name)s/.htusers <username>
   AuthUserFile %(clients_root)s/%(client_name)s/var/trac/%(project_name)s/.htusers
 

cleverbox/trunk/assets/trac-defaults.ini

@@ -1 +1 @@
 [attachment]
-max_size = 25600
+max_size = 10485760
 
 [components]
 webadmin.* = enabled
 themeengine.* = enabled
+svnhooks.svnhooks

cleverbox/trunk/cleverbox/scripts/admin.py

@@ -1 +1 @@
 # -*- coding: utf-8 -*-
 
+import shutils
 import cmd
 import os
@@ -12 +13 @@
 
 _defaults = {
-    'env_dir_layout'       : ('clients-available', 'clients-enabled',
-                              'projects-available', 'projects-enabled'),
+    'env_dir_layout'    : ('clients-available', 'clients-enabled',
+                           'projects-available', 'projects-enabled',
+                           'profiles/default'),
     'client_dir_layout' : ('htdocs', 'logs', 'tmp', 'uploads',
                            'var/svn', 'var/trac'),
+    'profile_files'     : ('project.apache.conf', 'trac-defaults.ini', 'permissions.ini')
 }
 
@@ -133 +136 @@
         collected_infos['apache_group'] = raw_input('Webserver group id [%d]> ' % d_gid).strip() or d_gid
 
-        # SSH user & group
-        d_uid = '1001'
-        d_gid = '1001'
-        collected_infos['ssh_user'] = raw_input('SSH user id [%s]> ' % d_uid).strip() or d_uid
-        collected_infos['ssh_group'] = raw_input('SSH group id [%s]> ' % d_gid).strip() or d_gid
-
-        # Virtual Host mode : single or multi ?
-        d_vhost_mode = 'single'
-        collected_infos['vhost_mode'] = raw_input('Virtual host mode (either "single" or "multi") [%s]> ' % d_vhost_mode).strip() or d_vhost_mode
+        # root user & group
+        # we keep the ssh_user notion for backward compatibility.
+        # this will have to disappear in a future release 
+        collected_infos['ssh_user'] = 0
+        collected_infos['ssh_group'] = 0
+
+        # Host server domain name
+        collected_infos['domain'] = raw_input('Domain name > ').strip()
         
-        if collected_infos['vhost_mode'] == 'multi':
-            collected_infos['domain'] = raw_input('Domain name > ').strip()
-        
-        # Cleverbox assets
-        d_cleverbox_assets = '/usr/share/cleverbox'
-        collected_infos['assets_dir'] = raw_input('Cleverbox assets directory [%s]> ' % d_cleverbox_assets).strip() or d_cleverbox_assets
-
         # Authentication backend password (if any)
         collected_infos['authbackend_pass'] = raw_input('Authentication backend password (if any) []> ').strip() or ''
+
+        # Default configuration profile
+        dcp = 'default'
+        collected_infos['default_profile'] = raw_input('Default configuration profile [%s]> ' % dcp).strip() or dcp
                 
         # Write ini file
@@ -174 +173 @@
         # Create directory structure
         try:
-            print "\n\tCreating directory structure\n"
+            print "\n\tCreating directory layout\n"
             env_dirs = []
             for dirname in _defaults['env_dir_layout']:
@@ -185 +184 @@
         # Create VERSION file
         try:
+            print "\n\tCreating VERSION file\n"
             fd = open( os.path.join(self.envname, 'VERSION'), 'w' )
             fd.write(_version)
         finally:
             fd.close()
+
+        # Default configuration profile
+        print "\n\tCreating default configuration profile\n"
+        for filename in _defaults['profile_files']:
+            shutils.copy('/usr/share/cleverbox/assets/' + filename, os.path.join(self.envname, 'profile', 'default'))
+        
 
         print
@@ -695 +701 @@
             collected_infos['full_name'] = raw_input('Full Name [%s]> ' % dfn).strip() or dfn
 
+            print
+            print "  What configuration profile should be used ?"
+            print "  Those reside in %s/profiles/" % self.envname
+            print
+
+            dp = self.getConfig('default_profile', 'general')
+            collected_infos['profile'] = raw_input('Configuration profile [%s]> ' % dp).strip() or dp
+
             # Project creation
             print
@@ -751 +765 @@
         TODO : clients may not be stored in 'clients_root', be careful with that.
         """
-        conf_template = open('%s/%s.%s' % (self.getConfig('assets_dir', 'general'), 'apache.conf', self.getConfig('vhost_mode', 'general')))
+        conf_template = open(os.path.join(self.envname, 'profiles', infos['profile'], 'project.apache.conf'))
         conf_data = conf_template.read() % {'client_name'      : infos['client'],
                                             'project_name'     : infos['short_name'],
@@ -841 +855 @@
         # Grant default permissions
         perms_config = ConfigParser.SafeConfigParser()
-        perms_config.read(os.path.join(self.getConfig('assets_dir', 'general'), 'permissions.ini'))
+        perms_config.read(os.path.join(self.envname, 'profiles', infos['profile'], 'permissions.ini'))
         for profile in perms_config.options('trac'):
             os.system( trac_perms_cmd % {'env_path'   : trac_env_path,
@@ -868 +882 @@
         chmod g+w /$CLIENTSROOT/$CLIENTNAME/var/svn/$PROJECTNAME
         chown -R www-data:dev /$CLIENTSROOT/$CLIENTNAME/var/trac/$PROJECTNAME/db
-        chown dev:www-data /$CLIENTSROOT/$CLIENTNAME/var/trac/conf/trac.ini
-        chmod g+w /$CLIENTSROOT/$CLIENTNAME/var/trac/conf/trac.ini
+            chown dev:www-data /$CLIENTSROOT/$CLIENTNAME/var/trac/conf/trac.ini
+            chmod g+w /$CLIENTSROOT/$CLIENTNAME/var/trac/conf/trac.ini
         """
 
@@ -909 +923 @@
 
     def _project_trac_defaultconf(self, infos):
+        """
+        Overrides project's default trac.ini with values provided in configuration profile.
+        """
+        
         # New defaults
         tracdefaults_config = ConfigParser.SafeConfigParser()
-        tracdefaults_config.read(os.path.join(self.getConfig('assets_dir', 'general'), 'trac-defaults.ini'))
+        tracdefaults_config.read(os.path.join(self.envname, 'profiles', infos['profile'], 'trac-defaults.ini'))
         
         # Trac base config file
-        project_config_path = os.path.join('%s/%s/var/trac/%s/conf/trac.ini' % (self.getConfig('clients_root', 'general'), infos['client'], infos['short_name']))
+        project_config_path = os.path.join(self.getConfig('clients_root', 'general', infos['client'], 'var', 'trac', infos['short_name'], 'conf', 'trac.ini'))
         tracproject_config = ConfigParser.SafeConfigParser()
         tracproject_config.read(project_config_path)