Path: | README.md |
Last Update: | Wed Apr 27 16:37:28 +0000 2011 |
BoxGrinder is a set of projects that help you grind out appliances for multiple virtualization and Cloud providers.
Visit us at [boxgrinder.org](www.boxgrinder.org), or join boxgrinder on irc.freenode.net
## BoxGrinder Build
BoxGrinder Build is a command line tool to help you build appliances. With an appliance definition and just a single command, BoxGrinder can create your appliance, target it to a platform and deliver it.
### Boxgrinder Build Meta Appliance: BoxGrinder the Easy Way
The BoxGrinder Meta appliance is pre-configured with an optimal environment prepared to use BoxGrinder right from launch. Just [download the latest appliance](boxgrinder.org/download/boxgrinder-build-meta-appliance/) from boxgrinder.org in your desired format, launch it, and you‘re ready to grind out images!
It is a great way to use or test BoxGrinder in a virtual environment without affecting your local system.
Visit the [BoxGrinder Meta appliance usage article](boxgrinder.org/tutorials/boxgrinder-build-meta-appliance/) to learn more.
### Supported OSes
At present the project officially supports the following OSes in x86_64 and i386 variants:
### Requirements
#### Fedora
BoxGrinder and all of its dependencies reside within the official Fedora repositories, therefore there are no special requirements. Simply install via your package manager.
#### RHEL/CentOS
EPEL and BoxGrinder repositories locations must be added to your package manager in order to install BoxGrinder and resolve its dependencies successfully.
For detailed instructions, see: [Preparing your environment](boxgrinder.org/tutorials/boxgrinder-build-quick-start/preparing-environment/)
### Installing
Once the prerequisites are satisfied, install BoxGrinder via a package manager, for instance in YUM;
### Removing
You should remove BoxGrinder through your system package manager, for instance with YUM:
### Usage
BoxGrinder.org‘s [quick-start](boxgrinder.org/tutorials/boxgrinder-build-quick-start/) tutorial is the best place to learn the fundamentals of BoxGrinder Build, enabling you to rapidly leverage the feature-set on offer.
The following sections provide a basic overview of functionality.
### Plugins
Most of the features of BoxGrinder Build are provided through plugins, with three primary variants (Operating System, Platform and Delivery), each catering for a phase of the build process. Furthermore, the flexible and extensible structure of BoxGrinder Build enables users to seamlessly add new features and functionality.
As of version 0.9.0 BoxGrinder Build is distributed with [standard plugins](boxgrinder.org/tutorials/boxgrinder-build-plugins/#Plugin_introduction) installed by default.
Learn more: [BoxGrinder Build](boxgrinder.org/build/), [BoxGrinder Plugins](boxgrinder.org/tutorials/boxgrinder-build-plugins/)
#### Plugin Configuration
Many plugins allow, or mandate, some degree of configuration before they are executed. These properties are aggregated into a single per-user configuration file, at `~/.boxgrinder/config`. The user should consult the documentation of a given plugin to determine what fields it should be configured with, and which fields (if any), are requisite.
plugins: sftp: host: 192.168.0.1 username: boxgrinder path: /home/boxgrinder/appliances
Learn more: [BoxGrinder Plugins](boxgrinder.org/tutorials/boxgrinder-build-plugins/#Plugin_configuration)
#### Defining Appliances
Appliances are defined in YAML, the following "JEOS" definition can be used by BoxGrinder to produce a basic, but fully functional appliance;
name: f14-basic summary: Just Enough Operating System based on Fedora 14 os: name: fedora version: 14 hardware: partitions: "/": size: 2 packages: - @core * With this simple definition, BoxGrinder will produce a Fedora 14 appliance with the Core [group of packages](http://yum.baseurl.org/wiki/YumGroups). You can easily add packages, repositories, and harness a plethora of powerful features in a concise, declarative manner. * For an introduction to Appliance Definitions, see: [Quick-start, building your first appliance](http://boxgrinder.org/tutorials/boxgrinder-build-quick-start/build-your-first-appliance) * For fuller explanations of all parameters BoxGrinder offers, see: [Appliance definition parameters](http://boxgrinder.org/tutorials/appliance-definition/)
#### Building Appliances The BoxGrinder Build CLI is a simple interface through which you can instruct BoxGrinder to build your appliances. You can view a brief manual by using `boxgrinder-build —help`, and version information through `boxgrinder-build —version`
BoxGrinder Build is run with a mandatory appliance definition, along with optional platform and delivery plugin specifiers. BoxGrinder resolves the packages and associated dependencies in the appliance definition, and installs them into the new image it generates based upon the operating system and versions specified.
boxgrinder-build [appliance definition file] [options] * The two most common options are `[-p|--platform=]` and `[-d|--delivery=]`. Neither is mandatory, if platform is omitted then only the raw KVM image is created. You can can later return and target a build to different platforms, and BoxGrinder will always reuse the intermediary data where it is available. If you wish to force a rebuild, you can use the `[-f|--force]` flag. * It is possible to manually provide key-value pairs for platform and delivery plugin configuration on the command line. These will override any pre-existing plugin parameters set in the BoxGrinder config file. * Shell commands can be executed in `post` sections of the appliance definition files, which is useful for basic configuration. However, it is advisable that more complex configuration and installation of custom software is performed properly through RPM files. This is often best achieved through local repositories, which can be configured as [_ephemeral_](http://boxgrinder.org/tutorials/appliance-definition/) in order to avoid the repository being installed into the resultant image's package manager.
See: [BoxGrinder Build Usage Instructions](boxgrinder.org/tutorials/boxgrinder-build-usage-instructions/), [How to use local repositories](boxgrinder.org/tutorials/how-to-use-local-repository)
##### Examples
boxgrinder-build fedora-14.appl -p vmware -d sftp
Build an image based upon _fedora-14.appl_, and produce an image targeted at the vmware platform. Once complete, deliver by sftp. Note that each of these plugins must be configured in `~/.boxgrinder/conf` or by providing the key-value pairs as command-line arguments.