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

Table of Contents

Uploading pics/files

Coppermine is a web gallery, so the key aspect of it's usage is the ability of the admin (or the users if the admin allows them to upload) to upload images (or rather files) to the gallery - without files being uploaded, a gallery doesn't make much sense. What actually happens during upload is that the image uploaded gets resized and a thumbnail is being created. Additionally to the file that is being stored on the webspace, a database record is being created for each file uploaded. All of this stuff happens "behind the scenes" - coppermine is taking care of this, so you don't have to know what exactly is happening. However, the ability to upload is being limited by several factors that coppermine doesn't have the power to change. This is where this part of the documentation comes into play: if things go wrong or don't work as expected, you should read up this documentation to be able to fix the things that don't work as expected. So, please read on - at least if you have issues with uploads.

There are several methods to upload files within Coppermine. You (as gallery admin) should use FTP-upload plus batch-add (only the admin can do this). Regular users are supposed to use the "regular" http upload or (if they have Windows XP) the XP Publisher.

An uploading client for Linux using the KDE desktop is available as well: Coppermine-developer Aditya Mooley has created "Koppermine" that is recommended for all Linux users.

If you have issues uploading, read the upload troubleshooting section extra carefully.

Sub-sections of the upload documentation

There are several sub-pages that explain details about uploading:

How Coppermine stores files

As suggested above, there are several ways that you can use to upload files to coppermine: depending on the upload method you use, the files will be stored in different ways. To the regular visitor of your gallery, this is not important at all, since coppermine (or rather: the database that coppermine is using) keeps track of where your files are actually stored - the human doesn't have to. This being said: if you don't care about the folder and file structure on your webserver, you can savely skip reading this section of the docs.

The albums folder

Out of the box, coppermine is storing all files that are being uploaded within the folder named albums that resides within the coppermine root folder. This folder name is a bit misleading and exists for historical reasons (for backwards compatibility with older versions of coppermine). It's important to remember that this folder name must not be confused with the logical structure of albums; uploaded files can be set up in a way that allows you to mimmick the logical category and albums structure of your frontend, however this doesn't have to be the case. You can change the name and location of the folder where all your uploads go to from albums to anything else using the config option "The album directory", but unless you really know your way around it's advisable to keep the default. Pay attention to the warnings that apply when changing that config option.

HTTP-uploads go into the userpics folder

When using http uploads (the "regular" upload method that is being used if you use the "upload"-link from coppermine's menu), all uploaded files will physically reside in a sub-folder of the folder userpics. The folder userpics itself is a sub-folder of the albums-folder.
The name of the userpics folder can be changed as well (refer to the config option "The directory for user files"), but again pay attention to the warnings for that config option! The name of the actual folder the files go into is being calculated based on the user ID of the user who uploaded the file initially (10,000 plus user ID). This leads to a structure like this:, where the sub-folder 10001 relates to the folder for the user with the ID "1". If you should get more than 10,000 users, the count goes on (as the folder name is user ID plus 10,000), so the user with the user ID 10000 will correspond to the sub-folder 20000 of the userpics folder.

The only exception to this rule is the usage of safe_mode: if your webserver runs in safe_mode and you have turned silly safe_mode on in config, the PHP script usually can't create sub-folders. That's why all uploads by all users will directly go into the userpics folder without a sub-folder for each user being created.

The temporary edit folder

Inside the albums-folder, you'll find a sub-folder named "edit" - that's the only temporary folder coppermine is using. It is being used for internal purposes only: if you use http uploads and the user has already uploaded several pics, they go to that folder first. The user then has to assign the uploaded files to albums, which is the moment when the uploaded files get moved from the temporary folder to the actual sub-folders of the userpics folder. If he doesn't assign the uploaded files to albums (or something goes wrong), the temporary files remain in the edit-folder, where the garbage collection takes care of them from time to time and deletes older temporary files. This mechanism is necessary because the http upload mechanism can be tricky to handle, seen from the perspective of a programmer: all kind of weird things could happen (the files could be too large, there could be no more webspace left, the target folder might lack the needed write permissions for the script). Using the temporary folder for http uploads just makes coppermine's http upload mechanisms more reliable, which was the reason why it has been designed the way it is. Don't touch the edit-folder at all manually: don't rename it, don't delete it, don't upload files there - just leave it as it is and let coppermine use it for it's own purposes.


FTP uploads are a totally different animal: as the initial FTP upload isn't being performed by coppermine, but the admin user himself (using his FTP client), it's his task to make sure the files he tried to upload are actually there where they are expected. What the batch-add process does is adding the files that already are physically where you want them to be to the database. To make sure that you understand this concept: the database itself doesn't contain the files - think of it as a logical structure only, that keeps track of the physical location of the files and some other parameters (like dimensions, the album the file resides in etc.). Think of the database as a phone book that doesn't actually contain the people it lists, nor does it contain wires nor phones: all a phone book consists of are records that point to something in real life (a person's name & address & phone number).

This being said, your FTP-uploads should go into a folder structure within the albums-folder. They must not go into the userpics folder, but into a folder-structure of it's own. Those folders you create with your FTP app are not temporary folders, but they are permanent: coppermine doesn't move those files around, but leaves them where you FTP-uploaded them to in the first place.

XP Publisher uploads

When you use XP Publisher to upload, there is another storage pattern that is being applied: the files go into sub-folders of the albums folder that are named wpw-yyyymmdd, where "wpw" stands for "Windows Publishing Wizard" and yyyy for the year, mm for the month and dd for the day of the upload. Again, coppermine doesn't move those files around - they remain where they are.