TOC?

Managing Trac installations with Trac tools

Introduction

Maintaining a single Trac installation is really easy. Editing the configuration file, adjusting templates, installing plugins: Trac provides a great infrastructure and tool support to do that. It becomes more complicated when we have to deal with various projects with similiar (but not same) configurations, plugins and templates. This is where the Trac tools come into play: they are built to ease mainenance of such scenarios.

Basic concepts

Trac tools assume you want to derive configuration files from another. Say you have simple basic configuration and in your project-wide configuration files, you just define their project-specific settings. This makes it really easy to change global settings like SMTP configuration values.

The configuration tools support single inheritance for config files similar to what's known from programming languages like java: a child configuration can reuse and overwrite the values from its parent config.

For example this simple inheritance graph: every projects derives its settings from the base configuration.

Another variant is using a mid-level configuration which specializes the parent configuration and sets e.g. a department specific template_dir.

The workflow

Basic directory structure

• trac/
  • global/
    • templates/
      • overview.html
      • site.html
    • plugins/
    • config.ini
  • projects/
    • project1/
      • conf/
        • trac.ini
        • custom.ini
      • ...
    • project2/
      • conf/
        • trac.ini
        • custom.ini
      • ...

The global-directory is the place, where the basic configuration is stored. The projects-directory can be used as a TRAC_ENV_ROOT, alternatively each instance can be started manually (using FastCGI, mod_python or tracd). The custom.ini-files in the conf-subdirectories is the specific config, and the trac.ini is generated with trac-config-merge which merges the config.ini and the custom.ini.

Installing Trac

With Trac tools or without: the bare installation is the same. Use trac-admin <path> initenv to install your Trac instance. We fill out the few questions and after a few steps the installation is finished.

Installation cleanup

Now trac-install-cleanup comes into play: it removes unneeded default values from the freshly installed instance, and removes the default template.

Extracting the custom config

The next tool to use is trac-config-extract? to extract the specific configuration from the freshly created configuration that contains the whole set of configuration values. Use trac-config-extract --source <config> --target <target> to create your custom config. Say you choose to store the configuration in <root>/conf/custom.conf: then you later create the whole configuration with trac-config-merge.

Generating trac.ini

Now that we extracted the project specific bits from the configuration, let's generate the trac.ini, which is still required, as we don't touch Trac to do any of the magic. We generate the real trac.ini by merging the config.ini-file with the custom.ini:

$ trac-config-merge \
  --parent trac/global/config.ini \
  --child trac/projects/project1/conf/custom.ini \
  --output trac/projects/project1/conf/trac.ini

NOTE: It is recommended to create custom shell-script to replicate the command line from above. This task is pretty common (every time you edit the config) and so it makes sense to gather all config merge jobs in one shell-script.