README

   1 Boxer
   2 =====
   3
   4 Boxer is helper tool for "boxing" a Debian Pure Blend, e.g. putting
   5 together freedom-enabling, user-friendly services as a "FreedomBox":
   6
   7 Compose a system from a set of classes, generate, and use it!
   8
   9 Some sample classes are included.  They are easily extended, either with
  10 override files, scripts, or (preferrably) lists of packages and debconf
  11 answers tuning the install of those packages.
  12
  13 FIXME: Implement support for debconf preseeding/reconfiguration.
  14
  15 The goal of Boxer is to encourage reuse of customizations, and to ease
  16 (re)integration with Debian.  Ideally override files and scripts are
  17 used only to speedup development, then integrated into official Debian
  18 packages, and the final product uses only package lists and debconf,
  19 a.k.a. a Debian Pure Blend!
  20
  21
  22 Prerequisites
  23 -------------
  24
  25 Boxer is known to work with Debian stable (squeeze) and should work also
  26 with testing (wheezy) and unstable (sid).
  27
  28 The specific requirements depend on actual use of Boxer.
  29
  30 Boxer by default installs to /media/boxer, expects the device to not
  31 already be mounted, and that medium is suitably formatted for the target
  32 host.  Typically this means a USB stick formatted as ext3, and add a
  33 line like this in fstab:
  34
  35         /dev/sdb1 /media/boxer ext3 noauto
  36
  37 Alternatively create a fake device as normal user with commands like
  38 these (which creates a 1.1GB image):
  39
  40         dd if=/dev/zero of=boxer_usb.img bs=1M count=1024
  41         /sbin/mkfs.ext3 -F boxer_usb.img
  42
  43 ...and add a line like this in /etc/fstab:
  44
  45         /home/you/boxer_usb.img /media/boxer ext3 loop,user,rw,exec,noauto
  46
  47 Example 1 below additionally needs this (invoked as root):
  48
  49         aptitude install git fakeroot multistrap fai-client mount rsync
  50
  51 Example 2 needs these (invoked as root and adjusted for actual device):
  52
  53         mkdir -p /media/freedom
  54         echo '/dev/sdb1 /media/freedom ext3 noauto' >> /etc/fstab
  55         aptitude install git approx sudo multistrap fai-client mount rsync
  56         echo 'debian http://cdn.debian.net/debian' >> /etc/approx/approx.conf
  57         adduser $YOUR_USERNAME sudo
  58
  59
  60 Getting the source
  61 ------------------
  62
  63         git clone git://git.debian.org/git/collab-maint/boxer.git
  64         cd boxer
  65         git submodule update --init
  66
  67
  68 Usage
  69 -----
  70
  71 Simple use of Boxer goes something like this:
  72
  73  1. Compose your system by selecting from available classes
  74  2. Generate your custom system
  75  3. Attach (but don't mount) your already formatted medium
  76  4. Install your new system onto the attached medium
  77  5. Attach medium onto target system, boot, and enjoy!
  78
  79 Repeat steps 3-5 ad libitum for multiple equal systems.
  80
  81 Do a 'make clean' and repeat all for a different composition.
  82
  83 See "Hacking" below for customizing further...
  84
  85 Example 1: Simple server w/ XMPP-based webchat:
  86
  87         bin/boxerenclass ipv4ll webchat
  88         make
  89         sudo make install
  90
  91 FIXME: implement inclusion of kernel and bootloader for above.
  92
  93 Example 2: Simple development draft of FreedomBox w/ XMPP-based webchat:
  94
  95 NB! Please inspect config.mk - don't just use it blindly!
  96
  97         cp config.mk.example config.mk
  98         bin/boxerenclass ipv4ll webchat
  99         make
 100         sudo make install
 101
 102
 103 Workarounds
 104 -----------
 105
 106 For Squeeze and older:
 107
 108   * Early finalizing with fakeroot for alien arch broken (bug#617669).
 109     + Either use su-do-helper sudo, finalize mounted or at first boot,
 110       or use backports of qemu 1.0~rc4+dfsg or newer.
 111   * Real root (sudo as su-do-helper) broken (bug#556402).
 112     + Either use fakeroot, disable class NET, or use backport of
 113       ifupdown 0.7~rc3 or newer.
 114   * installing resolvconf with multistrap broken (bug#662724).
 115     + Either disable class NET, or use backport of resolvconf 1.67 or
 116       newer.
 117
 118 For Wheezy and newer:
 119
 120   * Installing apache2.2-common with multistrap broken (bug#697465).
 121     + Either avoid class HTTP, or hack multistrap/bin/install.sh to
 122       post-configure failing packages before other packages, ignoring
 123       errors, and/or apply tweaks to mimic what those failing packages
 124       intended to configure.
 125
 126
 127 Hacking
 128 -------
 129
 130 User-exposed classes are filenames in the subdir classes-available.
 131 Each file contains subclasses.  Additional classes (even non user-exposed
 132 ones) can also be added in config.mk.
 133
 134 Customizations live below the subdir tweaks.
 135
 136 Preferrably all customizations are expressed as for a Debian Pure Blend
 137 - i.e. purely do package installs and "remote-control" with debconf how
 138 they should configure themselves:
 139
 140   * package lists
 141   * debconf answers
 142
 143 Classic sysadmin-style "hacking on top" is also supported in the form of
 144 isolated "tweaks" - either files (overwriting as needed) or shell
 145 scripts invoked inside the new system.
 146
 147   * override files
 148   * override scripts
 149
 150 All types of customizations - package lists, debconf answers, override
 151 files and override scripts - are tied to classes.  You can ignore that
 152 and just tie everything the the class DEFAULT, but you are encouraged to
 153 group things to ease reuse by other related customization projects.
 154
 155 NB! When adding override files or scripts, try make as minimal changes
 156 as possible.
 157
 158 NB! This does a full build, saving all output for later debugging:
 159
 160         make install > >(tee stdout.log) 2> >(tee stderr.log >&2)
 161
 162
 163 Anatomy
 164 -------
 165
 166 Boxer is a tool to bootstrap and deploy custom instances of Debian,
 167 separating customizations in ways that encourage reuse and adoption of
 168 them into Debian itself.
 169
 170 Boxer handles these tasks:
 171
 172   * basesystem - install (but not configure) core packages
 173   * packages - install (but not configure) non-core packages
 174   * configure - apply Debian-pure (default or preseeded) configurations
 175   * customize - apply non-Debian changes
 176   * install - transfer system to target environment
 177
 178 By default, root is faked, target architecture is emulated, and tasks
 179 needing full environment are done last.
 180
 181 Tasks are executed in this order (doing only one of each sub-step):
 182
 183  1. prep - generate configuration files for build tools
 184  2. build - install Debian packages to staging medium/chroot
 185  3. tweak - seed debconf package configurations and override files
 186  4. preinstall - finalize most possible in build environment
 187     a. configure packages etc. for same-arch
 188     b. configure packages etc. emulating alien-arch
 189     c. add script to postpone package configuration etc. to postinstall
 190  5. install - transfer system to target medium
 191     a. copy to mounted medium
 192     b. copy to loop-mounted filesystem image
 193     c. copy via network to medium mounted on host
 194  6. postinstall - finalize on host medium
 195     a. finalize on mounted medium (or loop-mounted image)
 196     b. skip (finalize as initial boot session on host, then reboot)
 197     c. skip (already fully finalized in preinstall)
 198
 199 Running "make" executes steps 1-4, and "make install" executes step 5-6.
 200
 201 Steps 4b 5a 6a require real root access in build environment.
 202
 203 TODO: Actually implement 5c.
 204
 205 TODO: Separate uniqifying from package config, and drop 6c.
 206
 207
 208  -- Jonas Smedegaard <dr@jones.dk>  Tue, 30 Aug 2011 18:47:58 +0200