How to upgrade an appliance

Before you start, we recommend you backup your system, so you can go back if anything goes wrong. If your server is running in a virtual environment (i.e. not on bare metal) and your platform supports it, a "snapshot" is a good idea as well. Both are recommended when possible. A "proper" backup is good for transferring your data to a fresh server (of the same version) to completely start again, but can also be used to "wind back" changes. A snapshot is particularly useful to "wind back" to a known good state if you completely break your server.

Also if you are looking to use TKLBAM to migrate your data to a new version of TurnKey, please also see this page (very dated, but still somewhat 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.

Users who are unfamiliar with "stable" Linux distros such as Debian often find it a bit "weird" that software versions aren't updated to the latest version after "apt upgrade" is run. The reason for that is that when a new Debian major version release occurs, the version of all included software is "frozen". Further details of the pros and cons can be discussed elsewhere, but it's worth noting that this version paradigm is particularly useful for servers as it minimizes the need for maintenance and the OS should continue to run the same as the day it was first installed and configured.

The Debian Security Team address security issues with updates of the same software version, but the minimal possible changes addressing the specific issue. Often the security patches are developed in consultation with third parties - mainly other stable Linux distro maintainers such as Ubuntu, SUSE and Red Hat, as well as upstream software providers. Dues to the Security Team's attention to detail, 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.

Security issues - and some more serious bugs - are resolved by applying the smallest possible amount of changes possible. So rather than being a new version from the software developers (aka "upstream") it's the same "frozen" version, but with the relevant fix applied. While this means that new features aren't available, it also means that new bugs, issues and security vulnerabilities are also not included. For the life of the OS, users can rely on the system to more-or-less function exactly the same as it did the day it was first installed - but also remain secure.

Non-security package updates are developed in the same context, and can almost always be safely installed too. However they do not receive the same level of scrutiny that security updates do. Actual breakage is very rare, but there is a (very) small risk that a regression may occur or some software behavior may change - which may or may not have a material impact on your server. Because of that, they are not installed by default and it is recommended that general package updates are done under supervision so any issues can be addressed immediately.

So we do not install them by default and recommend that they are done under supervision. Then if there are any issues, they can be resolved ASAP. It's uncommon in simple websites, but in complex web apps, some functionality may 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. Essentially the functionality of software and the way separate pieces of software interact with one another. I.e. "stable" means that the way/s that you use software 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 12/Bookworm). 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, NodeJS, etc).

Please be aware that because the software version in TurnKey/Debian may be relatively old, sometimes specific software might be flagged as "insecure", "EOL" (end of life) or similar. So long as the OS itself is still supported and all available security updates have been applied (which happens daily by default on TurnKey) these warnings can be safely ignored.

The exception to that when third party software installed from source may require a specific version that is not provided by the OS. If the "frozen" version included in a newer OS release can fulfill those requirements, then that is often the best path forward - so please see below. In other cases, it may be more appropriate, easier and/or required to install software from some other source and/or using some other method. Due to the vast array of possibilities those will not be covered further here.

Finally, note that while we try to keep appliances as consistent as possible within a major version release, that is not always possible. Newer Turnkey minor versions of a specific appliance may include changes to configuration and even some specific software. So while installing apt updates will make the current version of the underlying OS (e.g. v18.0) "up to date" - it some cases, it may not be equivalent to the newer TurnKey release (e.g. v18.1).

Upgrading to a newer appliance version

If where relevant, you are keeping the pre-installed upstream software up to date, because of the Deian support timelines, there is no reason why you can't keep using your server appliance for an extended period of time. However, there will always come a time when a major update is required.

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. The TKLBAM documentation notes what you should be able to expect from TKLBAM. See also suggested workflow and some v14.x specific tweaks (it is a quite dated, but the general approach remains relevant for major data migrations).

If you work your way though it, please post the steps you took on the forums. That will help others and assist Turnkey to understand how the process can be made smoother going forward. If you get stuck and/or are feeling over your head, please check out the support options.

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. We encourage users to customize their servers to completely fit their needs but that makes "in place" upgrade potentially problematic. It is impossible to anticipate all the possible ways in which an appliance has changed since installation. That may make it problematic, even dangerous for automated configuration updates - as a Debian "in place" upgrade will. Rather than trying to upgrade in-place, we believe that a technically safer solution is to separate the system from the data it works. Hence why our backup and migration mechanism - TKLBAM - exists.

Regardless, we don;t want to limit user options and/or their use of TurnKey Linux. And at least technically, it should still be possible to do an in place "Debian style" upgrade to a newer stable Debian release. E.g. upgrade v17.x (Debian 11/Bullseye base) -> Debian 12/Bookworm base. However, the update won't that won't give you a true newer TurnKey major version (v18.x in my example). It will instead be a hybrid between TurnKey v17.x and Debian 12/Bookworm - i.e. v17.x TurnKey, but with an updated base Debian OS. That is because a lot of our tweaks and security hardening 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). Our custom packaged software will be updated though (via apt).

Whilst we don't officially support in place upgrades, we don't make changes 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. If you intend to do an "in place" upgrade, please check the general Debian upgrade info as well as the Debian version specific upgrade documentation (link to "oldstable" to "stable" upgrade docs - adjust as neccessary).

Note that a Debian "in place" upgrade can only be done between consecutive Debian versions - you can not skip any versions.

Also you will need to manually download the relevant newer TurnKey apt key before you will be able to install the newer TurnKey custom software packages.