If you have strange things happen after migrating from an earlier version of TKL to v14.x then please post on the support forums and someone will be along to try to help ASAP. Also if you are a Hub user (or AWS Marketplace subscriber) then please also feel free to try our support portal (accessible when logged into the Hub).
Suggested migration workflowIt is suggested that you migrate from older (pre v14.x) versions of TurnKey in a staged process, something like this:
- Note the specific points as detailed towards the bottom of this page.
- Audit restored data in new server - check what is working and what isn't.
- Resolve issues noted in your audit, documenting as you go.
- Do the final migration.
1. Initial restore and auditIt is recommended that you do not touch your production server (where your backup comes from) until the migration is complete and you are 100% satisfied.
First check that your latest backup is fairly recent. Anytime within the last month (or so) should be adequate for now (although ideally you should be doing daily backups). Then restore your data to a test server and do a full audit. Take careful note of what is working and what isn't. Once you have the audit complete, take some time to do some research on anything you are unfamiliar with.
When searching for documentation/hints on specific issues, generally Google is your friend. Keep in mind that under the hood TurnKey is built on Debian, so generally stuff that applies to Debian, also applies to TurnKey.
When software is installed from upstream (e.g. TurnKey installs WordPress directly from WordPress themselves) it is highly recommended to consult their documentation too.
2. Work through issues found during audit
Consider this initial run purely a test. That way you can be fearless in your your tweaking. If you make something worse, or things get messy (e.g. trial and error without clean resolution) then you can just trash your test server and start again with a fresh restore.
Make sure you document everything you do; especially things that work. Try to focus on one problem at a time and keep working until each solution is complete. If you end up starting a fresh, any issues you have already completely resolved, don't need to be reapplied at this point. Any issues you have partially resolved, can be redone using your docs as reference.
3. Final migration
You've worked through all issues uncovered in your audit and documented their resolution. Back on your production server, where relevant and possible; put it in "maintenance mode" or otherwise lock it (so no new content is added). Then run a final backup.
Restore your new backup to a fresh new server. Take it out of "maintenance mode" (etc). Follow your docs to complete the migration so everything is working well.
Once you are 100% happy, then do any final tweaks (e.g. configure DNS to map to the new machine etc) to put it into production and do a backup of your new migrated server.
When you are ready you can destroy the old server. Note that some like to leave the old server running for a little while, just in case. Also it is recommended that before you destroy the server; within the Hub set "max backups" to 1 and force a final full backup. That will clear all the previous backups and leave you with a final legacy backup for archive/historical purposes.
Special notes for very old migrations
Some users have reported that when migrating from very old versions (e.g. v11.x) that the restored server will not boot. In cases such as that you may need to manually migrate your data. However TKLBAM can still be useful as a way of transferring your data to the new server. Instead of doing a full restore, just do a download:
You can then manually transfer the files to where they need to go in the filesystem. The downloaded files should be in locations which are relative to the download directory. E.g. files that come from /var/www should be found in /path/to/dump/files/var/www
You'll still need to decide what to move and what not to, but it will make life a little easier.
Webmin (all appliances)As of v14.0 Webmin is now hidden behind stunnel. This means that if you restore from an earlier version you'll need to make some changes before Webmin will work again. In the Webmin server config file (/etc/webmin/miniserv.conf) make sure that you have these entries (add them or change them as appropriate):
port=10000 ssl= listen=10000 inetd_ssl=1 bind=127.0.0.1 sockets= no_resolv_myname=0 ipv6=0Also double check that stunnel config (/etc/stunnel/stunnel.conf) has this (most likely right at the end):
[webmin] accept = 12321 connect = 127.0.0.1:10000If you have configured SSL certificates for Webmin (and/or Webshell), then you will most likely also need to configure stunnel to use them instead. E.g. adjust the lines in /etc/stunnel/stunnel.conf that says this:
cert = /etc/ssl/private/cert.pem
Apache (inc LAMP and about 70% of the library)Apache config has had some significant changes, although the one that will break things is actually TurnKey related. We hardened the SSL in v14.0 and moved the default certificate location. We also included all the additional SSL/TLS config together (in /etc/apache2/mods-available/ssl.conf).
The easiest way to avoid the most significant issue, is to exclude Apache's ssl.conf file from your restore. You can do that like this:
If you have a third party CA cert then this should not affect you (although you can move your cert if you desire). If you are using self signed certs, then simply removing reference to the old cert from your Apache vhost site files (in /etc/apache2/sites-available) should do the trick. E.g. here is the update in action on the Trac appliance.
There are other changes too that should probably be made (although Apache should still work without them). See links below for more info.
MySQLNothing of significance should have changed with regard to MySQL so it expected that the majority of users will be fine. However, due to a bug in PHPMyAdmin, we have switched to the lighter weight MySQL web UI; Adminer.
Additionally (not sure if it's related or not) some users have reported that their MySQL root password does not work post restore. That can easily be reset by re-running the MySQL inithook: