How to upgrade an appliance

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

Also if you are looking to use TKLBAM to migrate your data to a new version of TurnKey, please also see this page.

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. See also suggested workflow and some v14.x specific tweaks.

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. Most user config tweaks should be included in the backup, althouhg some manual tweaks may be required between versions.


Christian Peper's picture

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

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

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...
Ken's picture

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

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
Nobody's picture

If the user makes changes to their appliance, they also need to redo them in the new appliance.  Whereas if the use is a decent sysop (or a noob researching the correct linux way) and the upgrade process is also done properly, chances are high everything will be fine.

It sounds more like an excuse to force people to pay for TKLBAM and amazon storage.  :(

Jeremy Davis's picture

TurnKey is not forcing anyone to do anything. TurnKey Linux is completely free open source and is built on top of Debian stable. You are free to do what you like with it.

Whilst we developed TKLBAM to make life easier, you are not compelled to use it or any other TurnKey service. Besides, TKLBAM supports a ton of backend storage (other than AWS S3) so you don't even need to use it with the Hub if you don't want to.

OTOH for TurnKey to be sustainable and survive for the long term, we need to cover our costs somehow. We don't think it's unreasonable that we charge a small fee for the convenience of everything working really easily. If you disagree, please feel free to use whatever method you desire to backup and migrate your data.

PS most likely your appliance changes would be included in your backup, so would be included when you restore to a new server. If you test restoring your backups (as you should in any robust backup regime regardless of what backup tools you use) and your tweaks aren't included, then you can adjust TKLBAM to ensure that they are.

PPS Also we often provide tweaks and improvements in our new releases. Some of these are packaged (in our custom software) so will get applied by a system upgrade (as you recommend). But many are handled by overlayed files and scripts that run at build time. So bottom line is that a new TurnKey release isn't just the old release with newer packages...

Paul Hamilton's picture

Hi There,


Am I seeing things....    dnsutils seems to be missing from the version of LAMP that I have.  Which is a bit annoying as it is needed for apt-get....  

Have I done something stupid?