TurnKey Linux Virtual Appliance Library

How to upgrade an appliance

Before you start, we recommend you backup your system, so you can go back if anything goes wrong.

Package-level upgrades

TurnKey Linux appliances are configured by default to automatically install the latest security updates. Non-security package updates are not automatically installed, because there is always the risk that a new version of a package will somehow break existing functionality.

Since a TurnKey Linux appliance is pretty much a standard Ubuntu system under the hood it can be updated at the package-level just like any other Ubuntu or Debian based system:

apt-get update
apt-get dist-upgrade

The result is a system that has the latest package versions available in the base distribution (e.g., Ubuntu Hardy). Keep in mind that some appliances may include components that can not be managed through the APT package management system and may need to be upgraded by other means (e.g., Ruby gems).

Note that upgrading packages to the latest versions is not exactly equivalent to upgrading to a new version of an appliance because a new appliance may include a different configuration of components (e.g., the new Rails appliance is based on Phusion Passenger and not mongrel).

Upgrading to a newer appliance version

The recommended way to upgrade to a newer appliance version is to use TKLBAM to migrate your data and configurations from the old appliance to a fresh installation of a new version of the same appliance. See the TKLBAM documentation for details.

Why you can't upgrade in-place to a newer version of an appliance

Users often ask for an easy way to upgrade one appliance version to a newer appliance version in-place. This is technically problematic because we don't want to prevent users from customizing an appliance to fit their needs. TurnKey just give users a better starting point by pre-integrating the best selection of components. Since it's impossible to anticipate all the possible ways in which an appliance has changed since installation it's dangerous to try and change the configuration automatically in place.

Rather than trying to upgrade in-place, a technically safer solution is to separate the system from the data it works on and then provide a backup and migration mechanism so users that are interested can move their data from one appliance version to another and re-apply any tweaks they made to the old system, if necessary.


Christian Peper's picture

Upgrade to a new turnkey mw

It is important to realize that migrating to a new mediawiki is more difficult than making a MySQL backup and restoring it. This only works for the same mw version and omits all your images!

In order to migrate to a new mw version, from Turnkey or anyone else, use the dumpBackup.php in the maintenance section of your mw. I use the following command:

php dumpBackup.php --current --report=100 --output=bzip2:wikidump_<hostname>.xml.bz2

Next, backup all your images in the images directory of your mw:

tar cjf wikiimages_<hostname>.tar.bz2 *

Then, on your new mw server, import the XML content using dumpImport.php and restore the images in your new images directory.

Finally, run the rebuildall.php script from the maintenance section, to set everything right again. If you delete the thumbnails and choose your image manipulation program (i.e. GD2 or ImageMagick), that will also regenerated all those.


This says nothing about your plugins, extension and customizations made to your LocalSettings.php script! You'll have to do that in addition to the above. And beware that syntax and options may have changed from one mw version to the next. So simply copying your old LocalSettings and overwriting the new one may do damage!

Inveneo's picture

What about a Size Upgrade?

Is it possible to upgrade a server from, say, a micro to small machine?

Or, would I need to setup a new server and then manually migate my apps/content/etc. over?  Can this be done via the backup/restore mechanism (i.e. between two servers that are of different sizes)?


Liraz Siri's picture

Use snapshots to change EC2 instance sizes

The easiest way to do an EC2 size upgrade (or downgrade) is to create a snapshot of your instance and then restore the snapshot to a larger instance. EC2 size upgrades are bit off topic and this was answered on the forums but in case anyone runs into this here...
Guest's picture

Upgrading Linux Version

Hi, I wish to upgrade to from Debian 6 to Debian 7. I run apt-get update and apt-get dist-upgrade sucessfully, but is shows still being on Debian 6. Did it upgrad to 7?

I have seen other sites with more steps that changes the soruces.lists file, but that breaks the initail TurnKey menu and I suspect other things. I don't care if it reports version 6 if it is really 7.



Liraz Siri's picture

Use lsb_release to check Debian version

After you upgrade via apt-get the reported Debian version in the menu may not be correct. To check use lsb_release:
$ lsb_release -da
Distributor ID:	Debian
Description:	Debian GNU/Linux 8.1 (jessie)
Release:	8.2
Codename:	jessie