simple_apache

Table of Contents

1. Description
2. Usage - Configuration options and additional functionality
3. Limitations - OS compatibility, etc.
4. Development - Guide for contributing to the module

Description

Manage apache using puppet with configs checked out from git

Usage

See reference and examples

Limitations

• Not supported by Puppet, Inc.

Development

PRs accepted :)

Testing

This module supports testing using PDQTest.

Test can be executed with:

bundle install
make

See .travis.yml for a working CI example

Reference

Classes

• simple_apache: Apache module giving full text control over configs

Classes

simple_apache

mostly drop-in replacement for puppetlabs-apache (where noted) with built-in support for downloading full vhost and module configs from git. vhost definitions can be edited in-place for AccessLog, ErrorLog, DocumentRoot or just served raw.

simple_apache is somewhat a misnomer its simple if your an expert apache admin. Also (and more importantly) the module is not called apache which would instantly clash with the puppetlabs module of the same name. You can adjust base of the paths by setting class parameters. AccessLog ErrorLog and DocumentRoot can be adjusted on per-host basis

• See also https://forge.puppet.com/puppetlabs/vcsrepo for details of how to connect to your git repositories of config files

Examples

Configuration directory structure

/etc/httpd/
├── conf
│   ├── httpd.conf                                              <-- main httpd config
│   └── magic
├── conf.d                                                      <-- unmanaged config files
│   ├── autoindex.conf
│   ├── php.conf
│   ├── README
│   ├── userdir.conf
│   └── welcome.conf
├── conf.modules.d                                              <-- module configuration files to load
│   ├── 00-base.conf
│   ├── 00-systemd.conf
│   └── php.conf -> /etc/httpd/modules_available.d/php.conf     <-- symlink to file from git
├── ...
├── modules_available.d                                         <-- all known module configs (from git)
│   └── php.conf
├── ...
├── vhosts_available.d                                          <-- all known vhost configs (from git)
│   ├── beta.megacorp.com.conf
│   ├── dev.megacorp.com.conf
│   └── test.megacorp.com.conf
└── vhosts_enabled.d                                            <-- edited copies or symlinks of files from git
  ├── beta.megacorp.com.conf -> /etc/httpd/vhosts_available.d/beta.megacorp.com.conf
  └── test.megacorp.com.conf

DocumentRoot directory structure

/var/www/
├── cgi-bin
├── html
└── vhosts
  └── test.megacorp.com                                         <-- one directory per vhost based on ServerName
    └── index.html

Log directory structure

/var/log/httpd/
├── access_log                                                  <-- log files from main server process
├── error_log
├── test.megacorp.com-access_log                                <-- separate error/access log for each vhost
└── test.megacorp.com-error_log

Hiera data for overall server settings

simple_apache::server_settings:
  ServerAdmin: "root@megacorp.com" # pass array here if more then one setting needed

Hiera data to install a vhost and edit it for correct directories (defaults)

simple_apache::vhosts_enabled:
  "test.megacorp.com":

Hiera data to install a vhost as-is (symlink/no-edits)

simple_apache::vhosts_enabled:
  "test.megacorp.com":
    raw: true

Hiera data to install a vhost with (non-default settings)

simple_apache::vhosts_enabled:
  "test.megacorp.com":
    docroot:
      path: /home/bob/test
    error_log: /home/bob/test/error.log
    access_log: /home/bob/test/access.log
    log_format: '"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined'

Hiera data to install a vhost with specific docroot permissions

simple_apache::vhosts_enabled:
  "test.megacorp.com":
    docroot:
      path: /home/bob/test
      mode: '2750'
      owner: deployuser
      group: apache

Hiera data to install a module (file must exist in config files from git)

simple_apache::modules_enabled:
  - "php.conf"

Hiera data to configure your git sources

simple_apache::vcs_config:
  "vhosts":
    source: "https://git.megacorp.com/git/apache-vhosts.git"
  "modules":
    source: "https://git.megacorp.com/git/apache-modules.git"

Parameters

The following parameters are available in the simple_apache class.

apache_name

Data type: String

Name of the package to install (puppetlabs-apache compatible)

service_name

Data type: String

Name of the service to manage (puppetlabs-apache compatible)

conf_dir

Data type: String

Path to main configuration file directory (puppetlabs-apache compatible)

confd_dir

Data type: String

Path to configuration fragments (puppetlabs-apache compatible)

mod_dir

Data type: String

Path to configuration fragments for modules (puppetlabs-apache compatible)

logroot

Data type: String

Path to directory to store all logs in (puppetlabs-apache compatible)

vhost_dir

Data type: String

Path to store virtual host docroots under (puppetlabs-apache compatible)

vhost_available_dir

Data type: String

Path to checkout virtual host definitions from VCS

vhost_enabled_dir

Data type: String

Directory containing active vhost entries

mod_available_dir

Data type: String

Path to checkout module configs from VCS

vcs_config

Data type: Hash

Checkout details for config files from git (see examples)

Default value: {}

vhosts_enabled

Data type: Hash[String, Optional[Hash]]

Hash of sites to enable (must be present in vhost_available_dir)

Default value: {}

modules_enabled

Data type: Array[String]

Array of modules to enable (must be present in mod_available_dir)

Default value: []

manage_package

Data type: Boolean

true to enable management of the package (puppetlabs-apache compatible)

Default value: true

manage_service

Data type: Boolean

true to enable management of the service (puppetlabs-apache compatible)

Default value: true

apache_user

Data type: String

User who should own apache-writable files (puppetlabs-apache compatible)

apache_group

Data type: String

Group who should own apache-writable files (puppetlabs-apache compatible)

server_settings

Data type: Hash[String,Variant[String,Array[String]]]

Hash of server settings to apply to httpd.conf using augeas

Default value: {}