You are here
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
- Download any TurnKey appliance (e.g., TurnKey Core)
- Generate and apply example patch:
tklpatch-example helloworld tklpatch path/to/turnkey-core.iso helloworld
- 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.