Upgrading

Please note: as there have been changes both in the coppermine files and the database from previous versions to cpg1.5.x, users of older versions than cpg1.5.0 will have to apply all steps mentioned above: both the files have to be replaced and the update.php script has to be run once.

Steps needed to perform when upgrading Coppermine (from any version)

• Download the most recent stable version existing in the download section of the official Coppermine homepage
  (Don't assume that you have the most recent version, especially if you have installed Coppermine using a control panel app provided by your webhost. The coppermine dev team doesn't recommend using such auto-installers - please download the original from our site)
• Make a backup (dump) of your database
  (Recommended tools for creating a database dump are mySqlDumper or phpMyAdmin)
• Backup your include/config.inc.php file, your anycontent.php file and your "albums" directoy as a safety precaution if anything should go wrong.
  (Usually, you just download your entire coppermine folder to your local hard drive using your FTP app)
• Unpack the coppermine package you downloaded into a temporary folder on your local hard drive (preserving the folder structure within the package)
• Except for the "albums" directory, upload all of the new files and directories making sure not to overwrite your anycontent.php file or the albums directory.
• Run the file "update.php" in the coppermine directory once in your browser (e.g. http://yourdomain.tld/your_coppermine_folder/update.php). This will update your coppermine install by making all necessary changes in the database.
• If you have made a custom theme, apply the changes that were introduced in the themes structure to your custom-made theme - refer to the theme-upgrade guide.
• If your webserver is running in safe_mode and you have enabled "SILLY_SAFE_MODE" in include/config.inc.php, you will have to go to coppermine's config after performing above mentioned steps and enable "silly safe mode" there, as the setting in include/config.inc.php is no longer being taken into account in cpg1.5.x. The silly_safe_mode setting has been made into a config setting instead.

Additional actions for updating from particular versions

Depending on the version you're updating from, there are additional actions you need to perform:

Upgrading from version cpg1.0, cpg1.1, cpg1.2.x or cpg1.3.x to cpg1.5.x

Support for a direct upgrade from cpg1.0, cpg1.1, cpg1.2.x or cpg1.3.x to cpg1.5.x has been dropped - if you still have such an ancient version running, you will have to upgrade in a two-step-process (from your version to cpg1.4.x and then on to cpg1.5.x)

Upgrading from cpg1.4.x to version cpg1.5.x

• If you have made a custom theme, apply the changes that were introduced in the themes structure to your custom-made theme - refer to the theme-upgrade guide.
• You can not use language files from older versions of Coppermine as primary language (the language the admin will use) - make sure you only have the language files that come with this package inside of your lang folder (delete or rename all files from older versions within the lang folder).
  If you need to use a language that hasn't been translated for cpg1.5.x, you can try using the language file from cpg1.4.x, however there are certain caveats:
  • You need to enable the language fallback option in coppermine's config page if you want to use a language file from cpg1.4.x with cpg1.5.x
  • cpg1.5.x-phrases that don't exist in your old language file will go untranslated or show in english
  • Coppermine can't be administered using an old language file - the admin needs to use a "true" cpg1.5.x language file
  • You're free to try using old language files, however when running into issues or error messages, switch to US-English and see if the issue goes away then. Using outdated language files goes unsupported
  • In cpg1.3.x, the passwords for the users used to be stored in plain text inside the database. This has been changed in cpg1.4.x - out of the box, cpg1.4.x used to store the passwords encrypted. However, there used to be an option for those who upgraded from cpg1.3.x to cpg1.4.x to skip the step of encrypting the passwords. In cpg1.5.x, the plain-text storage of passwords is no longer an option. If you're running such an old gallery that first was updated from cpg1.3.x to cpg1.4.x and now on to cpg1.5.x, the updater will automatically encrypt all the passwords of your users (including your own admin account). You don't have to mind anything specifically - the updater will do this automatically.

The version check tool

Since the release of cpg1.3.2 Coppermine comes with an additional version checking tool to help you resolve issues with upgrades and updates easily. Except for specific files of coppermine that will only work for the version that it had been originally designed for, the versioncheck tool can be used with all versions starting from cpg1.2.1. To launch the versioncheck, simply add versioncheck.php to your browser's address bar after being logged into coppermine as admin (example: http://yourdomain.tld/your_coppermine_folder/versioncheck.php). With version 1.5.x, you can run the versioncheck utility from the Admin menu.

What it does

The script "versioncheck" is meant for two purposes:

• If you have upgraded from a previous version, you should perform versioncheck to see if your upgrade worked as expected
• Use versioncheck to make sure that your coppermine version is up-to-date

This script goes through the files on your webserver and tries to determine if the local file versions on your webserver are the identical to the ones at the repository of http://coppermine-gallery.net. Files that do not match are displayed and are the files you should update as well.

Compared to previous versions, the versioncheck page has been re-designed for cpg1.5.x both in terms of visuals as well as functionality.

First run

When run for the first time, you will see the option screen first. For a start, default options should be OK, so just submit the form. The script will then determine the coppermine version you're currently running, an try to look up the XML file on the coppermine repository that corresponds to your version. If successfull, it will compare all files that exist on your server against the most recent files that are recommended to use (trying to obtain that data from the repository). Subsequently, you should see a list of folders and files that are suppossed to exist on your server and an explanation if the file versions you have are the most recent. For details how to interpret the output, read on.

Options

There is a small number of options available on the versioncheck page that should be pretty self-explanatory:

• Display output
  Determines wether the full output with formatting is used, or only a reduced palin-text output
  • Full-screen
    Use this by default. It will display as much detail as possible and has a nicer layout
  • Text-only
    If a supporter asks you to post your versioncheck-output, switch to this options, so you can easily copy the output and paste it into your posting on the coppermine support board. Only do so if a supporter explicitely asks for it! Another potential use for the text-only output is resources-consumption: if you suffer from time-outs, try using the plain-text option, as it consumes slightly less resources.
• Only show potential errors
  If you have no idea what all the output is suppossed to mean or if a supporter asks for it, you might want to tick this option to only display the folders/files that have issues.
• Do not connect to the online repository
  If you check this option, the versioncheck script will not attempt to connect to the online repository and use the local XML file instead. Only use this option if connecting to the online repository doesn't work for you (e.g. if you're on an intranet and your server doesn't have internet access). The main drawback of not connecting to the online repository is the fact that you won't know about possible updates and most recent releases, so you better find the cause for your inability to connect to the online repository.

The options screen lets you configure the versioncheck, or rather what is being displayed. The options aren't saved anywhere, so you will have to adjust them each time you run versioncheck. The default options should be OK for most users - only change them if you have good reasons to do so.

Version comparison

There is a lot of information packed into a small space. Here's an example of a possible output and what the output means:

• Path
  The folder- and file name
• Missing
  If nothing is being displayed in this column, the folder/file exists on your server. If this is not the case (i.e. the folder/file does not exist on your server or is inaccessible), the column "Missing" will be populated with the result of this first, basic check.
  Note: there are some folders/files that are mandatory to have; others are optional. Anyway, if you perform a fresh install or upgrade, you should make sure to upload all folders/files. You can then later delete some of the optional files if you want, although this doesn't save much webspace.
  If a file is missing, all other steps that are next in the loop will not be performed - a missing file can't have a version number or similar. If versioncheck complains about missing files, use your FTP app to review if they are actually missing or inaccessible. If they are missing, re-upload them. If they are inaccessible, you will have to assign the needed permissions.
• Permissions
  Displays the permissions assigned to the folder/file. For some folders, write permissions are needed, while for others read permissions are enough. If the permission level of a folder is good, the result will be displayed together with a remark (in brackets) like "OK" (may differ in your language). Using a script like versioncheck to actually check permissions on folders works OK, while it may or may not work very well on files. This being said, you should mostly be concerned about folders that don't have sufficient permissions. If files are being reported to have an improper set of permissions assigned, don't be to alarmed if the rest of your gallery is working just fine.
  If permissions on folders need reviewing, read up the permissions section of the docs and do as suggested there.
• Version
  The version of the file on your server. If it is identical to the version indicated in the repository, you should see an "OK". If you're running an oudated version on your server you should get a fresh package and perform an upgrade.
  Note: folders don't have version numbers, nor do binary files (like graphics) have one, that's why the column "Version" displays "n/a" for folders and binary files. Only files that contain textual content can have a version number, so don't be alarmed by the many "n/a (OK)"-messages.
• Revision
  The revision of the file on your server. If it is identical to the revision indicated in the XML repository, you should see an "OK". If you're running an oudated revision on your server you should get a fresh package and perform an upgrade.
  Revisions are related to the versions - usually, if your version is OK, your revision should be OK as well. Only if you perform checkouts from the subversion repository, the revisions may "act up".
  The same thing that applies to version numbers applies to revisions as well: only textual files can have revision numbers - folders and binary files don't have a revision number.
  Confused? You don't have to: usually, you can savely ignore revisions - if you want to find out about what revisions are being used for, read the details on the subversion page.
• Modified
  If a file is accessible and the version and revision numbers match, the versioncheck script attempts to perform a check wether the file has been modified, compared to the original that comes with the coppermine package. This check is being performed by taking into account the MD5-hashes of the original file and your copy.
  When performing a fresh install or upgrade, there should be no modified files. If they are being displayed as modified, there are several possible reasons:
  • You deliberately modified the file (e.g. by applying a custom modification to it). In this case, it's OK to ignore the warning in the "Modified"-column and continue
  • Your file has not been transfered fully to the webserver. If this is the case, try to re-upload the file from your client to the server. If this doesn't help, your package might have gotten corrupt. Re-download a fresh one from the coppermine download section, un-archive it and re-upload the file. Make sure that your FTP app is configured to actually overwrite existing files
  • You have used an improper FTP-mode to transfer the file to your webserver. Using FTP apps, you can transfer files in binary or ASCII-mode. Most up-to-date FTP clients have a feature that will automatically select the proper FTP-mode for each file. If this is not the case, try the manual appoach and explicitely specify the FTP-mode for your file uploads.
  • Your webhost is injecting code into each file. Many free webspace providers (so-called "freehosts") do this to inject advertisments into your files. There's little you can do then except signing up with paid webhosting or ignoring the "Modified"-warning and hoping that things will work anyway.
• Comment
  The comment-column contains a short recommendation about what is suppossedly wrong and what you should do to fix this. No comments usually means that everything is OK.
• Repository link
  The link to the SVN repository (web SVN) is meant as an additional feature for power-users and developers. Read the subversion repository instructions to find out more. If everything is fine, you don't have to worry about the link anyway.
• Help
  Feature not done yet - there currently is no help available. Will be added later (hopefully).

Things that could go wrong using versioncheck

As the actions performed by the versioncheck script are complex, there are several things that can go wrong, depending on your webserver setup:

• No connection to the online XML repository
  If your server resides behind a proxy or a web filter that requires authentification or doesn't have internet connection at all (e.g. on a company's intranet), the versioncheck script may not be able to connect to the online XML repository. Use the corresponding option to keep the script from trying. The caveats mentioned in the options section applies.
• I get a white page, or a page without actual content
  The script probably times out, as it consumes huge resources. You'll have to live without versioncheck then on your server setup, unless the server is yours to configure, so you can assign more memory and execution time to the script.

Downgrading from cpg1.5.x to an older version

CPG1.5.x incorporates many new features (compared to older versions), so we encourage all users to upgrade. However, there may be some who want to test cpg1.5.x and decide later that they want to go back to an older version. You have to keep in mind that a full upgrade changes the overall layout of coppermine's database that includes converting the encoding to unicode. This process can't be reverted: once you have done the conversion, the only way back is to restore a complete mySQL database dump (of course you have to create this backup before you upgraded in the first place). Creating mySQL dumps (backups) is recommended anyway, so you should do so now.

To make this absolutely clear: you can only downgrade if you used to have cpg1.4.x before and upgraded this version to cpg1.5.x. If you have made a fresh install of cpg1.5.x, you can't downgrade at all!

To actually perform the downgrade, replace all cpg1.5.x files on your server with the files from the older version (as if you were doing an upgrade, see above).