meta-overc/README.install

OverC Overview
------------------

OverC is composed of building blocks (cubes) that implement a set of related
functionality. The current cubes are:

 - dom0: provides control services to the platform and is responsible for
         launching other containers in the system. Dom0 is not manipulated
         by non admin users.
 - dom1: provides system services (such as ntpd, etc) to the platform. This
         is not used by a typical user.
 - domE: provides full 'enterprise' functionality. This includes man pages,
         development tools, graphical desktop, etc. This domain is the primary
         environment for most users.

 - cube-server: provides a full featured, headless server environment. This is
                similar to domE, without graphics.

OverC also has two essential image types, that provide a foundation for the
container runtimes. These are:

 - cube-builder: This is the image which lists all the packages required to
                 boot the platform. cube-builder is also capable of self
                 hosting and building the platform itself.
 - cube-essential: This is a minimal runtime which is used for both the
                   installer and cube-essential in the fully assembled system.


OverC build
-----------

Modify local.conf with following settings:

 # build the cube distro
 DISTRO ?= "overc"

 # build the genericx86 machine, ussing the common-pc-64 branch
 MACHINE="genericx86-64"
 KMACHINE_genericx86-64 ?= "common-pc-64"

 # IMPORTANT: remove 'image-mklibs image-prelink' from the default
 #            user classes. They break lxc-autostart.
 USER_CLASSES ?= "buildstats"

Clone the layers described in the meta-overc/README, and build the images
mentioned in the overview:

  % bitbake cube-dom0 cube-dom1 cube-domE cube-essential cube-builder

This will take some time, since multiple images and configurations are
being build and assembled.

  Note: you can also find images at: http://openlinux.windriver.com/overc/images

Once the build (or download) completes, the build artifacts must be assembled
into an installer image (see the following sections).

OverC installer
---------------

The OverC installer must be assembled from build artifacts, and provides a 
bootable USB stick that is capable of installing to a hard disk on the 
target system. It also completes required installation and configuration of
the components that make up the core system (dom0, dom1, domE, essential).

The OverC installer is available from the following repository:

  https://github.com/WindRiver-OpenSourceLabs/overc-installer.git

Once cloned, the installer must be configured for your target device (Sample
configurations are provided).

The following sample shows how to create an installer on a network block 
device, with the outputs of a typical OverC build. Changing the target device
to a USB stick results in an installer that boots and runs on most x86 targets.

 % WORKDIR=<your_working_directory>
 % CLONEDIR=<your_clone_directory> #e.g. CLONEDIR=$WORKDIR
 % cd $CLONEDIR
 % git clone git://github.com/WindRiver-OpenSourceLabs/overc-installer.git
 % mkdir -p $WORKDIR/usbhdinstaller
 % cd $WORKDIR/usbhdinstaller
 % mkdir .overc
 % cp $CLONEDIR/overc-installer/config/config-usb-cube.sh.sample .overc/config-usb-cube.sh
 % cp $CLONEDIR/overc-installer/config/config-usb.sh.sample .overc/config-usb.sh

Edit the variables in config-usb.sh to suit the build and desired installation.
In particular:

 ARTIFACTS_DIR: set this to the directory containing the built images and kernel
                e.g. $WORKDIR/tmp/deploy/images/genericx86-64
** NOTE: ARTIFACTS_DIR defined in config-usb.sh will be ignored 
         if ./cubeit is called with --artifacts <artifacts_dir>

And confirm that the following outputs exist in the artifacts directory:

 INSTALL_KERNEL="${ARTIFACTS_DIR}/bzImage"
 INSTALL_ROOTFS="${ARTIFACTS_DIR}/cube-essential-genericx86-64.tar.bz2"
 INSTALL_INITRAMFS="${ARTIFACTS_DIR}/cube-builder-initramfs-genericx86-64.cpio.gz"

One other important file to modify is the grub configuration for the bootable
USB device. It is controlled by the following variable:

  INSTALL_GRUBUSBCFG="grub-usb.cfg"

That file, located in files/grub-usb.cfg in the installer tree is used by
grub when booting, and must be tailored to the target device AND version
of grub.

Copy the grub configuration to ~/.overc/ and edit to suit your device(s).

** NOTE: the grub installed on the machine writing the USB stick is used to
         populate the bootable device. 

 % cp $CLONEDIR/overc-installer/files/grub-usb.cfg $WORKDIR/usbhdinstaller/.overc

         The sample grub configuration files are for grub2, so if the machine
         creating the stick is not grub2, they will not work.

         The only current solution is to install grub2, or modify the files
         to suit your version of grub.

Finally, edit config-usb-cube.sh to list the containers and essential rootfs
that is to be installed. This is typically:

 HDINSTALL_ROOTFS="${ARTIFACTS_DIR}/cube-essential-genericx86-64.tar.bz2"

 HDINSTALL_CONTAINERS="${ARTIFACTS_DIR}/cube-dom0-genericx86-64.tar.bz2 \
                       ${ARTIFACTS_DIR}/cube-domE-genericx86-64.tar.bz2"

At this point we have the payload to create a bootable USB disk prepared. The
scripts (or applications) that perform the final install to the target device
are found in the installers/ subdirectory. The installers can be simple, or
complex, and should be edited to suit the desired target runtime.

** Note **: carefully inspect any sample or existing installer that is placed
            on the USB installer, since they may not be appropriate for your
            target device (and hence remove / wipe data).

cube-install.sh is capable of partitioning a device, installing the essential 
rootfs, configuring grub, extracting container payloads and rebooting the
device. It serves as a good example for other custom installers.

Once the installer(s) have been modified to suit the target device, the
following example command produces a bootable nbd USB device (assuming that a
nbd has been created properly started):

 % BLOCK_DEV=<your_block_dev> # e.g. /dev/nbd0 or /dev/sdb etc.
 % sudo $CLONEDIR/overc-installer/sbin/cubeit --config $WORKDIR/usbhdinstaller/.overc/config-usb-cube.sh --artifacts $ARTIFACTS_DIR $BLOCK_DEV

We now have a bootable device, with an embedded installer + installation payload.

NOTES:

  * Puppet - The installer is able to apply puppet configurations
    during the installation. To use this functionality set
    INSTALL_PUPPET_DIR in the install config script to enable puppet
    configuration of your installation. Puppet is run in the context
    of the installed 'cube-essential' at the end of the installation
    if using cube-install.sh.

OverC installation
------------------

Once a bootable installer has been created, insert it into the target and
boot. The default USB bootable image runs cube-essential, with the login of
root/root.

After logging into the bootable device, the installer should be run to move
artifacts to their final destination device.

In our cube-install.sh example from above, the following commands should be
run (assuming an installation to a second virtual disk):

 % cd /opt/installer/
 % ./sbin/cubeit-installer images/cube-essential-* vdb #or e.g. sda for hard drive

** Note: The cube installer will destroy all data on the target device, since
         it re-partitions, create filesystems, installs the boot image and
         the rootfs + container filesystems.

         Do not run it against a device with data you cannot afford to lose.

** Note: To create the root filesystem in btrfs, add -b option to cube-install.sh
 % ./sbin/cubeit-installer -b images/cube-essential-* vdb

Once this completes, the device is powered off, and is ready with the OverC
runtime.