apache-config-generator/README.rdoc

= Apache Config Generator

Programmatically construct your Apache configuration using a powerful DSL built in Ruby.

== Installation

<tt>gem install apache-config-generator</tt>

== Usage

Run <tt>apache-configurator <directory></tt> to create a new directory to hold your config files.
A Rakefile and config.yml file will also be generated.

== Building a config file

Configs center around the Apache::Config.build method:

  Apache::Config.build('sites-available/my-site.conf') do
    server_name 'my-cool-website.cool.wow'
    document_root '/var/www/my-cool-website'

		server_admin! "john@coswellproductions.com"

    directory '/' do
      options :follow_sym_links, :indexes
      allow_from_all
    end

    location_match %r{^/secret} do
      deny_from_all

      basic_authentication "My secret", '/etc/apache2/users/global.users', :user => :john
      satisfy :any
    end

    rewrites "My old content" do
    	cond "%{HTTP_REFERER}", '!^my-cool-website\.cool\.wow$'
    	rule %r{\.(gif|jpg|png|pdf)$}, '/lol-image-stealer.html', :last => true, :redirect => true

    	rewrite_test '/index.html', '/index.html', :http_referer => 'other.site'
    	rewrite_test '/index.gif', '/lol-image-stealer.html', :http_referer => 'other.site'
    	rewrite_test '/index.gif', '/index.gif', :http_referer => 'my-cool-website.cool.wow'
    end
  end

Notes on how the conversion works:

* Methods within the build block are translated into NerdCapsed Apache directives.
* Directives that house children take blocks that contain the child methods.
* Directives that expect regular expressions take a Regexp object.
* Passing a String as a parameter, by default, double-quotes it.
* Passing in a Symbol does not quote the parameter.
** Some directives NerdCap Symbols, such as Options
* Appending an exclamation point to the method turns off quoting.
* Shortcut methods are defined as modules under the Apache module.

There are also sanity checks that occur when configuration is being generated:

* Directives that rely on a path will check to see if the path exists.
* Since you need to use Regexp objects for directives that require a regular expression,
  bad expressions will be flagged by the Ruby interpreter.
* Rewrite rules can be tested with the rewrite_test method.

The above config is transformed into the following:

	ServerName "my-cool-website.cool.wow"
	DocumentRoot "/var/www/my-cool-website"
	ServerAdmin john@coswellproductions.com

	<Directory "/">
		Options FollowSymLinks, Indexes
		Allow from all
	</Directory>

	<LocationMatch "^/secret">
		Deny from all

		AuthType Basic
		AuthName "My secret"
		AuthUserFile "/etc/apache2/users/global.users"
		Require user john
	</LocationMatch>

	RewriteCond "%{HTTP_REFERER}" "^!my-cool-website\.cool\.wow"
	RewriteRule "\.(gif|jpg|png|pdf)$" "/lol-image-stealer.html" [L,R]