Project

An AutomateIt Project is a collection of related recipes, tags, fields and custom plugins.

Create a project

You can create a project by running the following from the Unix shell:

  automateit --create myproject

This will create a directory called myproject with a number of directories and files. Each directory has a README.txt that explains what it‘s used for.

Advantages of a project over raw recipe files

Although you can run recipes without a project, putting your recipes into a project provides you with the following benefits:

1. Directory structure to organize your files.
2. Automatically loads tags from project‘s config/tags.yml file.
3. Loads fields from the config/fields.yml file.
4. Loads all custom plugins and libraries found in the lib directory.
5. Provides a dist method that corresponds to your project‘s dist directory. Using this method will save you from having to type paths for files you intend to distribute from recipes, e.g.:

    cp(dist+"/source.txt", "/tmp/target.txt")
   

Using a project

For example, create a new project:

  automateit --create hello_project

Inside this project, edit its fields, which are stored in the config/fields.yml file, and make it look like this:

  greeting: Hello world!

Then create a recipe in the recipes/greet.rb file:

  puts lookup(:greeting)

You can run the recipe:

  automateit recipes/greet.rb

And you should get the following output:

  Hello world!

Partitioning recipes

You should split up your recipe code into different recipe files. This will improve the clarity of your code because each file can perform one task, and you‘ll also be able to easily execute a specific recipe.

For example, you can use a task-specific recipes/postgresql.rb to set up the PostgreSQL database server, and a recipes/apache.rb to setup the Apache web server.

Running recipes from other recipes

You can run one recipe from another. It‘s a good idea to create a top-level recipe that invokes the other recipes. This lets you run a single recipe that will in turn run all your other recipes in the correct order, such as setting up the database server before the web server so that websites.

For example, consider a recipes/all.rb file with these lines:

 invoke 'postgresql' if tagged? :postgresql_server
 invoke 'nginx' if tagged? :nginx_server
 invoke 'apache' if tagged? :apache_server

The first line above checks to see if the current host has the postgresql_server tag, and if it does, invokes the recipes/postgresql.rb recipe.

You must run recipes from other recipes using AutomateIt‘s invoke method and not Ruby‘s require, because the invoke passes along the AutomateIt interpreter to the other recipes so they can continue execution.

Using project libraries

Any files ending with .rb that you put into the project‘s lib directory will be loaded before your recipe starts executing. This is a good way to add common features, custom plugins and such.

For example, put the following into a new lib/meow.rb file:

  def meow
    "MEOW!"
  end

Now create a new recipe that uses this method in recipes/speak.rb

  puts meow

Now you can run it:

  automateit recipes/speak.rb

And you‘ll get this:

  MEOW!

Specifying project paths on the Unix shell

AutomateIt will load the project automatically if you‘re executing a recipe that‘s inside a project‘s recipes directory.

For example, assume that you‘ve create your project as /tmp/hello_project and have a recipe at /tmp/hello_project/recipes/greet.rb.

You can execute the recipe with a full path:

  automateit /tmp/hello_project/recipes/greet.rb

Or execute it with a relative path:

  cd /tmp/hello_project/recipes
  automateit greet.rb

Or you can prepend a header to the greet.rb recipe so it looks like this

  #!/usr/bin/env automateit

  puts lookup(:greeting)

And then make the file executable:

  chmod a+x /tmp/hello_project/recipes/greet.rb

And execute the recipe directly:

  /tmp/hello_project/recipes/greet.rb

Specifying project paths for embedded programs

If you‘re embedding the Interpreter into another Ruby program, you can run recipes and they‘ll automatically load the project if applicable. For example:

  require 'rubygems'
  require 'automateit'
  AutomateIt.invoke("/tmp/hello_project/recipes/greet.rb")

Or if you may specify the project path explicitly:

  require 'rubygems'
  require 'automateit'
  interpreter = AutomateIt.new(:project => "/tmp/hello_project")
  puts interpreter.lookup("greeting")

Tag and field command-line helpers

You can access a project‘s tags and fields from the Unix shell. This helps other programs access configuration data and make use of your roles.

For example, with the hello_project we‘ve created, we can lookup fields from the Unix shell like this:

  aifield -p /tmp/hello_project greeting

The -p specifies the project path (its an alias for —project).

More commands are available. For documentation and examples run the following commands from the Unix shell:

  aifield --help
  aitag --help

Sometimes it‘s convenient to set a default project path so you don‘t need to type as much by specifing the AUTOMATEIT_PROJECT environmental variable (or AIP if you want a shortcut) and use it like this:

  export AUTOMATEIT_PROJECT=/tmp/hello_project
  aifield greeting

Sharing a project between systems

If you want to share a project between different hosts, you‘re responsible for distributing the files between them. This isn‘t a big deal though because these are just text files and your OS has dozens of excellent ways to distribute these.

Common approaches to distribution:

• Shared directory: Your hosts mount a shared network directory (e.g., nfs or smb) with your project. This is very easy if your hosts already have a shared directory, but can be a nuisance otherwise because it opens potential security holes and risks having you hosts hang if the master goes offline.
• Client pull: Your hosts download the latest copy of your project from a master repository using a remote copy tool (e.g., rsync) or a revision control system (e.g., cvs, svn, hg). This is a safe, simple and secure option.
• Server push: You have a master push out the project files to clients using a remote copy tool and then invoke automateit on them via SSH. This can be awkward and time-consuming because the server must go through a list of all hosts and copy files to them individually.

An example of a complete solution for distributing system configuration management files:

1. Setup an svn or other version control repository to store your project and create a special account for the hosts to use to checkout code.
2. Write a wrapper script for running the recipes, for example, write a "/usr/bin/myautomateit" shell script like:

    #!/bin/sh
    cd /var/local/myautomateit
    svn update --quiet
    automateit recipe/default.rb
   

3. Run this wrapper once an hour using cron so that your systems are always up to date. AutomateIt only prints output when it makes a change, so cron will only email you when you commit new code to the repository and the hosts make changes.
4. If you need to run a recipe on the machine right now, SSH into it and run the wrapper.
5. If you need to run the script early on a bunch of machines and don‘t want to manually SSH into each one, you can leverage the aitag (see aitag —help) to execute a Unix command across multiple systems. For example, you could use a Unix shell command like this to execute the wrapper on all hosts tagged with apache_servers:

    for host in `aitag -p /var/local/myautomateit -w apache_server`; do
        echo "# $host"
        ssh $host myautomateit
    done
   

Curios

In case you‘re interested, the project creator is actually an AutomateIt recipe. You can read the recipe source code by looking at the AutomateIt::Project::create method.