Apache Config Generator

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

As of version 0.2.7, your destination config directory is destroyed and re-created each time the apache:create Rake task is run.


gem install apache-config-generator


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

Rakefile tasks

Apache Config Generator defines several tasks for managing Apache config files:

  • apache:create creates your config files for the specified environment

  • apache:environments lists all possible environments that can be generated

  • apache:default sets a default environment to use with a parameter-less apache:create (or the default rake task)

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! "[email protected]"

  directory '/' do
    options :follow_sym_links, :indexes

  location_match %r{^/secret} do

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

  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'

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 [email protected]

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

<LocationMatch "^/secret">
  Deny from all

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

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

The destination configs directory is destroyed and re-created each time the apache:create Rake task is run.

Using Apache::Config separately

Include the gem and access the methods on Apache::Config directly. See test/example_standalone.rb for an example.