Tutorial

This document provides a brief tutorial on how to use ConfigMe.

Installation

  1. Clone the ConfigMe repo
  2. Setup a virtualenv environment
  3. python ./setup develop

Defining The Problem

To demonstrate the use of of ConfigMe we will generate set of development and production configuration for NginX for a project called my-site.

Now lets look at a typical NginX configuration setup.

/etc/
`-- nginx
    |-- nginx.conf
    `-- sites-available
        `-- my-site.conf

However for nginx.conf production configuration we want gzipping on while in development configuration we want gzipping off.

Additionally we want my-site to be served on port 80 in production and port 8080 in development.

Configuration Folder Skeleton

First create the folder skeleton that will contain the templates, settings and output:

cd /tmp

mkdir -p /tmp/configme/templates/etc/nginx/sites-available
mkdir -p /tmp/configme/settings
mkdir -p /tmp/configme/output

Create etc/nginx/nginx.conf template

$EDITOR /tmp/configme/templates/etc/nginx/nginx.conf
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
user www-data;
worker_processes 4;
pid /var/run/nginx.pid;

events {
    worker_connections 768;
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    gzip {{gzip_status}};
    include /etc/nginx/sites-enabled/*;
 }

Note

The config file is a Jinja2 template and as you can see line 22 contains gzip_status variable.

Create etc/nginx/sites-available/my-site.conf template

$ $EDITOR /tmp/configme/templates/etc/nginx/sites-available/my-site.conf
1
2
3
4
5
6
7
8
9
server {
    listen {{site_port}};
    root /usr/share/nginx/www;
    index index.html index.htm;
    server_name localhost;
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Note

The config file is also Jinja2 template and line 2 contains site_port variable.

Add development Role Settings

Now lets create the development.configme file and set the gzip_status and site_port variables to their respective development values.

$EDITOR /tmp/configme/settings/development.configme
1
2
3
4
5
6
7
[etc/nginx/nginx.conf]

gzip_status = off

[etc/nginx/sites-available/my-site.conf]

site_port = 8080

Note

The development.configme settings file uses the INI format and contains sections for each of the configuration files that development role will have generated. If the file is not included in here it will not generated.

Add production Role Settings

Now lets create the production.configme file and set the gzip_status and site_port variables to their respective production values.

$EDITOR /tmp/configme/settings/production.configme
1
2
3
4
5
6
7
[etc/nginx/nginx.conf]

gzip_status = on

[etc/nginx/sites-available/my-site.conf]

site_port = 80

Note

The production.configme settings file uses the INI format and contains settings for the production role. As you can see the two configurations only differ slightly.

Resulting Configuration Skeleton

Now check the result in /tmp/configme/

/tmp/configme/
|-- output
|-- settings
|   |-- development.configme
|   `-- production.configme
`-- templates
    `-- etc
        `-- nginx
            |-- nginx.conf
            `-- sites-available
                `-- my-site.conf

Generate development Configuration

configme \
    --templates-path=/tmp/configme/templates \
    --settings-path=/tmp/configme/settings \
    --output-path=/tmp/configme/output \
    --role-name development

Generate production Configuration

configme \
    --templates-path=/tmp/configme/templates \
    --settings-path=/tmp/configme/settings \
    --output-path=/tmp/configme/output \
    --role-name production

Resulting Configuration Sets

/tmp/configme/output/
|-- development
|   `-- etc
|       `-- nginx
|           |-- nginx.conf
|           `-- sites-available
|               `-- my-site.conf
`-- production
    `-- etc
        `-- nginx
            |-- nginx.conf
            `-- sites-available
                `-- my-site.conf

What’s Next?

Learn more about ConfigMe usage in the next section: Usage