Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Ruby Gem for generating Apache configurations
Branch: master
Failed to load latest commit information.
autotest now generates symlinked dirs in rake task, with option to turn off fo…
bin a bunch of updates, especially to the rake apache:create task
config more reek cleanup
skel get rid of the symlink thing and just recreate the config directory e…
.gitignore what is this i don't even
CHANGELOG changelog
Gemfile one could not include the include module the old way
Gemfile.lock one could not include the include module the old way
Guardfile rearrange some things to make it more modern
README.rdoc update readme
Rakefile modernize rakefile
apache-config-generator.gemspec one could not include the include module the old way


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[environment] creates your config files for the specified environment

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

  • apache:default[environment] 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 method:'sites-available/my-site.conf') do
  server_name ''
  document_root '/var/www/my-cool-website'

  server_admin! ""

  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 => ''
    rewrite_test '/index.gif', '/lol-image-stealer.html', :http_referer => ''
    rewrite_test '/index.gif', '/index.gif', :http_referer => ''

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 ""
DocumentRoot "/var/www/my-cool-website"

<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.

Something went wrong with that request. Please try again.