Getting started

Use the "Album Manager" ("Albums" link in the admin menu) in to create and order your albums. You'll need at least one album your files can go into.

Use the anonymous group to define what non-registered users can and can't do (in the groups panel).

Use the properties of an album to modify its description and permissions.

In order for a user to be allowed to upload a file in album two conditions must be met:

• The user must be part of a group that can upload files.
• There must be at least one album where "Visitors can upload files" has been set to "Yes",
  OR
  The user has created an album in the 'user galleries', if allowed.

The same applies to picture rating and comment posting.

If you have installed the script succesfully but are having trouble getting it working properly you can enable the "debug mode" on the Config page. In this mode, the script outputs most of the warning/error messages produced by PHP in addition to some debug information. This can provide valuable information to understand what is wrong.

Basic concepts

Of course you're exited about Coppermine and want to start with it right now. However, there are some basic considerations you should make up your mind about first, as some settings can't be changed easily once your gallery has been populated with content.

So this section is meant as a guide once you've finished installing Coppermine. Go through it carefully to avoid issues that may turn up later.

• Initial configuration
  Settings you should edit immediately after finishing the install
• Category/album/file structure
  Understand how Coppermine organizes navigation and storage of individual files
• Resized images
  Resized versions of your uploaded originals are being created based on the config settings
• Your admin account
  
• Check uploads
  Make sure uploading works as expected before letting in visitors
• Consider bridging
  Bridging later when you already have users might get difficult
• What are your visitors allowed to do?
  What level of user interaction are you going to allow?
• Change your coppermine's design
  

Initial configuration

There are some settings in Coppermine's config that you should edit right after finishing install.

Log in with the admin username and password you set up during install, click on the "Show admin controls" link if it is visible, go to the Config page and start to configure your gallery. Note that even if you are a member of the administrator group, you need to have "Show admin controls" enabled. In previous versions, this used to be named "admin mode", but was renamed because some people thought that switching from admin mode to user mode showed them what regular users can see (which is not the case).

• Gallery administrator email
• URL of your coppermine gallery folder

There are some settings in config that can't be changed later (if there are already files in the database) - make sure to set them up correctly in the first place. Although you'll surely want to start using coppermine immediately it is advisable to configure those settings (marked with an asterisk "*") properly at the very beginning.

Category, albums and file structure

The Coppermine Photo Gallery works in the following way:

• Files are stored in albums
• Albums are organised in categories
• Categories can be nested (into subcategories)

If you don't plan to have many albums, you really won't need to use the categories feature. If this applies to you, simply do not create any categories and all your albums will automatically appear on the main page of the script.

There is, however, a special category named "User galleries". This category can't be deleted. If a user belongs to the group "can have a personal gallery" and this is set to YES, he will have the right to create his own albums and his gallery will be a sub-category of "User galleries". This link is not visible to visitors of your site, however, if you do not allow users to upload pics and have their own albums.

The administrator can create albums in any category. Non-administrative users can only create albums in the "User galleries/Their_username".

You can, however rename the "User Galleries". To rename the "User galleries" category and description, simply go to your category control panel and change the name there (e.g. to translate the words "User galleries" into your language).

Resized images

One of the key benefits of Coppermine is the fact that it creates thumbnails and intermediate-sized images for the original images uploaded. This happens once per image (on upload), however the process of creating resized images can be re-triggered using the admin tools. The resized copies of your originals are being stored in the same folder in which your original resides in - they just differ in terms of prefixes. You can determine the prefixes using the corresponding config options, however it's recommended not to change them at all unless you really know what you're doing.

The following resized files are being generated when uploading an image:

• Thumbnail
  The thumbnail is being created depending on the corresponding options "Thumbnail settings" in config if the file uploaded is larger in terms of dimensions than the dimensions set for the thumbnail. The thumbnails are mainly being used on the actual album thumbnail page, but as well in some other places (e.g. on the profile page or as thumbnail representation of albums and categories). The creation of thumbnails greatly improves the loading speed of your gallery - if coppermine would not create the thumbnail and display the originals instead (using HTML attributes to display them in a smaller size), the thumbnail page would be terribly slow to load.
  For the dimensions of your thumbnails you have to find a good compromise: thumbnails with smaller dimensions result in smaller files sizes and therefor the thumbnail page loads very fast. The drawback of small dimensions are obvious: if you pic numbers that are too small, your visitors can not figure out what will be shown and therefor not care to click on the thumbnail to see the full pic. There is no ideal setting for the thumbnail size, as it greatly depends on the subject of your gallery, however you should use between 50 and 250 pixels as a rule of thumb.
  If you upload a file that is smaller in terms of dimensions than the width/height you have set up for the thumbnails in coppermine's config, the creation of a thumbnail will be skipped and the original will be used as thumbnail representation instead.
• Intermediate (normal)
  The intermediate image is being created unless you have turned the option "Create intermediate pictures" off or if the uploaded image is smaller or equal in terms of dimensions than the width/height you have specified for the Max width or height of an intermediate picture. The intermediate image is being used mainly to be displayed on the intermediate image page (displayimage.php) that the user sees when clicking on a thumbnail. The intermediate image page can contain all types of additional information about the pic (like the uploader name, title, description, meta data etc.) and has navigation controls to allow the visitor to directly jump to the previous/next image within an album without having to go back to the thumbnail page first. Additionally, the intermediate image page contains controls for user interaction (like voting and comments if you allow this level of interaction).
  The main benefit of having an intermediate image is the fact that it is designed to fit on the screen of all your visitors, no matter what resolution they have. This will result in a seamless browsing experience for your users. It's advisable to use a "safe" value for Max width or height of an intermediate picture that makes sure it will fit on the screen (even with all the additional controls on that page). As the amount of space the controls need depends on the theme you use and you can't actually be sure of the screen resolutions of your visitors, it's advisable to use dimensions for the intermediate image that are between 400 and 800 pixels.
  The creation of intermediates will also speed up the page load, especially for users with slow connections, but of course the additional intermediate images take up webspace as well. Turn the creation of intermediate images off only if you're short on webspace. The intermediate image is being stored in the same folder where your uploaded original resides in and is being prefixed with "normal_" out of the box. You can change that prefix in coppermine's config, although it's advisable to keep the default.
  Examples:
  Let's say you have set the max. dimensions for intermediates to 400 pixels. You (or one of your users if you allow them to upload) then uploads an image named "mypic.jpg" that is 800 pixels wide and 600 pixels high. An intermediate image will then be created during the upload stage that is named "normal_mypic.jpg" with resolutions 400 x 300. Another image is then being uploaded named "foobar.jpg" that is 1024 by 768 pixels: again, an intermediate image will be created named "normal_foobar.jpg" that will again be 400 by 300 pixels in dimensions. A third image is being uploaded named "hugepic.jpg" with the dimensions 1280 by 800 pixels. The resulting intermediate image ("normal_hugepic.jpg") will be 400 by 250 pixels. You'll note that the dimensions of the third intermediate image in this example differs from the other two. The reason is that the creation of intermediates respects the aspect ratio of the original. However, your visitors will, when browsing the album that contains our three example pics always see an image embedded into the page that is 400 pixels wide, so the page controls will always remain visible no matter what, without a horizontal scrollbar appearing in the browser window that forces the visitor to scroll a lot.
• Original
  The original pic will be displayed in a pop-up when a user clicks on the intermediate image if the original as actually larger in terms of dimensions than the intermediate image.
  Example:
  Let's say you have set max intermediate dimension to 400 pixels and that you allow larger files to be uploaded. Two files then get uploaded: file "first_pic.jpg" is 800 by 600 pixels, file "second_pic.jpg" is 400 by 300 pixels. If a visitor is then looking at the intermediate image display for file "first_pic.jpg", he/she can click on the intermediate image and a full-size will pop up. When he/she looks at "second_pic.jpg" embedded into the intermediate image page, clicking on the intermediate image will have no result, as showing the original in a pop-up wouldn't make sense: the intermediate image display already displays the image in the greatest resolution that is available.
  You can instruct coppermine never to resize the original-sized image that gets uploaded initially and therefor (at least in theory) preserve the originals in an unmodified manner, however this has serious drawbacks: with modern digital cameras being capable to create pics that are larger in terms of dimensions than what will fit on your visitor's screens, the full-size pop-ups will not fit on the screens of your visitors, forcing visitors to scroll a lot. Additionally, huge pics will eat up a lot of webspace and will result in slow loading for visitors with small bandwidth connections.
  Therefor, Coppermine comes with the option to resize the original images as well on upload to a certain max. resolution - it's is strongly recommended to use this option both for admin uploads as well as regular user uploads. The option resides in Coppermine's config an is named Auto resize images that are larger than max width or height. Recommended values range between 800 and 1200 pixels. In this documentation, we will refer to those images as "originals" as well even if coppermine has initially resized them as well during upload. Technically speaking, they are no longer originals, but resized copies, but as this option was added way after the initial release of the first coppermine version, the documentation will refer to those files as originals. The originals are being stored without a prefix, using the file name that was used by the uploader. The file name is only being changed if it contains forbidden, non-websafe characters specified in coppermine's config option Characters forbidden in filenames.
  

Coppermine is using image libraries (either GD or ImageMagick) that need to exist on your webserver already to actually create the resized images (see "minimum requirements"). Those libraries are not capable to resize videos nor will they preserve meta data like EXIF or IPTC. That's why thumbnails and intermediate images can only be created for the image types supported by the image library you use.

There can be issues with resizing huge pics, as resizing consumes resources on your webserver. Refer to the section "Upload troubleshooting" of the docs if you have issues with larger files (or with getting uploads to work in the first place).

Your admin account

It's mandatory to have your admin account configured properly and to memorize the admin account data. Coppermine even provides you with the option to retrieve a lost password, but for this, you have to configure an email address for every account. When users sign up, they have to enter an email address, so this should not be a problem. However, the admin account that you created during setup doesn't have an email account yet. You should go to your profile when logged in as admin and specify a valid email address for the admin there - this way, you can later request a new password if you forget it.

To make this absolutely clear: there are at least two places where you must specify an email address in Coppermine:

• the first place is the config option "Gallery administrator email". Coppermine will use this address as "from"-address when sending emails (e.g. during registration). It's mandatory to have this email address populated properly. If you have your own domain, it might be a good idea to use an email account that correlates to your domain name.
  Example: if your domain name is "example.com", you should create an email address named gallery@example.com and use that email address in coppermine's config. Coppermine does not create that email address for you!
• the second place is the profile of your admin account: you should set up an email address for that account as well. This could be any sort of email address - provided it is one that you actually constantly monitor.

It won't hurt if those two email addresses are the same: they can be the same or they can differ. Just make sure to populate both.

Check uploads

Before actually promoting your coppermine gallery publicly, you should make sure that uploads work as expected, as they are the most common issues users have, caused by the huge amount of factors that have to be taken into account. Review the upload troubleshooting section if you have issues.

Consider bridging

Coppermine was designed to be used as standalone application in the first place. However, many people wanted to integrate it with another app, so starting with cpg1.1.x coppermine came with a mechanism that allowed users to bridge coppermine with another app in terms of user management. The main advantage is giving your site visitors a single sign-on for your overall site (e.g. both in your gallery and your forum), so they don't have to sign in twice and memorize two different logons.

Bridging does not integrate coppermine visually into your home page (you have to create a custom theme to accomplish this).

You can enable (or disable) bridging at any time, but you should make up your mind on bridging when installing Coppermine in the first place, because there are some issues that have to be taken into account: if you already have users inside your coppermine database when enabling bridging, the correlation between those initial coppermine users and the "new" users from the app you bridge with gets lost. As a consequence, there will be no more correlation between things your "old" users did (uploading pic, posting comments etc.) and the "new" users from the bridge.

To circumvent those future issues, you should make up your mind when installing coppermine: do you want to allow user interaction? Do you plan to offer a bulletin board later (or any other application that keeps track of users)? If your answer is "yes", or "maybe", then it's advisable to enable bridging before actually promoting your site publicly and starting to let users in.

Read up details in the bridging section of the docs.

What are your visitors allowed to do?

Coppermine can be used for a variety or purposes: some use it to display their personal files to everyone on the internet, others want only a limited number of users to be able to access the site for viewing only and no interaction at all. A large number of webmasters want to create a community site, where users can participate by uploading files, comment on other's files and rate them.

You can use Coppermine in all those setups (and a mixture of it), but you should be aware of the possibilities and limitations first:

Users "inherit" their permissions from the group they're in. That's why many settings in Coppermine are set per group. This way, you can have several levels of permissions. Set permissions by group using the group control panel

Change your coppermine's design

You can change some layout and design aspects (e.g. displaying random thumbnails on the index page) in the corresponding config section. Coppermine comes with a theme engine that allows you to customize the look of your gallery. You can choose one of the themes that come with Coppermine or you can download user-contributed themes from the downloads section of the Coppermine homepage. Based on the available themes you can customize your individual theme to make your site look unique and make your gallery match the overall look of your site.

Typical setups

There are a lot of configuration options built into coppermine - use them wisely. As many users ask for a typical setup (although there is no such thing as the typical setup that fits for anybody), here's just a couple of them:

Single uploader without user interaction (Monolithic gallery)

Only one uploader (you) and little or no user interaction
If you're going to be the only uploader and want little or no user interaction at all, disallow your site's visitors anything you don't want them to do. This is usually the case if you're an artist or photographer: there is no community building behind your gallery - you just show to the public what content you have.

• Disable new user registration in coppermine's config (Configuration → Registration → Allow new user registrations). This will disable the "register" link in the navigation. Users manually going to the registration page will see a message telling them that they are not allowed to perform this operation
• Disable creation of new albums for users (Groups → Row "Registered" → Personal gallery → Allowed = no) in case you haven't disabled the registration from the start and there are some leftover users registered.
• Disallow visitors to upload by going to the groups control panel and setting "Public albums upload" to be not allowed: Groups → Row "Guests" → Public albums upload → Allowed = no. If guests (or any user group) is disallowed to have personal galleries and to upload to public albums, the "upload file" link in the navigation will no longer be displayed.
• If you don't want your visitors to interact by rating, turn rating off on the groups control panel for the guests/anonymous group: Groups → Row "Guests" → Permissions → Rating = no. If rating is disabled, users won't see the rating stars where they could vote.
• If you don't want your visitors to post comments, turn comments off for guests: Groups → Row "Guests" → Permissions → Comments = no.
• If you don't want your visitors to send ecards, disable the sending of ecards in the groups control panel as suggested above: Groups → Row "Guests" → Permissions → Ecards = no

Single uploader with user interaction

If you're going to be the only uploader, but you want to build a community around your site, with visitor registering, posting comments etc., just turn off uploads for your users, but turn on all the other feature that you want to allow:

• Turn off all kinds of uploads for guests as well as registered users:
  • Groups → Row "Guests" → Personal gallery → Allowed = no
  • Groups → Row "Registered" → Personal gallery → Allowed = no
  • Groups → Row "Guests" → Public albums upload → Allowed = no
  • Groups → Row "Registered" → Public albums upload → Allowed = no
• To avoid comment spam you should disallow comments for guests, but allow those features for registered users:
  • Groups → Row "Guests" → Permissions → Comments = no
  • Groups → Row "Registered" → Permissions → Comments = yes
  • To fight comment spam you should enable comment approval and/or captcha for comments.
    To enable comment approval, go to coppermine's config and change the corresponding setting: Configuration → Comment settings → Comments require approval.
    Additionally (or alternatively), you should enable captcha (a sort of image that displays scrambled, random letters that the visitor has to read and enter into an input field to prove that he is human and not just a silly bot script) for comments as well: Configuration → Comment settings → Display Captcha (Visual Confirmation) for adding comments
• Allow visitors to rate your content: you enable rating on per group level. Therefor, go to the groups control panel and allow rating for all possible groups:
  • Groups → Row "Guests" → Permissions → Rating = yes
  • Groups → Row "Registered" → Permissions → Rating = yes
  You have to understand though that this is not all: think of those per-group settings as a general on/off switch. You can fine-tune those settings per individual album: you can allow rating in one album and deny it in another one. Go to the album properties of an individual album to allow/disallow ratings for this particular album.