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...
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
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...

Jeremy Davis's picture

It will really depend on which version you have and what your desired outcome is.

It's worth noting that often using TKLBAM to migrate data to newer versions can still require manual intervention when there have been significant changes between versions. We try to minimise those changes between minor version updates, but it's not always possible.

We made some significant changes in v14.2. Namely we replaced SambaDav (webUI for interacting with the Samba files) with WebDAV CGI. We also replaced the rTorrent/ruTorrent client setup with Transmission. The update to v15.0 was a major OS update, but the installed components remain the same (just newer versions).

So if you have v14.2, then you should be able to use TKLBAM to migrate your data and settings and I would expect it to "just work". Although there may still be tweaks required.

If you are using an earlier v14.x, then how you wish to proceed will depend on what outcome you are looking for.

If you are ok with SambaDav and rTorrent/ruTorrent, then I suggest doing an "inplace" Debian upgrade. I.e. do a dist-upgrade on your current server and update the base OS to the current Debian Stretch (what v15.x is based on). You should find plenty of info on doing that via a search for something like "upgrade debian jessie to debian stretch" (or similar). If you wish to upgrade SambaDav and/or rTorrent/ruTorrent you will need to do that manually yourself afterwards. However, if you choose the "Debian upgrade" option, I would urge you to make sure that you have an "snapshot" or some other sort of image of your server, just in case things go pear-shaped (unlike restoring TKLBAM, you do not have the opportunity to "roll back"). FWIW, you can do an "inplace" Debian upgrade for v14.2 too if you wish...

If you wish to use TKLBAM to migrate your data from v14.0/v14.1 to the v15.x appliance, then you will almost certainly want to do a staged restore of data (i.e. restore specific files/directories, rather than doing a default complete restore). We don't actually have a v15.x specific page that covers that, but most of the general points and advice covered in our TKLBAM - Migrate to v14.x doc page still applies to migrating to v15.x. (I really need to update that page and/or create a new v15.x version of it).

Either way, if you want a hand, I suggest that you start a new thread in the forums. You will need a (free) website user account and be logged in to start a new thread. I generally try to respond at least daily (on work days anyway), but sometimes more often. It's also worth being aware that if I'm particularly snowed under with important tasks that I can also be a little slower to respond (but at least once per week, usually much more often). If you don't get a timely response, please feel free to bump your thread (many forums don't like that, but we don't mind).