Overview

The objective is to provide a simple way in which an appliance can be customized and extended.

Example tweaks

  • Tweaking a configuration file
  • Adding data files
  • Adding a package
  • Creating a brand new appliance leveraging a generic appliance such as Core, LAMP, Rails, etc.

Design goals

  • Well designed mechanism (simple, generic and powerful) 
  • Very simple technically to reduce barriers to entry
  • Encourage developers to publish their patches easily
    • Incorporate good developments upstream to TurnKey appliances
    • Establish opensource ecosystem of patches
    • Satisfy long tail of special needs

Usage

Applying a patch to an appliance ISO image (the patched image will be called image-patched.iso)

 tklpatch image.iso patch.tar.gz

Applying a patch to change an installed appliance instance (from inside the appliance):
Gotcha: The running system must be configured according to the tklpatch expected state unless the patch manages discrepancies (e.g., running servers, passwords, etc.)

tklpatch-apply / patch.tar.gz

Hello world example

  1. Download any TurnKey appliance (e.g., TurnKey Core)
  2. Generate and apply example patch: 
    	tklpatch-example helloworld
	tklpatch path/to/turnkey-core.iso helloworld
  3. Tweak and customize the example patch template to fit your needs.

Command syntax

TKLpatch is designed in the Unix tradition as a modular collection of simple sub-scripts. The tklpatch command itself is just the top high level script, which calls:

1) tklpatch-extract-iso
   Disassemble the ISO to extract its contents

    1) cdroot: ISO filesystem - contains bootloader and compressed rootfs
    2) rootfs: uncompressed root filesystem

2) tklpatch-apply
   Apply the patch to the root filesystem.

   Patch structure:

     patch-dir/
         debs/       # custom debian packages (installed with dpkg -i *.deb)
         overlay/    # overlay applied to root filesystem
         conf        # configuration script to execute in chroot (rootfs)

3) tklpatch-prepare-cdroot
   Prepare cdroot for ISO creation. This mainly compresses the extracted
   root filesystem.

4) tklpatch-geniso
   Generate an ISO from the cdroot.

Anatomy of a patch

A patch is a directory (which can be packaged as a gzipped tarball) which may contain any of the following files and directories:

patch/
    debs/       # custom debian packages (installed with dpkg -i *.deb)
    overlay/    # overlay applied to root filesystem
    conf        # configuration script to execute in chroot (rootfs)

Additionally, patch/ can contain a patches/ folder, which may contain nested patches (unpacked or bundled as a gzipped tarball). Nested patches will be installed in alpha-numeric ordering of their names prior to the patch that contains them (enabling patch patching).

patch1/
    patches/
        patch2/
        patch3.tar.gz
        patch4.tar.gz
        patches/
            patch5/

Nested patches facilitate modular design as changes don't need to be bundled together.