Step-by-step guide when asking for support

This is a step-by-step guide that is meant to explain in a fool-proof way what settings you need to make when asking for support on the Coppermine support board.

We assume that you have applied tight permission settings, so we'll go through this a bit more complicated than actually necessary on most setups: the instructions below are meant to allow upload troubleshooting for the supporter even if the rest of users of your gallery isn't allowed to upload or if you don't even allow user registration in the first place. If you know your way around, you can of course skip the steps that explain the creation of an extra group if all your registered users are allowed to upload anyway. In the end, the important thing that counts is that the supporter can go through uploading untill he/she can see what actually goes wrong during the upload stage.

• Log in as admin

  Go to your coppermine page and log in as admin

• Create uploader group

  The instructions below how to create a group only applies if you are running Coppermine in standalone mode. If you have bridged your Coppermine gallery, use your bridging application to create the uploader group.

  • Go to the group control panel by clicking on the corresponding link in the admin menu
  • Scroll to the bottom of the page
  • Click on the "Create new group" button
  • A new table row will appear at the bottom of the groups control panel table. Click into the name field and enter a name for the group that will make sense, e.g. "uploaders"
  • Scroll to the bottom of the page
  • Submit the form by clicking on the "Apply changes" button

• Assign upload permissions to the uploader group

  The instructions below how to assign upload permissions to a group applies both for bridged as well as for standalone galleries.

  • Go to the group control panel by clicking on the corresponding link in the admin menu
  • For the uploader group you created in the previous step, set the "Allowed" toggle to "Yes" in the column "Public albums upload". Set the "Approval" toggle to "No" in that table cell.
  • Scroll to the bottom of the page
  • Submit the form by clicking on the "Apply changes" button

• Create a non-admin test user account

  The instructions below how to create a user only applies if you are running Coppermine in standalone mode. If you have bridged your Coppermine gallery, use your bridging application to create the test user account.

  • Go to the user manager by clicking on the corresponding link in the admin menu
  • Scroll to the bottom of the page
  • Click on the "Create new user" button
  • On the following screen, enter a user name that is easy to memorize and type - we recommend something simple like "tester", preferably without capitalization.
  • Assign an easy password - can be the same as the user name.
  • Assign the user to the "Uploaders" user group you created previously - make sure that for the user group dropdown field the value is "Uploaders" (or whatever name you chose for the custom group).
  • Scroll to the bottom and submit the form.

• Create an album where the uploads can go into

  So far, we have created a custom group that is allowed to upload to public albums, but we haven't specified into what album the upload is allowed to go to. We need to create an album first.

  • Go to the album manager by clicking on the corresponding link in the admin menu
  • Choose a category in which the test album should be created in - pick the category using the dropdown field at the top of the album manager. For ease of use it's recommended to create the test album in the gallery root (i.e. picking "* No category *" from the dropdown).
  • Click on the "New album" button at the bottom of the album manager page
  • An input field will show. Enter the name of the new album as "test album" and submit the form by clicking on the OK button

• Allow uploads to the test album

  The album where the uploads should go to exists, but so far nobody except the admin has got permissions to upload to it. Let's allow uploads for that album.

  • Go to the gallery index by clicking on the "Album list" link in the regular gallery navigation
  • Navigate to the category in which you created the test album in (if you did as suggested and created the test album inside the gallery root, you should already be where you're suppossed to be, so no need for action here)
  • Click on the "Properties" button next to the empty thumbnail that represents the test album
  • On the album properties screen, set "Visitors can upload files" to "Yes"
  • If your gallery has heavy traffic and you don't want your site visitors to notice that there is a test album, choose "Members of the 'Uploaders' group" from the dropdown list "Visitors can upload files"
  • Scroll to the bottom and submit the form by clicking on the button "Update album"

• Set "Default upload method" to "Simple"

  • Go to the config screen
  • Scroll to the section "User settings" and expand it by clicking on it
  • Set the Default upload mechanism to "Simple - one file at a time"
  • Scroll to the bottom of the page
  • Save the new settings by clicking on "Save new configuration"

• Enable "debug mode"

  • Go to the config screen
  • Scroll to the section "Maintenance settings" and expand it by clicking on it
  • Enable debug mode for everyone by clicking on "Yes: Everyone" in the line "Enable debug mode"
  • Leave display of notices switched off - if the checkbox "Display notices in debug mode" is ticked, un-tick it (notices are only meant for developers - if you have idea what they mean, leave them off permanently)
  • Scroll to the bottom of the page
  • Save the new settings by clicking on "Save new configuration"

• Test uploading using the test user account

  You may be tempted to go ahead and ask for support now, but wait a minute: you haven't tried for yourself yet if everything works as expected. You wouldn't want to start a support thread and just be told "do your homework first" (because that's what will happen if you obviously failed to do as suggested here). Here's what you do:

  • Log out from Coppermine (or use another browser alternatively) if you're logged in as admin
  • Log in using the non-admin test user account that you created in the steps above. If logging in fails, review the test user account details while being logged in as admin.
  • Click on "Upload file". If you don't have that upload link, you have failed to set up permissions properly - review the steps above carefully.
  • On the upload file screen, choose the test album from the "Album" dropdown. If you can't select the test album, you have made a mistake when setting up the upload permissions
  • Click the "Browse..." button and navigate to a small, known-good jpg-file on your hard drive. Don't assume that any image will do: when in doubt, download a test image from the coppermine demo page
  • Submit the form by clicking on the "Upload file" button

  In an ideal world, everything will work as expected - your upload will succeed and you will see your uploaded image embedded into a coppermine page. If this is the case, http uploads work as expected. If this is not the case, you should get an error message that explains what went wrong. If you can't figure out what the error message means, but you were able to perform all the steps above including the last one (submitting the upload form), then please go ahead and ask for support on the coppermine support board. You're welcome to post your support request as well if http work as expected, but you want to request help with another upload method.

• Post your support request on the Coppermine support board

  • Go to the Coppermine support board
  • Register for a new account if you don't already have one and log in with that account on the coppermine forum.
  • Make sure to have read the board rules before posting (a link to the board rules can be found in the forum navigation)
  • Start a new thread on the support board that corresponds to your coppermine version. Since you are reading the documentation for cpg1.5.x, you are probably using that version, so you should start your thread on the sub-board that deals with that version. Posting on a board for another version is not an option and will lead to frustration only both for you as well as for the supporter. Since you have issues with uploading, you should post on the sub-board that deals with upload issues.
  • In your posting, make sure to post a link to your gallery. If your gallery contains adult content (mild nudity falls into this category as well), make sure to post a warning with your link
  • Post the test user account details (user name and password) that you have set up above
  • It's a good idea to show supporters that you tried for yourself before asking for support - explain what actually goes wrong, how far you got, what error message you get etc.

Example support request

Error message: failed to create stream: Operation not permitted

Impossible to move somepic.jpg to albums/userpics/
Warning: move_uploaded_file(/tmp/phpezCYKr)
[function.move-uploaded-file]: failed to create stream: Operation not permitted

Impossible to move X to Y

Impossible to move somepic.jpg to albums/userpics/XXXXX/

Error message: failed to open dir: No such file or directory

Warning: opendir(./albums/edit): failed to open dir: No such file or directory

Error message: Sorry there is no album where you are allowed to upload files

Sorry there is no album where you are allowed to upload files

Error message: Allowed memory size of X bytes exhausted

Fatal error: Allowed memory size of XXXXXXX bytes exhausted at (null):0 (tried to allocate XXXX bytes) in /var/www/html/include/picmgmt.inc.php

Error message: Exec() has been disabled

Exec() has been disabled

Error message: Not a GD extension

Not a GD extension

Error message: Error executing ImageMagick - Return value 127

The file 'albums/userpics/10001/somepic.jpg' can't be inserted in the album. Error executing ImageMagick - Return value 127

Error message: PHP running on your server does not support the GD image library

PHP running on your server does not support the GD image library, check with your webhost if ImageMagick is installed.

Error message: No file was uploaded !

No file was uploaded ! If you have really selected a file to upload, check that the server allows file uploads...

Error message: Destination directory X is not writable by the script

Destination directory albums/userpics/XXXXX/ is not writable by the script

The PHP configuration file php.ini

Things to check

If you are webhosted, you will need to consult with your webhost regarding the following settings. You can review (although not change) those settings on your phpinfo page.

1. max_input_time

   60 seconds is the default time limit for uploading files.
   This time limit includes the time it takes for the files to upload, so if you exceed this limit, the file will not even parse, and the browser will not get a response. You can workaround this by trying to upload smaller or fewer files, or you can try uploading over broadband. The best solution, of course, is to increase the time limit to something more in line with your needs.

2. upload_max_filesize

   2MB is the default limit for individual files.

3. post_max_size

   8MB is the default limit for post requests.

4. memory_limit

   8MB is the default size. Read up Memory usage during resizing for instructions how to change this setting and circumvent the error messages related to the memory limit being reached.

5. LimitRequestBody

   512KB default limit. (mainly an issue on Redhat/Apache systems. Found in /etc/http/conf.d)
   In general, upload_max_filesize < post_max_size < memory_limit in order for uploads to function properly. Coppermine may warn you if a file exceeds upload_max_filesize, but it cannot warn you if the total size of all the files exceeds the post limit or the memory limit.

6. file_uploads

   This determines whether or not PHP will allow file uploads. It must be set to "On".

7. upload_tmp_dir

   This specifies the temporary directory where PHP stores uploaded files.
   The most common issue caused by this setting is an open_basedir warning. In this situation, your server administrator has restricted the files that PHP can work with to a certain directory. If he does not create and specify a temporary directory within the open_basedir restriction, PHP will attempt to use the OS temporary directory, and it will be rebuffed by the open_basedir restriction.

Upload mechanisms/methods

Some notes about the different types of upload mechanisms available since cpg1.3.x (or better):

Multiple HTTP uploads are designed to handle a small number of files. Therefore, they are not well suited for the uploading of large numbers of files unless you are running your own webserver or have control over the php.ini configuration.

If you are looking to upload more than 15 or 20 files at a time, you should consider the batch add process or the XP Publisher utility. Each has its own drawbacks and advantages.

The batch add process is fast, but it creates quite a load on the server and, as a result, you may experience timeouts causing your uploads to terminate prematurely. XP Publisher, on the other hand, is considerably slower, but it limits the load on the server. It also circumvents many of the pitfalls caused by limitations set in the php.ini configuration by uploading each file in the batch being uploaded as an individual post request.

Other alternative upload mechanisms (like Client-based agents as JUpload or similar) may be provided as third-party contributions - you're encouraged to look at them as well, but please keep in mind that the coppermine developers can only provide limited support for third-party contributions.

Keep in mind though that before trying any alternative upload mechanism, you have to make sure that the initial upload method "http uploads" works as expected - if it doesn't, you have to fix that first; it doesn't make sense to try alternative upload mechanisms if the core upload mechanism doesn't work.

Memory usage during resizing

There is (at least in theory) no limit in Coppermine to the file size or dimensions that the script can handle. However, there is at least one limit existing on the webserver: resizing images (to create intermediate images and/or thumbnails) consumes memory and burns CPU cylces.

If the resizing process is eating up too much memory, you usually get the error message Fatal error: Allowed memory size of XXXXXXX bytes exhausted at (null):0 (tried to allocate XXXX bytes) in /var/www/html/include/picmgmt.inc.php or similar.

To prevent the server from crashing, the server admin has to restrict the amount of memory that a PHP script is allowed to consume. This is done using the parameter memory_limit.

You might be tempted to believe that the memory usage equals the file size an image consumes on file system level, but that's not the case: the common file format JPEG is compressed, so if the server loads a JPEG file into memory, it consumes much more RAM than it consumed on file system level.

To calculate the amount of memory an image uses, you simply multiply the pixel width and height, and then you multiply the result by the number of base colors (RGB - 3, CMYK - 4). Finally, you divide by 1,048,576 (2²⁰) to get the memory usage in MB.

Here are some common image resolutions and their memory use in GD (assuming RGB):

Remember when using the above figures that the amount of memory being used by the rest of Coppermine must be taken into account, too.

As you can see, the memory consumption of images produced by modern digital cameras can easily be too much for your webserver to cope with, even when using single file uploads (let alone the consumption when processing several images using batch-add), so it's recommended to resize your images on your client before uploading them: if the server simply isn't capable to process the images uploaded, there's little point in blaming the script (i.e. Coppermine) or asking for support on the Coppermine support board: the Coppermine devs can not find a cure for the technology used on webservers. Use the webserver for what it has been designed to be used for; perform resources-intensive calculations (like resizing images with a high resolution) on your client.

To increase the memory limit allocation in php.ini, you must be the server's administrator. Also, .htaccess files cannot change this configuration setting, and it cannot be changed using ini_set(). This being said, most coppermine users who are on shared webhosting will not be able to change this. If you actually are the server admin, here's how to increase the memory limit:
First, you locate the following block in php.ini (if you actually are the server admin):

;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;

max_execution_time = 30     ; Maximum execution time of each script, in seconds
max_input_time = 60        ; Maximum amount of time each script may spend parsing request data
memory_limit = 8M      ; Maximum amount of memory a script may consume (8MB)

Now you increase the memory limit to fit your needs. 9 to 16 MB should handle most requirements.