# Coppermine Photo Gallery v1.5.x: Documentation and Manual

# Backup

This page is meant to explain how to back up a coppermine-driven gallery.

Backups can be used to restore your gallery somewhere in case something goes wrong (i.e. server hard-drive crash, hacking, own mistake) or if you want to move (move servers, move to another webhost, use another application).

Coppermine stores content both on file system level (i.e. on your webspace - that's the hard drive of your webserver) as well as on database level. Think of the database as a giant array of tables that are connected one with the other. Although the database is (technically) being stored in files as well, you can't just backup the file that represents the database. This is being caused by the way that a database works. Additionally, you usually don't have access to the file that represents the database (but don't start the wicth hunt and try to find it - you wouldn't be able to use it anyway). That's why the backup process needs to be two-fold: you need to back up your files and you need to back up your database. Only backing up one of them without the other will result in an incomplete backup that hardly can be usefull.

### File Backup

The backup on file system level is pretty straightforward and you already should be familiar with the technology, assuming that you have installed coppermine in the way the coppermine dev team recommends: using your favorite FTP application. Do not trust buggy tools integrated into WYSIWYG editors. Do not trust wannabe "web-FTP" clients: you need the real thing - a genuine FTP client. If you don't have one already, get one first before continuing.

#### Complete File Backup

The term "complete file backup" means in this case "a file backup of the entire coppermine gallery". It's advisable to perform this at least once, so you have a full backup for disaster recovery.

To actually perform such a backup, create a folder on your local hard drive first. Of course you need to make sure in advance that there is enough room left on the storage device you use (your internal or external hard drive in most cases) to hold the entire gallery once the backup is done. If you're short on disk space on your client, you could burn the contents of your backup to a CD or DVD once your backup is complete and then free the precious hard drive space once you have copied everything to CD/DVD.

#### Partial File Backup

If you perform frequent backups you don't have to make a complete file backup each time, as the coppermine core code will (i.e. all the files that make coppermine work on the server) will not change from one backup to the other. That's why you can then perform a partial back, i.e. only the contents of the albums folder of coppermine that corresponds to `http://example.com/your_coppermine_folder/albums/`. If you need to perform a restore later, you will have to restore your complete backup first and then restore your partial backup that was created later and therfor is more accurate and recent.

#### Incremental File Backup

There are nifty tools available from third parties that will perform an incremental backup by FTP, i.e. they will only backup the files that are new or have changed since the last time the backup was performed. This will reduce the time needed to perform a backup dramatically, but on the other hand will make restoring after a disaster a bit trickier - you should only use that option if you know what you're doing.

### Database Backup

Coppermine creates during initial install several database tables that are being used to store the content:

- The pictures table stores the path on file system level to the content of your gallery (i.e. the images)
- The config table stores your configuration
- The users table stores data about your registered users (including the admin account)
- ...

There are many other tables that store specific aspects of the content of your gallery - for a complete list of all tables and the structure within them, take a look at the database schema. All relevant tables of a coppermine gallery have the same prefix - the one you chose during initial install. To perform a database backup, make sure to backup all coppermine tables, i.e. all that have the prefix you chose during install. If you're not sure about the prefix, download the file include/config.inc.php with your FTP app to your client and then edit/view it using a plain text editor (notepad.exe is fine): the prefix should be named there. By default, the prefix name is `cpg15x_`.

#### Database Backup: what needs to be backed up?

The wording may differ, depending on the tool and it's version you use to perform the backup, you you need to know what exactly to backup.

A full database backup contains both the structure of the database table definitions (i.e. the "instructions" needed to create the empty tables if they have been lost or need to be created on another server) as well as the data (i.e. the actual table content).

The tables coppermine consists of are not equally important though:

- The table cpg15x_hit_stats can become quite large if you have enabled the feature "Keep detailed hit statistics". Subsequently, the backup can become quite large if the contents of that table is being taken into accound during frequent backups. Escepcially when moving a coppermine install from one server to the other it might be a good idea to skip the detailed hits statistics and therefore not backup the contents of this particular table.
- The table cpg15x_sessions tracks sessions for logged in and anonymous users. It gets populated automatically if it is empty, so you don't necessarily to back it up.
- The table cpg15x_temp_messages is used to store messages from one page to the other - the content is very short-lived and will be purged frequently, so the table doesn't need to be preserved when performing frquent backups.

Keep in mind though that coppermine will complain (i.e. there will be an error message) if a table is missing, so you need to create the above-mentioned tables in the first place, but they can be empty.

#### Database Backup Tools

Coppermine does not come with a database backup tool - you need to find one by yourself and use that. However, there is a list of tools the dev team recommends:

- ##### phpMyAdmin

  Open-source web application for database management that can be downloaded (for free) and installed on your webserver (easy installation). It comes with multiple language support. Your webhost may even provide this tool.
  [more]

  Please note that the coppermine dev team can not support you on the usage of phpMyAdmin - so here's just a short summary that is not meant to be a replacement for the documentation for phpMyAdmin:

  - Point your browser to the URL where your copy of phpMyAdmin resides (assuming that you have successfully installed phpMyAdmin on your webspace or that your webhost is providing phpMyAdmin for you)
  - If applicable (i.e. if the security settings of phpMyAdmin are configured accordingly), provide your phpMyAdmin login data if you're prompted for it
  - If applicable (i.e. if you have access to several databases), select the database where your coppermine database tables resides in (the database you have selected when installing coppermine) from the top left frame in the phpMyAdmin interface
  - In the right phpMyAdmin frame at the very top, select "Export" from the navigation
  - On the screen "View dump (schema) of database", select the tables you want to backup (by default, all tables within the selected database are selected) from the box labelled "Export". If you're not sure, back up all coppermine tables, i.e. all tables that have the same table prefix that you specified when installing coppermine in the first place
  - In the "Export" box, leave the radio button "SQL" selected that is already selected by default
  - Make sure that the checkbox "Structure" is ticked
  - Do not tick the checkbox "Drop table" - dropping means "deleting the table after the backup is complete", which is something you almost certainly would not want to happen, as coppermine would stop working immediately and you'd have to perform a restore.
  - Make sure that the checkbox "Data" is ticked
  - It's advisable (although not mandatory) to tick the checkbox "Complete inserts"
  - It's advisable (although not mandatory) to tick the checkbox "Extended inserts"
  - It's advisable to tick the checkbox "Save as file" that will give you a file to download instead of just getting the output of the dump displayed on screen that you would then have to copy & paste into a plain text file.
  - If you're running into time-outs while creating the database dump, try enabling compression for the file (you can of course only use the compression format that is available on your webserver)

  If you're not sure, read the documentation that comes with phpMyAdmin and google for backup tutorials on the internet; the coppermine support board is not the correct place to ask for support on phpMyAdmin usage.

- ##### mySqlDumper

  MySqlDumper is a web app that can be downloaded and installed on your webserver. It is meant to be used to create backups of your mysql databse (and eventually restore those backups). Particularly helpful if you don't have shell access to your webserver and regular mySQL backups fail due to time-outs.
  [more]

- ##### mysqldump

  The tool mysqdump must not be confused with mySqlDumper or vice versa: mysqldump is a script that belongs to the mysql resources themselves that only applies (i.e. that you can only use) if you have shell access (which is rarely the case for most, webhosted users). [more]

- ##### mysqlhotcopy

  The Perl script mysqlhotcopy belongs to the mysql resources. It is the fastest way to make a backup of the database or single tables, but it can be run only on the same machine where the database directories are located. mysqlhotcopy works only for backing up MyISAM and ARCHIVE tables. It runs on Unix and NetWare. [more]

#### After the database backup

After performing the manual database backup it's important to make sure that the dump you just created works as expected. Therefore, you should really try to open the dump file first and see if it not broken. Ideally, you should perform a restore on a testbed to make sure everything works as expected.

There have been many users already who relied on their backup without ever having tested it once: if you never test your backup strategy, you will never know if it will enable you to perform the restore in case of a disaster. Since there are many things that can go wrong, it's really recommended to test your backup.

### Moving your gallery

Your coppermine-driven gallery can be moved around on your webserver as well as from one webspace to the other. Here's how you accomplish those tasks:

#### Moving on your webserver

Moving your gallery on your webserver (e.g. from a particular folder to the webroot or vice versa) is comparatively easy. Coppermine consists of two components:

- Files
- Database records

The good thing about moving your files/folders around is the fact that coppermine does not store the absolute path to a file within the database, but only a relative one: the relative path inside the albums folder). Subsequently, you can move around the folder where your coppermine gallery resides in on your server easily and you won't have to change your database records accordingly.

Just keep in mind that you need to move the entire coppermine folder around, i.e. you must move all files and folders around and not just some of them. The folder and file structure within your coppermine folder needs to remain intact when moving it.

Basically there are two options for this:

- ##### You just rename the folder your gallery resides in

  This is the setup that is the most easiest option. If your coppermine-driven gallery currently resides at `http://example.com/your_coppermine_folder/` and you find that URL to hard to memorize for your visitors, you could just rename the folder `your_coppermine_folder` to something else that is easier to memorize, e.g. `gallery` or `photos`. To accomplish that, you just use your favorite FTP application and rename the folder that corresponds to `http://example.com/your_coppermine_folder/` accordingly. All that is then left to do is described in the section Changing Coppermine's URL in config.

- ##### You move the coppermine folder contents around

  Unless you have shell access to your webserver, this is a three-step process: first you copy the entire content of your coppermine folder to a temporary folder on your client using your FTP application. Then you restore the content of that folder in the target directory on your server. Finally, you need to set permissions for the new folder structure.
  Let's assume that your website is at `http://example.com/` and your Coppermine gallery is located at `http://example.com/coppermine/`. Let's assume that the webroot `http://example.com/` corresponds to the absolute path `/home/htdocs/` on the server and subsequently the gallery corresponds to the server path `/home/htdocs/coppermine/`. Let's assume that you want to move it to a folder named "`photos`" that resides within a folder named "`multimedia`". For that target folder the absolute path would be `/home/htdocs/multimedia/photos/` and the target URL would be `http://example.com/multimedia/photos/`.

  Step | Webserver | Direction | Client | Explanation
  --- | --- | --- | --- | ---
  1 | URL: `http://example.com/coppermine/` Absolute path: `/home/htdocs/coppermine/` | → | `c:\temp\coppermine\` | Use your FTP app to copy the gallery folder and everything within it into a temporary folder on your client's hard drive.
  2 | URL: `http://example.com/multimedia/photos/` Absolute path: `/home/htdocs/multimedia/photos/` | ← | `c:\temp\coppermine\` | Use your FTP app to copy all content from the local temporary folder to the new target folder on the server.
  3 | URL: `http://example.com/multimedia/photos/albums/` Absolute path: `/home/htdocs/multimedia/photos/albums/` | n/a | - | Set permissions (using your FTP app) on the albums folder that needs to be writable.

  Finally you could delete the local temporary folder where you stored your coppermine files in, but it's advisable to keep that folder instead as a backup.
  What folder is the source folder and the target folder doesn't matter at all, nor does it matter how deep the coppermine folder is nested within the folder structure on your webserver. The steps needed to perform when moving coppermine from a folder to the webroot or vice versa don't differ at all: the webroot in fact just is represented by a folder on webserver file system level, and you move the content of a folder around.

#### Moving from one webserver to the other

This scenario usually applies when switching from one webhost to the other. In fact you create a copy of your files (a complete file backup) and a copy of your database (complete database dump) on the old server and restore those copies on the new server.

You're encouraged to create and maintain frequent backups in case anything goes wrong, so you really should have a backup already. However, if you don't have one, you should create one now. You need to keep in mind that there might be a downtime of your site when moving from one webhost to the other. Ideally, the downtime will be neglible, but you usually won't be able to access the gallery on the old server and the gallery on the new server under the same URL at the same time. Therefore, you need to backup the old server while you still can, i.e. before your old webhosting contract expires and you no longer can access the old server to create the backup. If you don't have a backup and your webserver is no longer accessible you will be out of luck: nobody will be able to help you recover your gallery - it's absolutely mandatory to have a working backup both of your files as well as your database.

Refer to the corresponding ections on this page to figure out in detail how to create the backups.

Below is a summary of the needed steps and some notes on the tricky stuff:

- ##### Maintenance mode

  Tell your visitors that there will be maintenance works on your site and that there might be downtimes. If you allow visitor interaction like uploading of files or posting of comments, you better put the gallery into offline mode or make sure otherwise that the content of your database won't change after having created the dump.

- ##### Backup your files

  FTP-download your complete coppermine-folder (including all folders and files within it) from the old server to your client's hard drive, preserving the structure of the sub-folders.

- ##### Create a dump of your database

  Use a tool like phpMyAdmin or similar to backup your database, i.e. to get a dump (backup) of your mySQL database entries. Make sure that you're not just creating a backup of your table structure - you need to backup the actual content (i.e. the individual database records) as well.

- ##### Verify your backup is working

  Check if the mySQL-dump contains all data (open the zipped dump file and use a text editor to view it). Ideally, restore the entire gallery on a testbed in case you can't access the new server yet to make sure your backup is valid and working.

- ##### FTP-upload your coppermine-folder to the new server

  Restore the files on the new server if you can, again preserving the exact structure of sub-folders that exists in your backup on your client.

- ##### Set permissions

  Coppermine needs write permissions on some folders, so you need to set permissions on the new server in the similar way you had to do when installing Coppermine in the first place on the old server. Don't forget this step, it's important!

- ##### Restore the database

  Restore the mySQL table by running the queries of the dump files you created on the old server. To accomplish that, you will need the same tool on the new server (the target server) that you have used on the old server to create the backup; if you have used phpMyAdmin on the old server to create the backup you should use phpMyAdmin on the new server as well to restore the dump.

- ##### Edit the database settings

  Your new webhost must have provided you with the mySQL access data (you already had to use that data to restore the dump on the new server). That mySQL data usually will differ from the mySQL data on the old webserver, so you will have to edit the file that contains those data. Use a plain text editor (notepad.exe is fine) and edit `include/config.inc.php`: inside that file, you will find the old mySQL data that you will need to overwrite with the mySQL data for the new server.

- ##### Disable maintenance mode

  If you have originally put your gallery into offline mode on the old server you have to remember to turn offline mode off on the new server. Go to coppermine's config and edit the corresponding setting.

- ##### Test everything thoroughly

  Test every facet of your gallery: try to log on as regular (non-admin) user, try to use http uploads, post a comment etc.

#### Disadvantages of renaming

There are several disadvantages when changing the URL of your gallery:

- Bookmarks / favorites of your visitors will no longer apply
- Search engine indexes will point to the old URIs. Subsequently, you will lose the ranking in those search indexes

Tim Berners-Lee (the "inventor" of the www) coined the motto "Cool URIs don't change" that still applies, so you better think twice before renaming your coppermine folder once it has been established. It's better to choose a clever folder name in the first place (when initially installing Coppermine). Anyway, if you must change the URI of your gallery (or in fact any other URL), you should at least set up some redirector that takes care of the change: on Apache-driven servers (and provided that your webserver supports that feature), you could set up a redirection using a `.htaccess file` with the redirect directive.

#### Changing Coppermine's URL in config

Whenever the URL of your gallery changes (i.e. after having moved your gallery around on your webserver or after renaming the folder it resided in), you have to reflect the changed URL in coppermine's config:

- Go to the new URL in your browser's address bar
- Log in as admin if you're not already logged in
- Go to Coppermine's config panel
- Expand "General settings"
- Enter the new URL into the field "URL of your coppermine gallery folder"
- Scroll to the bottom of the config panel
- Save your changes by submitting the form using the corresponding button at the bottom of the page