Coppermine Photo Gallery v1.6.x: Documentation and Manual

Table of Contents


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

Why upgrade?

There are major and minor releases of Coppermine. Major releases have so far been cpg1.0, cpg1.1, cpg1.2.x, cpg1.3.x, cpg1.4.x and cpg1.5.x. The next major release will be cpg1.6.04 (which currently is in the dev pipeline - no scheduled release date yet) - you're just reading the preliminary docs for cpg1.6.x. Minor releases (the third number in the version numbering scheme) represent updates, also known as "maintenance releases". Major releases contain new features (compared to the previous major release), minor releases do not contain new features, but only bug fixes and slight improvements (like additional language files).

To understand the release policy of the Coppermine dev team you have to understand how bugs are being fixed: we maintain a repository where the core code of each major release is being constantly being improved. Major and minor bugs that are reported on the Coppermine support board are being fixed in that repository. Once a new package is being bundled, all fixes that have been made in that repository go into the new maintenance release.

There is a good reason for every new maintenance release: they are usually being packaged when a new bug or vulnerability is being discovered that is relevant in terms of security. As suggested above, there are several minor bugfixes that go into each new release as well, not only the one major bug or vulnerability that lead to the maintenance release. Therefore, it will not be enough to just fix the single vulnerability that has been the initial reason for a new package to be released. Instead, always upgrade to the most recent stable release as soon as it has been announced.

Reasons for package releases

This is a list of minor releases of cpg1.6.x and the reason why they have been released. It is meant to explain why you should upgrade as soon as possible to the most recent stable release if you are running an outdated version.

Package Reason for release Release Date
  • This version was never released as a package - the version number 1.6.01 was just reserved for the initial development stage of the cpg1.6.x series before the feature freeze stage started. There is no package available, nor has there ever been one - only Git checkouts have been possible.

As you can see, the Coppermine dev team is constantly fixing and improving Coppermine. Every non-trivial piece of software contains bugs, so there is no guarantee that the version that currently is the most recent one will be the final, ultimately bug-free version to be released in the cpg1.5.x series. It is absolutely vital that you perform regular updates as soon as new packages are being released.


Details on the changes that went into a release can be found in the changelog that comes with each package. The changelog file can be found in the root directory of the Coppermine package. The changelog contains more information on additional languages and the time and date of the fix as well.

The changelog is a plain-text file that can be read using a simple editor - on Windows-driven machines, notepad.exe is fine.

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

The instructions here apply for all Coppermine udpates/upgrades, so please read them carefully.

To make this absolutely clear:

there is no such thing as a separate upgrade package - Coppermine always comes as a complete package that can be used both for a fresh install as well as an upgrade.

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, cpg1.3.x or cpg1.4.x to cpg1.6.x

Support for a direct upgrade from cpg1.0, cpg1.1, cpg1.2.x, cpg1.3.x or cpg1.4.x to cpg1.6.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.5.x and then on to cpg1.6.x)

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

Upgrading from older versions of cpg1.6.x to the most recent version of cpg1.6.x

There are no additional steps to follow when upgrading from an older version of cpg1.6.x to the most recent version of that family. Just performing the basic instructions discussed above in Steps needed to perform when upgrading Coppermine (from any version) will be enough.

The update script

The updater is a script that will update your database and delete leftover files from outdated versions that are no longer used in your version. It can be accessed by clicking on the corresponding link inside the admin menu or by entering the URL into the address bar of your browser.

You can run the updater by entering http://yoursite.tld/your_coppermine_folder/update.php into your browser's address bar.

What it does

The updater performs three things:


The updater will perform the database update for you after you manually have replaced the sql file it is using. The updater will not detect for you if there is a new version of Coppermine available, nor will it download anything from the Coppermine website. The level of automation is not that advanced in Coppermine (yet).

To find out about new versions of Coppermine or maintenance releases, check the news from

Authorization check

In Coppermine versions before cpg1.5.x, the update script used to be publicly accessible, e.g. everybody was able to run it. While this was good for support purposes (supporters were able to run the updater for users looking for help if it was obvious that they had not done so), there was a slight chance that this accessibility for everyone could at some stage be a security risk. That's why the dev team members decided to protect the updater from being run by any visitor who accesses it - starting with cpg1.5x you need to supply admin credentials. This can happen in four different ways:

When must the updater be run?

You need to run the updater every time you upgrade/update, i.e. each time the file sql/update.sql is being replaced with a new version.

It doesn't hurt to run the updater several times in a row, so if you're in doubt, run it again.

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. 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). You can run the versioncheck utility from the Admin menu.

The versioncheck tool does not perform an actual update: it does not download newer versions of Coppermine for you, nor does it install any fixes - it just is meant to make you aware of newer versions and help you to determine wether you performed an upgrade correctly.

What it does

The script "versioncheck" is meant for two purposes:

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 Files that do not match are displayed and are the files you should update as well.

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 supposed 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.


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

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:

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:

Versioncheck is being provided as a courtesy to end users. As there are several factors that have an impact on it, it may or may not work on your server setup. If the versioncheck tool does nothing at all, this is probably the case for you - you don't have to be alarmed in this case: just make sure to keep your coppermine install up-to-date, preferably by enabling the config option "Display news from". Only if individual issues are being reported by the version check tool (i.e. only if some lines contain a remark in the comments column), you should be alarmed and take a closer look.

Wrong expectations

To some this may sound trivial, for others it might be an important piece of information: naturally, files that you have not replaced during the upgrading process (e.g. anycontent.php) will show as outdated in versioncheck's output. This is of course to be expected. It doesn't hurt if you performed the upgrade exactly as suggested, as the files you're supposed to keep during that process don't actually contain code that needs updating. As an example, anycontent.php doesn't actually contain code at all (at least the file that comes with Coppermine out of the box). It can contain custom code if you decide to use it. For details on the usage of anycontent.php, refer to the section "Using anycontent.php".

The versioncheck tool doesn't actually download newer file versions from the internet - it just checks the files you have on your server against a list of most recent files. The versioncheck tool doesn't check nor sanitize your site against hacking.

Upgrading FAQ

Downgrading from cpg1.6.x to an older version

CPG1.6.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.6.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.5.x before and upgraded this version to cpg1.6.x. If you have made a fresh install of cpg1.6.x, you can not downgrade at all!

To actually perform the downgrade, replace all cpg1.6.x files on your server with the files from the older version (as if you were doing an upgrade, see above). Then restore your database dump that you must have made before upgrading. If you don't have a database dump (backup), you can't go back!