Applying a patch (tutorial)

Terminology
Prerequisites
Install TKLPatch
Download the patch
Applying a patch
More advanced usage
Applying a patch from GitHub source
Applying a patch to an OVZ template (rather than ISO)

Terminology

In typical usage (e.g., on the forums) "TKLPatch" can mean one of two things:

  1. The name of the script you use to apply (or develop) patches.
  2. The thing that's applied to an ISO or running appliance to customize an appliance.

Prerequisites

You'll want to begin by installing a TurnKey system. Any appliance will do but a fresh installation of TurnKey Core is recommended.

Theoretically you can use TKLPatch in any Linux distribution but it isn't as easy to install and hasn't been well tested. Sometimes things break.

Install TKLPatch

TurnKey allows you to install tklpatch via the package management system:

apt-get update
apt-get install tklpatch

Download the patch

Usually patches will be attached as compressed files to the thread announcing a new TKLPatch in the General forum. You can download this file from within an appliance using wget:

wget http://www.turnkeylinux.org/files/...

Applying a patch

Usually a patch is designed to be applied to a specific appliance (e.g., TurnKey LAMP). You'll need to download the ISO to this appliance.

You then have two options:

  1. Patch the ISO: this customizes the ISO to create a new "patched" ISO which you can then install as an appliance. This is the recommended and best tested way to use TKLPatch. 
    tklpatch example-appliance.iso example-patch.tar.gz
  2. Install the ISO and apply the patch to the running system from within: this customizes the running system on the fly. You'll need to install tklpatch within the running system (not recommended, but possible - depending on the patch, stuff might break). 
    tklpatch-apply / example-patch.tar.gz

Note for patching behind a proxy: If you are behind a proxy, patches may not apply properly (due to an inability to download from within the chroot). To wrok around this you will need to extract the patch and edit the conf file to include

export http_proxy=http://yourproxy:yourport/etc...

More advanced usage

Applying a patch from GitHub source

Rather than being a nice tar.gz archive downloadable from the relevant TKL forum post, some patches may be hosted on GitHub and/or have newer development versions hosted on GitHub. These aren't too hard to use but may seem initially daunting for the uninitiated. Here are the steps.

  1. Install TKLPatch as above and cd to your home directory 
    cd ~
  2. Clone the relevant GitHub repo. This address can be gained from the relevant GitHub page (if the patch is hosted on GitHub there will be a link in the Patch forum post). In your browser the GitHub page should be something like github.com/example-user/example-patch. The actual git repo address should be something like git://github.com/example-user/example-patch.git so go ahead and clone the repo like this: 
    git clone git://github.com/example-user/example-patch.git

    This will create a new folder in your home named example-patch (ie the name of the patch) and the actual patch will be a subfolder of that. You will need to know the name of this subfolder. This info will be on the GitHub page, or you can just browse the local folder itself.

  3. Same as for a normal patch (above), you can patch an ISO (1 - below) or directly to the installed system (2 - below - generally not advisable, but theoretically possible - YMMV). So armed with the name of the sub-folder inside the GitHub repo you just cloned and assuming you are back in your home folder ('~') (and if using method 1, you have the relevant ISO downloaded there too) patching is as simple as: 
    1. tklpatch example-appliance.iso example-patch/subfolder

      OR

    2. tklpatch-apply / example-patch/subfolder

Applying a patch to an OVZ template (rather than ISO)

Ideally TKLPatch could be extended to include other image formats as targets for patching (ie not just ISOs). Currently that is not the case though. In the meantime, it's relatively easy to patch an OVZ template and the process is somewhat similar to above. Applying the patch to the running template is per normal (above) - this is to apply a patch to a template prior to launch.

All prior steps are same as above other than the application of the patch to the template. Obviously you'll need the relevant template (and patch) downloaded to your working directory. Then untar the template, apply the patch and re tar it. Like this:

mkdir template-temp-folder
tar xfz tkl-ovz.template.tar.gz -C template-temp-folder/
tklpatch-apply template-temp-folder/ tklpatch.tar.gz #or tklpatch-dir/
cd template-temp-folder
tar cfz template-patched.tar.gz *

If all went smoothly you now have a patched OVZ template (template-patched.tar.gz)