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.

Comments

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.

NOTE:

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)?

Thanks!


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.

Thanks,

Ken
 

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?

 

cheera

Paul

 

Jenno Verdonck's picture

I want to upgrade my turnkey torrent/fileserver to version 15.x from version 14.x Are there any specific tweaks needed or can i just use tklbam without extra tweaks?
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).