Debian Appliance Builder
Introduction
Creating high quality appliances is a difficult task and requires deep knowledge of the underlying operating system. So we created the 'Debian Appliance Builder' to simplify that task. 'dab' is a script to automate the creation of OpenVZ appliances. It is basically a rewrite of debootstrap in perl, but uses OpenVZ instead of chroot and generates OpenVZ templates. Another difference is that it supports multi-stage building of templates. That way you can execute arbitrary scripts between package installation steps to accomplish what you want.
Furthermore, some common tasks are fully automated - like setting up a database server (mysql or postgres). To accomplish minimal template creation time, packages are cached to a local directory, so you do not need a local Debian/Ubuntu mirror (although this would speed up the first run). All generated templates includes an appliance description file. Those can be used to build appliance repositories.
'dab' is licensed under GPLv2 (Open source).
Main features
- Fully automated build process with standard 'make' scripts
- Local package cache
- Multi-stage build process
- Creates and includes appliance description files
- Simplifies various tasks like database installation
- Appliances can be certified and integrated into the Proxmox VE download directory
- Supports Debian and Ubuntu based appliances
- Generates 32 or 64 bit appliances
- Automatic dependency resolution
Target audience
'dab' is an easy way for software vendors and open source project to package their product into a "ready-to-run" appliance. Appliances can be published into the Proxmox VE appliance download directory to reach the target customer. See Download_templates_(Video).
In order to work with 'dab', basic Linux knowledge is needed.
Installation
The script needs to be run as root, so it is not recommended to start it on a production machine with running containers.
System requirements
Prepare your operating system - you can install 'dab' on the following operating systems:
- Proxmox VE (fastest)
- Proxmox VE inside Proxmox VE (KVM) - (most comfortable)
- Proxmox VE inside VMWare/XEN 64bit virtual machine
- Debian 64/Ubuntu 64 with OpenVZ Kernel (not tested)
'dab' and sample template installation
Log into Proxmox VE, and install 'dab' using apt:
apt-get install dab
Or download and install it manually from:
wget http://download.proxmox.com/debian/dists/etch/pve/binary-amd64/dab_1.1-1_all.deb
A set of examples is also available. Simple download them:
wget ftp://download.proxmox.com/sources/dab-pve-appliances_2009-01-19.tar.gz
Unpack with tar:
tar xvf dab-pve-appliances_2009-01-19.tar.gz
'dab' manual pages
The package includes a manual page:
man dab
dab(1) User Contributed Perl Documentation dab(1)
NAME
dab - Debian OpenVZ Appliance Builder
SYNOPSIS
dab command [OPTIONS]
dab init
Downloads the package descriptions form the repository. Also trun‐
cates the "logfile".
dab bootstrap
Bootstrap a debian system and allocate a temporary container (we
use IDs 90000 and above).
--exim
Use exim as MTA (we use postfix by default)
--minimal
Do not install standard packages.
dab veid
Print used container ID.
dab basedir
Print container private directory.
dab packagefile
Print the appliance file name.
dab install pkg ...
Install one or more packages. pkg can also refer to a file named
"xyz.pkglist" which contains a list of packages. All dependencies
are automatically installed.
dab unpack pkg ...
Unpack one or more packages. pkg can also refer to a file named
"xyz.pkglist" which contains a list of packages. All dependencies
are automatically unpacked.
dab exec CMD ARGS
Executes command CMD inside the container.
dab enter
Calls "vzctl enter CTID" - this is for debugging only.
dab task mysql
Install a mysql database server. During appliance generation we use
"admin" as mysql root password (also stored in /root/.my.cnf).
--password=XXX
Specify the mysql root password. The special value "random" can
be use to generate a random root password when the appliance is
started first time (stored in /root/.my.cnf)
--start
Start the mysql server (if you want to execute sql commands
during appliance generation).
dab task postgres
Install a postgres database server.
--version=XXX
Select Postgres version. Posible values are 7.4, 8.1 and 8.3
(depends on the selected suite).
--start
Start the postgres server (if you want to execute sql commands
during appliance generation).
dab task php
Install php5.
--memlimit=i
Set the php memory_limit.
dab finalize
Cleanup everything inside the container and generate the final
appliance package.
--keepmycnf
Do not delete file "/root/.my.cfg" (mysql).
dab list
List installed packages.
--verbose
Also print package versions.
dab clean
Remove all temporary file and destroy the used OpenVZ container.
dab dist-clean
Like clean, but also removes the package cache (except when you
specified your own cache directory in the config file)
DESCRIPTION
dab is a script to automate the creation of OpenVZ appliances. It is
basically a rewrite of debootstrap in perl, but uses OpenVZ instead of
chroot and generates OpenVZ templates. Another difference is that it
supports multi-stage building of templates. That way you can execute
arbitrary scripts between to accomplish what you want.
Furthermore some common tasks are fully automated, like setting up a
database server (mysql or postgres).
To accomplish minimal template creation time, packages are cached to a
local directory, so you do not need a local debian mirror (although
this would speed up the first run).
See http://pve.proxmox.com/Debian_Appliance_Builder for examples.
This script need to be run as root, so it is not recommended to start
it on a production machine with running container. Proxmox VE
(http://pve.proxmox.com) is the preferred environment, because it is
able to log the console output when a container starts. You wont be
able to detect errors during container startup when running on standard
OpenVZ. So many people run Proxmox VE inside a KVM or VMWare 64bit vir‐
tual machine to build appliances.
All generated templates includes an appliance description file. Those
can be used to build appliance repositories.
CONFIGURATION
Configuration is read from the file "dab.conf" inside the current work‐
ing directory. The files contains key value pairs, separated by colon.
Suite: etch|lenny|hardy
The Debian or Ubuntu suite.
Source: URL [components]
Defines a source location. By default we use the following for
debian:
Source: http://ftp.debian.org/debian SUITE main contrib
Source: http://security.debian.org SUITE/updates main contrib
Note: SUITE is a variable and will be substituted.
There are also reasonable defaults for Ubuntu. If you do not specify
any source the defaults are used.
Depends: dependencies
Debian like package dependencies. This can be used to make sure that
speific package versions are available.
CacheDir: path
Allows you to specify the directory where downloaded packages are
cached.
Mirror: SRCURL => DSTURL
Define a mirror location. for example:
Mirror: http://ftp.debian.org/debian => ftp://mirror/debian
All other settings in this files are also included into the appliance
description file.
Name: name
The name of the appliance.
Appliance names must consist only of lower case letters (a-z), digits
(0-9), plus (+) and minus (-) signs, and periods (.). They must be at
least two characters long and must start with an alphanumeric charac‐
ter.
Architecture: i386|amd64
Target architecture.
Version: upstream_version[-build_revision]
The version number of an appliance.
This field specifies an application area into which the appliance has
been classified. Currently we use the following section names: sys‐
tem, admin, www
Maintainer: name <email>
The appliance maintainer’s name and email address. The name should
come first, then the email address inside angle brackets <> (in
RFC822 format).
Infopage: URL
Link to web page containing more informations about this appliance.
Description: single line synopsis
extended description over several lines (indended by space) may follow.
Appliance description file
All generated templates includes an appliance description file called
/etc/appliance.info
this is the first file inside the tar archive. That way it can be eas‐
ily exctracted without scanning the whole archive. The file itself con‐
tains informations like a debian "control" file. It can be used to
build appliance repositories.
Most fields are directly copied from the configuration file "dab.conf".
Additionally there are some auto-generated files:
Installed-Size: bytes
It gives the total amount of disk space required to install the
named appliance. The disk space is represented in megabytes as a
simple decimal number.
Type: type
This is always "openvz".
OS: [debian-4.0|debian-5.0|ubuntu-8.0]
Operation system.
Appliance repositories usually add additional fields:
md5sum: md5sum
MD5 checksum
FILES
The following files are created inside your working directory:
dab.conf appliance configuration file
logfile contains installation logs
.veid stores the used container ID
cache/* default package cache directory
info/* package information cache
AUTHOR
Dietmar Maurer <dietmar@proxmox.com>
Many thanks to Proxmox Server Solutions (www.proxmox.com) for sponsor‐
ing this work.
COPYRIGHT AND DISCLAIMER
Copyright (C) 2007-2009 Proxmox Server Solutions GmbH
Copyright: dab is under GNU GPL, the GNU General Public License.
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; version 2 dated June, 1991.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
1.1 2009-01-19 dab(1)
Build Virtual Appliances
We published several examples to show how to work with 'dab'. To start, just build a first OS template based on our examples. If you understand the basics, you can start customizing your own appliance (based on a standard OS template).
Basic recommendations:
- Choose the best suitable base OS (Debian Etch or Lenny, Ubuntu Hardy)
- Choose the right architecture (32 or 64 bit): unless your appliance needs a lot of RAM choose 32 bit
- Always try to use Debian/Ubuntu packages for applications (instead of tar.gz files)
- Pre-configure applications as much as possible (PHP, Apache, MySql, Postgresql, etc.) - based on the recommendations of the software
- Use unique keys and passwords (auto generate them during first start-up)
- Define the update procedure for users running the appliance in production: if you use Debian packages, update is easy (apt-get update)
- Contact the Proxmox support team for help Proxmox Support Forum
- And finally: Get certified! See Certification Overview
Debian 5 Standard (Lenny, 32bit)
This example shows the basic steps when creating appliances with 'dab'. First step is to create a temporary working directory and cd into that directory (or just cd into the previously un-tared examples):
mkdir debian-5.0-standard cd debian-5.0-standard
Now you need to create/edit the configuration file called 'dab.conf':
Suite: lenny Architecture: i386 Name: debian-5.0-standard Version: 5.0-1 Section: system Maintainer: Proxmox Support Team <support@proxmox.com> Infopage: http://pve.proxmox.com/wiki/Debian_5.0_Standard Description: Debian 5.0 (standard) A small Debian Lenny system including all standard packages.
Next step: Download the available package lists:
dab init
Start the creation process with:
dab bootstrap
Finally build the final appliance package with:
dab finalize
Thats all. Simply upload the final template to your server (/var/lib/vz/template/cache/). Sure, always check if everything went well before releasing a template. For this purpose all output is logged to a file called 'logfile'.
When finished you may want to cleanup your working directory with:
dab clean
or use 'dist-clean' if you also want to erase the package cache directory:
dab dist-clean
You can automate above steps using make. Simply create a file called 'Makefile' (here is an example):
BASEDIR:=$(shell dab basedir)
all: info/init_ok
dab bootstrap
dab finalize
info/init_ok: dab.conf
dab init
touch $@
.PHONY: clean
clean:
dab clean
rm -f *~
.PHONY: dist-clean
dist-clean:
dab dist-clean
rm -f *~
To start template creation you can now simply type:
make
and
make clean
to cleanup the directory.
Other OS sample Appliances
These example OS templates are included in the dab-pve-appliances_2009-01-19.tar.gz
- Debian 4 Standard (Etch, 32bit)
- Debian 4 Standard (Etch, 64bit)
- Debian 5 Standard (Lenny, 64bit)
- Ubuntu 8.04 Standard (Hardy, 32bit)
- Ubuntu 8.04 Standard (Hardy, 64bit)
Sample Application Appliances
These example application templates are included in the dab-pve-appliances_2009-01-19.tar.gz
- Acquia Drupal (Debian Etch, 32 bit)
- Drupal (Debian Lenny, 32 bit)
- Mediawiki (Debian Lenny, 32 bit)
- Joomla (Debian Lenny, 32 bit)
- Wordpress (Debian Lenny, 32 bit)
- Request Tracker (Debian Lenny, 32 bit)
- Xserver (with GNOME, Debian Lenny 32 bit)
Howto certify a Virtual Appliance
Get support
Get_support including commercial support offering concerning 'dab'.