install upgrade
This is the upgrade guide for Melody.
Upgrade is similar to installation, except that backups of all data should created, and database and config files don't have to be created from scratch.
Important: Movable Type users and Melody 0.9.x alpha users should first consult the Movable Type and Melody 0.9.x Upgrade Instructions.
Here's the basic process:
- Backup - The most important part of upgrading
- Install New Version
- Configure New Version
- Upgrade Database
- Install Plugins - critical if publishing requires plugins, otherwise optional.
This guide assumes that you have FTP, shell, or some other form of access to the server.
Throughout this guide two terms are commonly used:
-
$MT_HOMEis used to refer to the application directory -
$MT_STATICis used to refer to the static directory
Some plugins come bundled with Melody. But there are many plugins available from third-party developers which extend the functionality of Melody. These plugins may or may not work with the version of Melody you are using and it is ultimately your responsibility to confirm that by upgrading you won't break those plugins. If however you encounter a plugin that is not compatible with Melody, please let the community know. If it is open source someone may help you make the changes necessary to restore its operability.
The Perl Modules section of the System Requirements page lists which are required. After installing the new Melody application files on the server the check.cgi script can be used to test if necessary Perl Modules are installed. (This step is listed after Configure New Version below.)
When upgrading, the same database is typically used with the new version as well. After upgrading to the new version of Melody, you'll access Melody and an upgrade script will automatically update your database to the latest schema.
The Melody community currently focuses its primary development activities around MySQL. There are however a number of community-driven projects to support for Postgres and SQLite.
If you are using SQLite or PostgreSQL learn how to [migrate your SQLite or PostgreSQL database to MySQL](SQLite or PostgreSQL) if you choose to do so.
Two upgrade strategies when it comes to database:
- backup the current database, and proceed with the current database.
- populate a new database with the backup of the existing database.
Tip: The benefit of the second option is that the existing database and Melody application can be left in parallel with the new install and new database which makes reverting easy if necessary.
The database credentials can be found in the `config.cgi file.
If using a new database (assuming it's a MySQL database) have the following three items ready:
- database name
- database user
- database user password
Warning: This is the most important part of upgrading.
Backups should be created on a regular basis regardless of whether performing an upgrade or installing plugins that effect the database. Should data be lost due to any reason, a recently-created full backup will make it easy to revert to a previous state. Determine how many hours or days of work you can afford to lose, this amount of time should be your backup interval.
Note: Optionally, use the Backup and Restore functionality in Melody to move data between installations of Melody. This is optional because backing up the database and directories as described below covers is a more comprehensive backup strategy.
See the File System page for more info about these directories.
- application directory
mt-staticdirectory- website directories - If Melody is publishing multiple blogs or websites, backup the root directory containing all the files being published.
Duplicate the directories to backup (via FTP program or command line) on the server or download a backup.
Tip: If possible create a compressed archive of on the server first (zip, tar.gz, etc.). Via command line, use the zip command to recursively compress all the files and directories in a sub-directory of the current directory into a zip archive:
zip -r sub-directory-name.zip sub-directory-name
The database is where all the non-file content and settings are stored. Read more about backing up a MySQL datatbase. (Find the database name, user, and password in the config.cgi file.)
If not using MySQL refer to migrating to MySQL from SQLite or PostgreSQL.
Now that all the data is backed up we're ready to install the new version of Melody.
Because installation of the new version during upgrade is essentially the same as during initial installation, please refer to the Install New Version section of the Detailed Step-by-Step Installation Guide. (Simpler installation guides are also available: Install via FTP or Install via SSH.)
Because this will be the second (or more) version of Melody being installed, there a couple strategies for installation location:
-
If installing the new version of Melody into the current directory, simply copy the new files over the old ones. Melody is structured such that doing so runs no risk of colliding with any plugins or themes you have installed yourself.
-
If multiple application directories are installed:
cgi-bin/ Melody-1.0 Melody-1.1They can each be accessed separately:
http://domain.com/cgi-bin/Melody-1.0/index.cgi http://domain.com/cgi-bin/Melody-1.1/index.cgiInstalling these directories side-by-side allows for easily switching back or referring to a previously installed version of Melody if necessary.
Tip: a symlink can be created to point "melody" to the current application directory in the
cgi-binso that Melody can be accessed without the version number in the URL:.$ ln -s Melody-1.0 melodyRead more about Symlinking to the Application Directory
Confirm that file permissions have been set correctly.
Copy the contents of the old $MT_HOME/mt-static/support directory into the new mt-static/support directory.
If permissions have changed since these files were backed up ensure that file permissions are set correctly.
Take the config.cgi file from the application directory of the previous installation and copy it to the new installation's application directory.
If using a new database, change the database config directives to access the new database, however this is an unlikely step in a typical upgrade.
Note: Optionally, confirm proper installation that Melody is installed properly by accessing the
check.cgiscript. Should be a url similar to this:http://domain.com/cgi-bin/Melody-1.0/check.cgiThe message "Melody System Check Successful" will appear at the bottom of the screen if the server has all the necessary libraries/modules for installing Melody.
If the system check fails to complete, then the missing Perl libraries/modules must be installed before continuing.
At this point all the files for the Melody application have been installed and configured.
Logging into the new Melody version will trigger the upgrade script. If the database schema has changed between the old and new versions, this script will move data around in the database to match the new schema.
Login to the Melody install:
http://www.domain.com/cgi-bin/melody/index.cgi
If there is an error, double-check that the steps above have been completed.
Note: The database upgrade process may not run to completion on sites that have extremely large databases. For tips about how to manage that problem, see the next section.
Melody will make a lot of changes to your database schema to introduce performance enhancements and support for new features. For really large databases, say for databases with several hundred thousand comments for example, this process may take several minutes. Therefore users that feel that they have large database are encouraged to run the command-line upgrade tool.
To execute this tool, run the following commands from the command line while your working directory is the application directory:
perl ./tools/upgrade
Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.
- Author: Dan Wolfgang
- Edited by: Byrne Reese, Violet Bliss Dietz