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 (quite dated, but still quite relevant).

Package-level upgrades

As hopefully you are already aware, TurnKey Linux appliances based on "Debian stable". Please see "TurnKey version < - > Debian version matrix" for info on which Debian release each TurnKey appliance version is based on.

Because of the Debian Security Team's attention to detail and collaboration with third parties (mainly other Linux distro maintainers such as Ubuntu, SUSE and Red Hat, as well as upstream software providers) Debian security updates include the minimal possible changes. They patch the specific security issue and nothing else. As such, we believe that they are safe enough to auto install and TurnKey servers come preconfigured to automatically check for, and when relevant, install any security updates daily.

Generally non-security related package updates can be safely installed too. However, as there is greater risk that behavior may change in updated (bugfixed) software, they are not auto installed by default. It's uncommon in simple websites, but in complex web apps, some functionality may even be dependent on software behavior that others consider a bug! It's relevant to note here that the "stable" in "Debian stable" doesn't suggest system stability (although IMO it could). Instead it denotes ABI/API stability - i.e. the functionality of software (and the way separate pieces of software interact with one another) should not change too much during the lifetime of the release.

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

apt update
apt upgrade

The result is a system that has the latest package versions available in the base distribution (e.g., Debian 11/Bullseye). 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, NodeJS, etc).

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 Rails appliance is based on Phusion Passenger - previously we used mongrel). As much as possible we try not to make radical changes to the way an appliance is generated between major versions. However, that is not always possible.

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 (it is a quite dated, but the general approach remains relevant).

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.

Technically you (probably) still can do an in place "Debian style" upgrade to a newer stable Debian release. E.g. upgrade v16.x (which has a Debian 10/Buster base) -> Debian 11/Bullseye. However, that won't get you to the newest TurnKey major version (v17.x in my example). It will instead be a hybrid between TurnKey v16.x and Debian 11/Bullseye (i.e. v16.x TurnKey, but with an updated base OS). That is because a lot of our tweaks are done at build time. When we release a new major version, we update our tweaks to be compatible with the new Debian version (sometimes add new tweaks, sometimes remove old redundant tweaks).

Whilst we don't officially support in place upgrades, we don't make changes explicitly to make that hard and I'm not currently aware of any specific issues related to any appliances (although I suspect that there may be). So while we don't recommend it, it should certainly be possible. And even though we don't officially support it, we will provide "best effort" support via the forums to anyone attempting an in place upgrade.

Rather than trying to upgrade in-place though, 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, although 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...