TurnKey Linux Virtual Appliance Library

How to upgrade app XYZ in my TKL appliance [for Linux newbs]

...work in progress... I originally set out to make this simple and easy to read for newbs but it's got much more full on than intended... Feedback welcome.

For info on installing apps via package management (ie apt) please see here.

This is a tricky question that will probably require a specific answer for each individual app you wish to install or upgrade/update. Unfortunately that is beyond the scope of this 'how-to' and will require additional work on your part. You may be lucky and find a manual install or upgrade/update path has been documented by a previous TKL community member (try searching the forums - top right corner) if not, please keep reading. This page includes an explanation of the main ways apps are installed by TKL core devs, a rationale of why they did it that way, and what general steps you may need to take to install or upgrade/update the indivdual app in your TKL appliance.

Before you start

I highly recommend you start with the current TKL appliance version (v11.3 as at the time of writing). I also strongly recommend that you closely document each step as you go. It makes it easier to troubleshoot if you don't immediately get the desired results. Also when you are done, you can share your completed step-by-step documentation with the community - as all good open source citizens should! :)

For users with no current appliance with existing data, skip straight to the next heading. If you have current data in an appliance and if you aren't using at least v11.x, I strongly suggest you take care of that first. Then do a full backup (TKLBAM works well for me) and do a test restore to a clean install (VMs are handy for tasks such as this).

Some apps may require you to manually migrate the data when updating/upgrading versions. This will more often be the case when doing major version updates - please check the relevant app's documentation (hopefully it will be on their website). I suggest you do a test run of the upgrade on this VM prior to your main instance.

Worst case scenario, you can use your TKLBAM backup to start again from scratch, without damaging your currently running instance.

The main ways apps are installed

The main ways that the core TKL devs install apps when making appliances are:

  • Package management, or
  • Upstream archives (often referred to as 'tarballs'). Strictly speaking tarballs are only ever tar.gz (or tar.bz2) archives but sometimes upstream developers package as zip files instead (which technically aren't tarballs). For the purposes of this documentation tarballs refers to any upstream provided app archive.
  • Other upstream source code. AFAIK TKL devs don't generally install anything from upstream version control repos (eg SVN/Git/Mercurial/etc) and/or manually compiled source code as these are often not stable. Although I have noticed that increasingly some developers choose to also provide stable branches via this means (so I chose to include it).

Package management (official repo)

These apps are installed using the apt-get install <packagename> command and (generally) will come from the official Ubuntu repositories. Generally these packages are kept at the same major version as at time of release (ie April 2010 in the case of Ubuntu 10.04 - the basis of TKL v11.x). For further info on using apt see here.

To add to the confusion there is also an official, but not officially supported Ubuntu repo called 'universe'. The packages in this repo are not guaranteed security updates (although they may receive community provided patches and there are some exceptions such as MediaWiki). There is also another official Ubuntu repo called 'backports' (which again is not officially supported) which contains newer/updated versions of software than what shipped originally. Whilst this may seem like a happy medium, in my experience there is rarely anything much of interest in there but YMMV.

Pros

Despite the fact that major versions of these apps is not updated, it does not mean that they are not updated at all. Generally all security related bugs are backported (and occasionally other serious bug fixes too) - to apps in the 'main' repo anyway (the updates appear in 'security'). These will be auto applied via TKL's automated security update mechanism.

This process of install and update/upgrade maximises security and stability and minimises risk of unexpected problems occuring. It also minimises maintenance overheads, leading to increased productivity. The risks of data being corrupted or downtime for your appliance are very limited (although obviously it's still best to keep regular backups - just in case).

So unless there is a genuine need for the latest version (eg a 'show-stopper' bug or a needed feature) it is generally preferable to leave these apps as they are. Windows users new to Linux may find this is contrary to their usual process of always upgrading to the 'latest and greatest' version of software but in many scenarios it really is better!

Cons

The downside is that new features are almost never added and minor bugs (and sometimes even major ones) are not addressed (until the next major version of TKL - where the app version number will often jump considerably). Also simplistic security auditing software (which just checks on software version numbers) will often falsely list apps as being 'unsecure' and having vulnerabilities when in fact they have been patched - ie false positives.

Also sometimes apps installed like this can be a little confusing for ex Windows Linux newbs as instead of everything being in the same place (eg in a subfolder of the web root) they can be spread out in a few different places through the Linux filesystem (eg usually config files will be found in /etc/<appname>). TKL tries to mitigate this by providing symlinks to where the data is.

Package management (third party repo)

AFAIK TKL devs don't currently provide any appliances that contain apps from third party repos. When available it can be a good way to go if a third party provides a repo that includes a compatible app.

Sometimes you will be lucky enough that the upstream devs of the desired app provide their own repo. This repo may be hosted on their own website, or perhaps somewhere like a PPA (Personal Package Archive) on LaunchPad. Sometimes you may find a third party (ie someone not involved with the upstream devs) will produce their own repo (more likely to be a PPA, but may not be). Personally i have generally had good results with LaunchPad but it can be hit and miss.

Pros

Third party repos are usually updated much more often than official repos (although that depends on the third party). Official repos (PPAs or otherwise) are generally secure and trustworthy and (generally) provide minimum fuss for updating apps. IMO these can often be even better than the official Ubuntu repos.

Cons

If they are unofficial, third party repos can be of unknown quality and trustworthiness. You have no real way of knowing when or if they may again be updated.

Upstream tarballs (and other source)

As suggested above, upstream tarballs are archives containing all the files required for installing the app. These are provided directly by the upstream developer. These are quite often generic in nature but will usually have some sort of minimum requirement. Webapps (ie apps that run on a webserver eg MediaWiki) are very commonly provided like this. Before you even consider upgrading to an upstream tarball you will want to double check that everything it requires can be easily satisfied by Ubuntu 10.04 (in my experience this is generally the case with mainstream apps although YMMV). If you are upgrading an existing TKL appliance that uses an app from package management, you will probably need to remove it. In some cases it may even be preferable to start with a vanilla LAMP installation (rather than update an existing appliance).

Pros

Upstream tarballs will always have the latest version of software and will include all the latest features (as well as all the latest bugs :p). Often upstream developers will have 2 branches: stable (this will be the one you want for production) and development (this may contain some cool new cutting edge features but also may be unfinished and/or contain bugs). This is especially relevant if they provide their source via a version control repo (such as SVN or Git, etc).

Cons

Once you go for an upstream version you will need to manually apply all future updates as they are released. So whilst the idea of having the 'latest and greatest' may be appealing you also need to consider the increased maintenance costs and security risks (if security bugs are not manually addressed quickly as they arise). For a small site, with little important data and a good backup regime, an increased security risk and a bit of extra maintenance using an upstream source may be a no brainer. Especially if there are show-stopper bugs and/or needed new features that don't occur in the pre-packed version (or when there isn't one!).

As stated above, unless you have good reason, you are better off sticking with the version from the official Ubuntu repos.

Where do TKL devs install from and why?

When the TKL core devs release an appliance they take these above factors into consideration and decide whether to include the pre-packaged version (where available) or the upstream version. For example in appliances such as MediaWiki, the devs decided that the pre-packaged version is adequite and so left it at that. With Moodle, the devs decided to install from upstream as the pre-packaged version (v1.9) had some pretty serious bugs, and the new upstream version (v2.0) has some strong new features (besides Moodle is only available in the 'universe' repos - see other considerations below for explanation). In some other cases (such as Redmine IIRC) the pre-packaged version is just so old and missing so many features that there isn't much choice but to use upstream. Somethings, like Joomla are just not available via Ubuntu so the only way to offer them is to use upstream.