templar

Templar

[Config] Templar provides the ability to manage development configurations for any file in a project, using ERB templates.

Usage

Once Templar is installed and configured, it will automatically keep your local copies of configurations up-to-date. It does this by running prior to initialization of the Rails (and Capistrano) environment.

The Example section below, will give you the best idea of the usage of Templar.

Example

Most of this example is now handled by rake templar:file[filename], this task is currently only supported by Rails.

This will take you, step by step, through the process of configuring and using Templar to manage the database.yml file in a Rails application.

Before we begin, please follow the instructions in the Installation section below.

the database.yml file

development:
  adapter:  mysql
  database: name_development
  user:
  username: root
  password:
production:
  ...

git mv the database.yml file

Move the file from it's normal location to the templar directory and add the erb extension.

git mv config/database.yml config/templar/database.yml.erb

add config/database.yml to .gitignore

This means you will track the template, but not the output file.

echo "config/database.yml" > .gitignore

add file to templar.yml config

edit the config/templar.yml file and add an entry to the templates section for database.yml

templates:
  ...
  - { file: database.yml.erb,     dest: config/database.yml }

copy the configuration info from the database.yml

Copy and paste the configuration information from config/templar/database.yml.erb to templar/data.yml

# database.yml
database:
  adapter: mysql
  database: name_development
  username: root
  password:
  host: 127.0.0.1

change the database.yml.erb file

Change the values in the config/templar/database.yml.erb file to use the template variables.

The configuration values from the config/templar/data.yml file are available in the @T template variable.

development:
  adapter:  <%= @T.database.adapter %>
  database: <%= @T.database.database %>
  user:     <%= @T.database.user %>
  username: <%= @T.database.username %>
  password: <%= @T.database.password %>
production:
  ...

done

The database.yml is now managed by Templar. I'm hoping that this entire process will be simplified with a rake task.

Installation

Add the gem into the Gemfile.

Gemfile

gem 'templar'

Then run bundle install

config/environment.rb

Add the following line to this file:

Templar.init()

The templarize command

Similar to capify or wheneverize this command will add the basic configuration files for Templar to your rails application directory.

From within the rails base directory, run the command templarize . You must specify the . as part of the command.

Once the command is complete, it will have created three new files config/templar/data.yml, config/templar/data.sample.yml and config/templar.yml. It will also have added some lines to the .gitignore file.

Confguration

There are two types of configuration files for Templar.

Templar Configuration (config/templar.yml)

The templar.yml file is the primary configuration for Templar. Most often, you will only need to change the templates section of this file.

# templates: the list of files and destinations to be handled by **Templar**
templates:
  # example
  #- {file: randomconfig.yml.erb, dest: config/randomconfig.yml}

# default options
# you generally will not need to change these options

# directory: the directory containing the templated configuration files (erb) and the data file
directory: config/templar

# always_update: force the template files to be regenerated everytime
# default: false. The files will only be regenerated when the erb template is newer than the destination file
always_update: false

# the file containing the data used in the templates
# default: data.yml (relative to the "directory" configuration value)
data_file: data.yml

Configuration Data (config/templar/data.yml)

This file is ignored by git automatically (as part of the installation process). This should contain the configuration for the local development environment.

An example data.yml.

# database.yml
database:
  adapter: mysql
  database: name_development
  username: root
  password:
  host: 127.0.0.1

This file contains any of the data that will be inserted into the template configuration files. Such that if you have a database.yml.erb file managed by Templar, you can populate the data from the database block in the data.yml file.

Configuration Data (config/templar/data.sample.yml)

This file should contain the default local development environment configuration data. This is used to create the config/templar/data.yml file for users when they first setup their local development environment for the app.

See Example for more info.

Capistrano

The Capistrano integration is used for one specific purpose. It is rare and few will need it.

You can use Templar in conjunction with Capistrano to manage templated configuration files which you will be pushing directly to the server using Capistrano's push method.

This allows you to have all the same functionality of templar, when running in something other than Ruby and Rails.

I use this to manage properties files for a J2EE application in SVN, and use Capistrano to push the properties files to the servers

TODO

Clean up Capistrano integration

Still needs a bit of help.