Introduction

Roost is a provisioning system similar to puppet and chef but heavily inspired by the clean and unobtrusive design of the nodejs module eco-system. It is also a bit like grunt but without the added complexity.

Originally Roost was written in JavaScript but for better readability and reduced complexity, it is now written in CoffeeScript.

The Basics

Roost is configured through a simple manifest file, typically called roost.json, however other names can be used too. The file is used to describes how a system is provisioned, i.e what commands, packages, services and other characteristics a system needs to adhere to.

When running roost without any command-line parameters it will try to look for the manifest file inside the current working directory. With the -f|--file option you can specify any arbitrary file or directory to be used by roost. For example:

Order Of Execution

Roost does not expose means by which you can configure the order of execution of things. The order is already chosen for you in advance, which is:

plugins

bootstrap

files

packages

services

commands

tasks

This order is not finalised but this is what it is at the moment. The order of execution is pre-selected to avoid confusion and to provide some level of consistency. You can choose your own arbitary order by using tasks.

Tasks are esentially mini roost config files and they can nest inside the same roost directives as the ones described previously. Tasks can also provide dependencies. For example:

The Plugin System

The plugin system of roost is essentially the nodejs module system. You can load plugins by declaring them inside the roost manifest file as illustrated previously. The plugin must be either installed globally via npm or locally inside the node_modules folder structure.

Each plugin must export a function called getRoost or roost. Function getRoost is used to get an object that must export the function roost. The function expects two parameters: the manifest file and the target. Once the function is invoked the plugin will be able to traverse the manifest file for declarations it recognizes and execute actions via the target. A plugin may even augment the manifest structure if desired, i.e. a plugin my install more packages by simply extending the "packages" directive.

Two functions exist in the target that are useful to plugin developers: exec and spawn. Use exec to launch any shell command. Use spawn to launch an executable with a fine-grain control over the process.

For examples and inspiration check out the project source code.

Embedding Into Other Projects

Roost can be easily embedded into other projects. Check out bin/roost and lib/roost.coffee for inspiration. Just copy and paste the parts that you need. The whole project has been designed to be easily embedable so that it can live as part of larger and more complex systems.

You can also have a look at Vortex, which embeds roost as the default provisioner.

Project Status and Future Plans

The project is new and immature in some ways. We hope to change this in the upcoming months. At the moment only ubuntu/debian is supported for the packages and the services directives. Please fork it as much as you want and send us patches. We are keen to make something out of this.

Roost, although open source, is commercially backed by Websecurify. We are just starting to use it internally to manage our infrastructure. It is also the default provisioner for Vortex, which is pretty decent virtual machine management toolki. We are committed to support it in the foreseeable future so you can be assured that it is actually used to satisfy real needs.

How To Contribute

Fork the project. Improve it. Send us the patches. Write some plugins and spread the news. We are happy to help with any technical queries you may have.

We want to support the community to create all kinds of ready-made systems. Share your roost files for the world to see. Get in touch if you want them to be included as part of the default distribution.

Roost Plugins You Can Use

The easiest way to install these plugins is to create a package.json file and declare the modules just as you usually do. Execute npm install inside the same folder than use roost to load the plugins that you need. It is as simple as that.