Getting started
Here's a list of issues that beginners often have issues with, so please just read this list one by one:
- Use the "Album Manager" ("Albums" link in the admin menu) to create and order your albums. You will need at least one album in which your files can go.
- Use the anonymous/guest group to define what non-registered users (aka guests) can and cannot do (in the groups panel).
- Use the properties of an album to modify its description and permissions. The album properties dialog is accessible by clicking on the "Porperties"-button next to a thumbnail that represents an album.
- In order for a user to be allowed to upload a file into an album, two conditions must be met:
- The user must be part of a group that can upload files.
- There needs to be at least one album where the file can be uploaded to permissions-wise. This is the case if
- There is at least one album within a public category (this can be the root category as well) where "Visitors can upload files" has been set to "Yes",
OR
- The user has created an album in the 'user galleries', if he's allowed to do so.
- The same applies to picture rating and comment posting: the group the user is in must have the general permission to rate / post comments and there needs to be at least one album where the corresponding permission-by-album has been turned to yes. Permissions by album can be set using the album properties dialog.
- If you have installed the gallery script successfully 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.
- Throughout the documentations, the word "visitor" is being used for any person accessing a page (logged in or not logged in). "Visitor" does not equal "guest". Guests as well as registered users are visitors.
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:
- Files are stored in albums
- Albums are organised in categories
- Categories can be nested (into subcategories)
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:
-
Thumbnails
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 did not create the thumbnail and displayed 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 therefore the thumbnail page loads very fast. The drawback of small dimensions are obvious: if you pick numbers that are too small, your visitors cannot figure out what will be shown and therefore would not care to click on the thumbnail to see the full picture. 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.
-
Intermediates
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 picture (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 visitors, no matter what resolution they have. This will result in a seamless browsing experience for your users. It is advisable to use a "safe" value for Max width or height of an intermediate picture that ensures 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 cannot actually be sure of the screen resolutions of your visitors, it is 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 are 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.
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.
-
Originals
The original picture will be displayed in a pop-up when a user clicks on the intermediate image if the original was actually larger in terms of dimensions than the intermediate image.
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 would not 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 therefore (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 visitors' 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.
Therefore, Coppermine comes with the option to resize the original images as well on upload to a certain maximum resolution - it is strongly recommended to use this option both for admin uploads as well as regular user uploads. The option resides in Coppermine's config and 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 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:
- "Create intermediate pictures" to "no"
This way, the full-size image will be used on the displayimage screen as well
- "Max width or height of an intermediate picture/video" to "800"
This will take care of the resolution you will see of the embedded pic on the displayimage screen
- "Max width or height for uploaded pictures/videos" to "800"
This would result in an error message if your users tried to upload images with a bigger resolution if you disabled the next option "Auto resize images that are larger than max width or height" to "No". However, if you set "Auto resize images that are larger than max width or height" to yes, all uploads will be resized to what you have set in "Max width or height for uploaded pictures/videos (pixels)"
- "Auto resize images that are larger than max width or height" to "Yes:Everyone"
As suggested above, you need to set this to "Yes" to make sure that users don't get an error message when uploading bigger pics than they're suppossed to. Coppermine will then resize the images on the server if needed
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.
"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.
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):
-
No uploads possible at all
-
Turn off all kinds of uploads on the group control panel for the group in question
- Groups → Row corresponding to the group → Personal gallery → Allowed = no
- Groups → Row corresponding to the group → Public albums upload → Allowed = no
-
User can upload to particular albums in admin-created categories only, but can not create albums
-
Enable public album upload on the group control panel for the group in question
- Groups → Row corresponding to the group → Personal gallery → Allowed = no
- Groups → Row corresponding to the group → Public albums upload → Allowed = yes
-
You will need at least one album where uploads have been allowed. Go to the album properties of the album in a public category that the user is meant to upload to.
- Album properties → Visitor can upload files = Yes
Repeat this if you want to allow uploads to several albums out of the box.
-
User can upload to particular albums in admin-created categories and can create albums inside particular categories
-
Enable public album upload on the group control panel for the group in question
- Groups → Row corresponding to the group → Personal gallery → Allowed = no
- Groups → Row corresponding to the group → Public albums upload → Allowed = yes
-
Go to the categories control panel and determine the category (or categories) in which the user is suppossed to be able to create albums in
- Categories → Edit icon in the row that corresponds to the category you want to allow album creation in → Group(s) allowed to create albums in this category → Select the groups (to select multiple groups, press and hold the [Ctrl]-key)
By default, non-admins are not allowed to create albums in public categories, so you have to explicitely allow particular groups to create albums in a particular category.
-
User can create personal albums within his user gallery and can upload to those albums he created
When the user is allowed to upload to personal galleries, the following settings need to be applied.
- Groups → Row corresponding to the group → Personal gallery → Allowed = yes
- Groups → Row corresponding to the group → Public albums upload → Allowed = no
The user will then have an additional menu item labelled "Create / order my albums" where he needs to create one album first before being able to upload (unless the config option Configuration → Registration → Create user album in personal gallery on registration is enabled).
-
User can upload both to public and personal albums
A combination both of public as well as personal album uploads is possible as well: you can determine that a user can upload both to albums in public categories as well as personal albums within his user gallery section. Subsequently, on the groups control panel the following options need to be set:
- Groups → Row corresponding to the group → Personal gallery → Allowed = yes
- Groups → Row corresponding to the group → Public albums upload → Allowed = yes
The methods suggested above to allow uploads to particular albums using the album properties dialog as well as the discussed setting on the category control panel of course needs to be applied as well as suggested above.
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.
- 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 have not 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 do not 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 will not see the rating stars where they could vote.
- If you do not want your visitors to post comments, turn comments off for guests: Groups → Row "Guests" → Permissions → Comments = no.
- If you do not 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 are 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. Therefore, 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
Please 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.
Multiple uploaders without new registrations (closed group)
Usually this setup is used if you are going to have a comparatively low number of users who will be uploading, but a larger number of people who are suppossed to see your galery's content. This is often the case for clans, clubs or companies, where members are allowed to upload files, but the visitors of the page are just meant to browse those images without adding any new content. There is comparatively little difference to the previous setup "Single uploader with user interaction" except for the following:
- Configuration → Registration → Allow new user registrations = no that will make sure that no new users register. It's up to the admin to create the needed user accounts.
- The admin of course needs to set permissions for uploads for the registered users as well
Multiple uploaders with new registrations
In this setup we will go through a setup that may sound a bit confusing in the first place, but is something that a lot of gallery admins will want to accomplish: a gallery where everyone can register and where users can upload as well.
To build a commmunity around your website you will have to give your visitors an additional benefit for registering: registrations means putting an additional effort into the visit on your site, so there must be an additional thing that the visitor gets in return for his "work".
Here's a list of features that you might to consider to give to your registered users "as a reward" for registration (of course you need to disallow those features for non-registered guests to make this actually work):
-
Exclusive content for registered users
The best method to promote registration is real, exclusive content for registered users only. To accomplish this, set the access permission for one or several albums from "Everybody (public album)" to "Members of the 'Registered' group" using the option "Album can be viewed by" on the album properties screen.
-
Access level
Allow your registered users to see all image resolutions including the full-size image and restrict your guests to thumbnail and intermediate images only. Alternatively, allow your guests even less: only let them access thumbnails - for enything else, they will need to register (this is only an option if you have very good content).
Set the access level on the groups control panel.
-
Participation by uploading
Allow your registered users to participate in your community by allowing them to upload as well, while disallowing uploads for guests. Permissions to upload into punlic albums and / or to have a personal gallery is set on group membership level as well, that's why you assign those permissions in the groups control panel as well.
-
Ask your users for their opinion
On the groups control panel you can determine if a member of a particular group can rate the files in your gallery and if they can add comments to them. It's advisable to consider this carefully, as commenting often is subject to spam activities, which will in turn result in extra moderation effort for you as gallery admin.
-
Ecards
You might want to allow your users to promote your gallery by recommending it to their friends using the ecard feature. Again, this is being controlled on the groups control panel. However, the ecard feature in itself is a bit dated, as most visitors are aware how to send emails to their friends without using your services.
-
Contacting you
You can determine if a contact form should be available and wether guests are allowed to access it as well (or only registered users).
-
Alternative browsing
The sidebar can be an alternative way for your visitors to browse your gallery's content; you might want to offer that as a form of "reward" as well for registered users only.
If you should decide for one (or more) of the methods mentioned above, don't forget to tell your site visitors about those benefits - it doesn't help to grant your registered users additional privileges to promote registration if you fail to tell unregistered guests about those privileges in advance. To accomplish this, you can use the anycontent file with the example given there.