How to Upgrade a TurnKey Appliance to a Newer Version Without Using the Cloud
Upgrading a TurnKey appliance to a newer version can be done seamlessly using the TurnKey Backup and Migration (TKLBAM) tool. This guide will walk you through the process of upgrading your appliance locally, without using the cloud, based on the official TurnKey Linux instructions.
🛠️ Prerequisites:
- ✅ A working TurnKey appliance running.
- 🔐 Access to the TurnKey server via SSH.
- 💾 External storage to backup the appliance configuration.
- 🌐 An internet connection to fetch the necessary files.
📥 Step 1: Fetch the Base Profile
First, you need to fetch the base profile for your appliance. This profile will help ensure that your backup is compatible with the newer version of TurnKey Linux.
To do this, run the following command to download the base profile:
1
wget -O tklbam.conf https://raw.githubusercontent.com/turnkeylinux/tklbam-profiles/master/core
Next, visit the TurnKey Linux TKLBAM profiles repository and search for your specific appliance. Add any missing appliance-specific entries to the tklbam.conf file you just downloaded. This step ensures that your appliance configuration is included in the backup.
🧩 Step 2: Create the Profile
Now that you have the base profile and appliance-specific entries, you need to create a profile using the tklbam tool. Use the following command to create the profile:
1
tklbam internal create-profile --no-packages profile/ tklbam.conf
This command creates the necessary profile for your appliance, which will be used later to back up and restore your system configuration.
🔧 Step 3: Initialize the Profile
Next, initialize the profile with the tklbam-init command. This step prepares your system for backup and ensures that the configuration is set to the appropriate profile.
1
tklbam-init --solo --force-profile=profile
💽 Step 4: Backup the Profile to External Storage
It’s always a good idea to have a backup before proceeding with any upgrades. Backup your profile to an external storage device (e.g., NAS) using the following commands:
1
cp -r profile/ /srv/backup/ && cp -r tklbam.conf /srv/backup/
This command copies both the profile directory and the tklbam.conf configuration file to your external storage.
🗃️ Step 5: Create a Dump
Now that you have backed up your profile, it’s time to create a full backup dump of your appliance configuration. This dump will allow you to restore your configuration after the upgrade. Run the following command:
1
tklbam-backup --dump=/srv/backup/dump
This creates a backup dump of your system that will be stored on the external storage at the path /srv/backup/dump.
📦 Step 6: Install the New Appliance
Now that you’ve backed up your appliance configuration, the next step is to install the new version of the appliance. This process may involve downloading a new TurnKey appliance image and setting it up within Proxmox. Refer to TurnKey’s official documentation for the specific installation steps of your appliance version.
♻️ Step 7: Restore the Configuration from the Dump
After installing the new version of the appliance, you need to restore your configuration from the dump you created earlier. To restore the backup, use the following command:
1
tklbam-restore /srv/backup/dump
This command restores your appliance configuration, including all files and settings, to the new version. After rebooting the appliance it should work as before the upgrade!
🧠 Final Thoughts
By following these steps, you can easily upgrade a TurnKey appliance running in Proxmox to a newer version without using the cloud. The key to a smooth migration is backing up your appliance configuration using TKLBAM and then restoring it after installing the new appliance version. This ensures that your settings and data are preserved during the upgrade process.
For any issues or questions, consult the official TurnKey Linux documentation or reach out to the TurnKey community for support.