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

Table of Contents

Getting started

Here's a list of issues that beginners often have issues with, so please just read this list one by one:

Basic concepts

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

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

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

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

Some settings have a serious performance impact as well and should be considered thoroughly, especially when you're on cheap shared hosting or even free hosting.

Category, albums and file structure

The Coppermine Photo Gallery works in the following way:

If you do not plan to have many albums, you likely would not 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 gallery.

There is, however, a special category named "User galleries". This category cannot 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.

The following resized files are generated when uploading an image:

Coppermine uses 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 able to resize videos nor will they preserve meta data like EXIF or IPTC. That is 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).

Recommended resizing setups

You need to understand that changing the resizing settings will only have an impact for the images added from that point on. Images that already existed when you changed the config sections will not automatically be resized accordingly - instead, you have to trigger a re-resizing process using the corresponding option "Update thumbs and/or resized photos" from the admin tools and loop through all albums with the new settings in place.

No full-size pop-ups

If you don't plan to use full-size pop-ups at all, i.e. if the images should always be displayed embedded into your Coppermine output, you can set up coppermine to save webspace with a setup like this.

You have to understand that you need to catter for the visitors with the smallest resolution. If you expect your visitors to have a resolution of 1024 x 768 pixels or better, you should set the width of the embedded images to 800, as you will need room for whitespace and page controls as well.

Let's assume for this example that the max size your visitor should be able to see is 800 pixels.

Go to coppermine's config and set:

Above mentioned settings are the most efficient ones if you plan to disallow full-size pop-ups, as they safe as much file space as possible and make it impossible for visitors to get the full-sized images in larger resolutions.

Allow full-size pop-ups with maximum space saving

"Create intermediate pictures" to "no" in config will not result in a gallery where you don't have intermediate-sized images at all that are embedded into the output; instead, the full-size pic will be displayed and re-sized by HTML mechanisms instead. This option is recommended if the majority of your pics will be viewed in full-size resolution anyway: this way, the browser will already cache the image and the full-size pop-ups will open very fast.

Not creating intermediate images will of course have an impact on the webspace saved: no intermediate image created will of course safe some space. However, if you're concerned about webspace consumption, you better consider limiting the "Max width or height for uploaded pictures/videos" and enabling the resizing of images to those dimensions (option "Auto resize images that are larger than max width or height") - modern digital cameras create images with enourmous dimensions and therefore huge storage space usage. Resizing those images to dimensions that make sense on the web makes sense for nearly all gallery purposes.

Example setup:

"Regular" setup with moderate file space consumption

If you have enough web space and bandwidth and your visitors have decent bandwidth, it's recommended to enable the creation of intermediate images and allow full-size pop-ups for those users who want to see the detail.

Example setup:

Your admin account

It is 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 does not 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:

It would not hurt if those two email addresses were the same: they can be the same or they can differ. Just make sure to populate both.

Uploading permissions

In Coppermine, the permission to upload files is being determined on group membership level. Therefor, you assign the privilege to upload on the group control panel per group the visitor is in. Generally speaking, there are the following possible setups (per group):

Check uploads

Before 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 a huge amount of factors that have to be taken into account. Review the upload troubleshooting section if you have issues. Don't take for granted that uploads will work as expected - test thoroughly, especially if you allow your users to upload.

Consider bridging

Coppermine was designed to be used as a standalone application. 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 do not 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 instead). All that bridging does is integrating Coppermine and the bridging app logically as far as user management and the sign-on process are concerned.

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 is 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 others' 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 are in. That is 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 gallery'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 are just a couple of them:

Single uploader without user interaction (Monolithic gallery)

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