Omnibus determines the platform for which to build an installer based on the platform it is currently running on. That is, you can only generate a .deb file on a Debian-based system. To alleviate this caveat, the generated project includes a Test Kitchen setup suitable for generating a series of Omnibus projects.

More documentation

Configuration DSL

Though the template project will build, it will not do anything exciting. For that, you need to use the Omnibus DSL to define the specifics of your application.

Config

If present, Omnibus will use a top-level configuration file named omnibus.rb at the root of your repository. This file is loaded at runtime and includes a number of configuration tunables. Here is an example:

You can tell Omnibus to load a different configuration file by passing the --config option to any command:

$ bin/omnibus --config /path/to/config.rb

Finally, you can override a specific configuration option at the command line using the --override flag. This takes ultimate precedence over any configuration file values:

$ bin/omnibus --override use_git_caching:false

Projects

A Project DSL file defines your actual application; this is the thing you are creating a full-stack installer for in the first place. It provides a means to define the dependencies of the project (again, as specified in Software DSL definition files), as well as ways to set installer package metadata.

All project definitions must be in the config/projects directory of your Omnibus repository.

Software

Omnibus "software" files define individual software components that go into making your overall package. They are the building blocks of your application. The Software DSL provides a way to define where to retrieve the software sources, how to build them, and what dependencies they have. These dependencies are also defined in their own Software DSL files, thus forming the basis for a dependency-aware build ordering.

All Software definitions should go in the config/software directory of your Omnibus project repository.

Since the software definitions are simply ruby code, you can conditionally execute anything by wrapping it with pure Ruby that tests for the version number.

Sharing software definitions

The easiest way to share organization-wide software is via bundler and Rubygems. For an example software repository, look at Chef's omnibus-software. For more information, please see the Rubygems documentation.

It is recommended you use bundler to pull down these gems (as bundler also permits pulling software directly from GitHub):

Then add the name of the software to the list of software_gems in your Omnibus config:

software_gems %w(my-company-omnibus-software omnibus-software)

You may also specify local paths on disk (but be warned this may make sharing the project among teams difficult):

local_software_dirs %w(/path/to/software /other/path/to/software)

For all of these paths, order matters, so it is possible to depend on local software version while still retaining a remote software repo. Given the above example, Omnibus will search for a software definition named foo in this order:

The first instance of foo.rb that is encountered will be used. Please note that local (vendored) softare definitions take precedence!

Caveats

Overrides

The project definitions can override specific software dependencies by passing in override to use the correct version:

name "chef-full"# <snip># This will override the default version of "chef"
override :chef, version:"2.1.1"
dependency "chef"

The overridden version must be defined in the associated software!

Debugging

By default, Omnibus will log at the warn level. You can override this by passing the --log-level flag to your Omnibus call:

$ bin/omnibus build <project> --log-level info # or "debug"

Git caching

by default, Omnibus caches compiled software definitions, so n+1 Omnibus project builds are much faster. This functionality can be disabled by adding the following to your omnibus.rb:

use_git_caching false

License

Copyright 2012-2014 Chef Software, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.