Coppermine Photo Gallery v1.4.12: Documentation and Manual

About Coppermine

Coppermine Photo Gallery is an advanced, user-friendly, picture gallery script with built-in support for other multi-media/data files. The gallery can be private, accessible to registered users only, and/or open to all visitors to your site. Users, if permitted, can upload pictures with their web browser (thumbnail and intermediate sized images are created on the fly), rate pictures, add comments and even send e-cards. The site administrator determines which of the features listed above are accessible by registered and non-registered users. The site administrator can also manage galleries and batch process large numbers of pictures that have been uploaded onto the server by FTP.

Image files are stored in albums and albums can be grouped into categories, which in turn, can be further grouped under parent categories. The script supports multiple users and provides the administrator of the website with tools to manage which user groups can or cannot have personal albums, send ecards, or add comments. Users may also upload to public albums if the website administrator permits it. Permissions to create albums, upload and delete files are all determined by the website administrator.

Coppermine has an optional user selectable theme system with a number of themes pre-installed. It also supports the use of multiple languages and contains it's own language library. These language files provide, users of your gallery, access in their preferred languages. Coppermine uses PHP, a MySQL database, and either the GD library (version 1.x or 2.x) or ImageMagick to generate and keep records and file information of all thumbnails, intermediate, and full-sized images. Coppermine generates the html code necessary to display its various categories, sub-categories, albums, intermediate, and full-sized image displays dynamically. This drastically cuts down on the number of files and space your gallery would require using standard HTML. The install script (install.php) makes it quick and easy to get started.

1. What is required

There are certain minimum requirements that need to be met in order to be able to install Coppermine:

• A web server that supports PHP
  PHP (version 4.2.0 or better), either compiled with the support for the GD library or permission to use the exec() function for the ImageMagick "convert" utility in order to make thumbnails and reduced size images. Mysql support needs to be compiled into PHP as well.
• A MySQL database
  You will need MySQL version 3.23.23 or better. MySQL 4.1 is recommended, MySQL 5 is supported. The MySQL user needs permissions to perform CREATE, ALTER, REPLACE, SELECT, UPDATE, DELETE, INSERT data from the database. Most users have these permissions when webhosted. If you don't have them, you will not be able to use this or any other pre-made scripts at all. If you are uncertain about your permissions, please check with your webhost. Most hosting services can probably tell you whether coppermine can or cannot be run on their servers.
  A database needs to be set up that Coppermine can use - the install script will not create a database for you, but it will automatically create the tables and data structure in your database during install. In most webhosted environments, you will already have at least one database set up for you by your webhost. If not, you will need to create one. If you do need to create a database, check with your webhost on the proper procedures for doing so. Write down your database name, userID and password. You will require all three to successfully install Coppermine.
• An image library:
  Either GD version 1.x or 2.x (PHP has to be compiled to support it) or ImageMagick.
  (see What's ImageMagick and What is GD)
• It's always a good idea to contact your webhosting service first and ask them if they are aware of any known issues when installing Coppermine.

Although Coppermine can be run on any webserver that has the minimum requirements mentioned above, the Coppermine dev team can not support you on setting up your webserver in the first place. As suggested, those are requirements, i.e. they have to be met before actually considering to run Coppermine. Please note that the Coppermine group does not recommend self-hosting unless you're an experienced webserver administrator and know your way around.

Back to top

2. Installation and Setup

2.1 How to install the script

• Unpack the archive preserving the directory structure.
  You can rename the coppermine folder, but not the files or folders within.
• Upload all files onto your webserver (making sure to use the correct ftp mode)
• Set permissions on the "albums" and "include" folders in your Coppermine directory. Usually, you have to apply the CHMOD command, setting the permissions to 755 (or 777, depending on your server config). This step is very important and must not be overlooked!
• Ensure you have correct information about your database - you need to know the database name as well as the details of a MySQL user account with which Coppermine should connect to the database. The database and the username must already exist, and the user must have access to the relevent database. Coppermine will not create the database for you, but it will create the tables in the database during installation, there is no need for you to add any tables yourself.
• Run the install script on your server
  Type the following URL into your web browser:   http://your_server/coppermine_dir/install.php   (your_server = your website, coppermine_dir = the folder in which you uploaded your Coppermine files.) Follow the online instructions on the install screen inserting the necessary information as requested.

Back to top

2.1.1 Setting permissions

• during install, coppermine needs to create and write to the file "config.inc.php" in the "include" folder in order to store the necessary mySQL access data to run coppermine and to create and write the "install.lock" file, also in the same folder to prevent the installer from being run a second time after a successful install.
• when using http uploads, coppermine needs to write the files that are being uploaded into the subfolders that you or your users create in the coppermine albums folder
• regardless of the upload method, coppermine will create a thumbnail file and an intermediate file (if you have configured coppermine accordingly) and store it in a sub-folder in the "albums" directory, as well
• If you are going to enable logging at some stage, the script needs write access on the folder "logs"
• The "plugin" folder needs to be set to write access as well if you want to use the zip upload capabilities of the plugin manager

By default, files and folders on a webserver are usually not writable, so you will probably have to change permissions before installion, for the reasons mentioned above. It's really mandatory that you set/change (CHMOD) permissions - or you will run into issues sooner or later.

To be able to set permissions correctly, you have to understand how they work: there are read, write and execute permissions (abbreviated with rwx) for each folder and file. Permissions on a parent folder can propagate to a child folder or the files within it, but it's possible to tweak your setup so that unwanted permissions will not propagate to child folders and resident files.

However, there are differences between the different operating systems that are used as webservers. As a result, there are a number of different approaches. As coppermine is designed to run on many different setups, we've included some basic instructions. Those who know their way around may find these instructions somewhat generalized and lacking in details.
Note: it is not your local, client computer that matters, permission-wise, but, rather, the operating system used by your webserver. If you're not sure what OS your server is running on, try the CHMOD instructions first - most webservers run a version of Unix/Linux. If you can't figure how to set permissions properly, ask your webhost for support.

Back to top

2.1.1.1 Apache on Unix/Linux (CHMOD)

• Basics
  There are different flavors of Unix/Linux - all of them share a similar, somewhat common approach. In referring to this architecture, the word "Lunix" is used for both Unix and Linux derivates. "Read" permissions apply to files that are not actively run, but only being served, e.g text or plain html files. "Write" permissions are needed to dynamically create files, modify or delete them. "Execute" permissions are needed to run executable files, for example, script files like PHP. To serve web pages that are php-powered properly, the most basic permissions that are needed, therefore, are "read" and "execute" (abbreviated as r-x).
  Possible permissions settings are:
  • r-- ... read only
  • r-x ... read and execute
  • rwx ... read, write and execute
  Needless to say, other combinations are technically possible (such as -wx, --x or -w-), but they make little sense in webserver setups and will be ignored in this tutorial.
• Groups in Lunix
  Lunix uses a set of three-group permissions, each of which can be applied independently. These are: owner, group and world. Using this set, you can dictate if a user who owns a file has permission to modify or delete it (write permission) while other users will only be able to read/view and possibly execute the file. On your server, these permission settings for the three possible groups are written in as a single line entry (in the order "owner", "group", "world").
  Examples :
  • rwxrwxrwx ... read, write and execute (rwx) permissions for all three groups
  • rwxr-xr-x ... rwx permissions for the owner, r-x permissions for all others
  • r-xr-xr-x ... read and execute permissions for all groups, only
• Webserver daemon
  Even though you (the user who owns the files on your server and who has control over the permissions) may be able to access a file (e.g. using your FTP app), the coppermine script may not be able to do so. This is often caused by a particular setup option for servers: services (in Lunix often called "daemons") may run in the context of a specific user that is different from the user who is allowed to access the files. On many such servers, the webserver (apache) service runs as user "nobody". This way, the server can be protected against hacker attacks. Therefore, setting permissions on a server for the "owner" only does not work on these particular setups, you must set permissions for both "group" and "world" (at least for the group the webserver daemon is in).
• Binary arithmetics
  As you can see, permissions can be either "on" or "off" - this is the equivalent to the two different states that a bit of data can have in binary arithmetics (and therefore, also in the whole world of computing). As we have three types of different permissions (read, write, execute), we will need three bits to assign a set of permissions. The highest bit is the "read" bit - decimal "4" is used to represent it. The middle bit "write" is assigned to decimal "2", the lowest bit "execute" is represented by decimal "1". This may be a bit hard to understand or follow at first, especially if you haven't dealt with binary arithmetics before. If you would like to learn more, google for it. It's easier to understand if you look at some examples:

  permission	bit value	set?	value
  read	4		4
  write	2		2
  execute	1		1
  sum (resulting byte value)			7

  permission	bit value	set?	value
  read	4		4
  write	2		-
  execute	1		1
  sum (resulting byte value)			5

  permission	bit value	set?	value
  read	4		4
  write	2		2
  execute	1		-
  sum (resulting byte value)			6
• What good is all of this?
  Instead of having to remember and write rwxrwxrwx for each file or folder in your setup, you can now write 777 in its place. The same applies for rwxr-xr-x, you can write 755, instead.
• FTP application
  Setting the permissions using your FTP application will be the option available for most users who are webhosted. Depending on the FTP app you use, the user interface will slightly differ: some apps will allow you to enter the CHMOD command by entering the numbers (777 or 755), others will provide you with checkboxes where you can tick the permissions separately for each group. More advanced FTP apps may even provide you with both mechanisms. As this documentation can't cover all individual FTP apps that are available, the exact method might differ a bit from what you have.
  Your FTP app will probably have two windows, one showing your local files, the other one showing the files on your server. In the window that shows the remote files on the server, navigate to the folder your coppermine files reside in. Highlight the "albums" folder that resides within the coppermine folder. From the context menu (right-click!), choose "properties" (might be named "chmod" or similar as well). The permissions dialog will then pop up. Choose the proper permissions as suggested above (777 or 755, depending on your server setup). If you have a checkbox that enables the permissions to propagate for all sub-folders and files, tick it. If you don't have it, nevermind. Then click "OK" on the dialog box to apply the permissions. Keep in mind that your FTP app might not have the power to actually find out about the current permissions that are applied, so you mustn't trust the information displayed in the dialog box: even if it appears that the permissions are already set as needed, this may not be the case, so you should re-apply the permissions no matter what.
  After having applied the permissions for the albums folder, do the same thing for the include folder that resides within your coppermine folder.
• Website control panel
  Some webhosts may not give you the option to access your site using FTP, or they may not allow your FTP client to execute the CHMOD command. If this is the case, you probably have a server setup interface (e.g. cpanel) to apply permission to folders and files. In fact, this doesn't matter, the method for applying permissions doesn't differ from the one described above in the section "FTP application": navigate to the albums folder and apply the permissions needed to give your webserver write access to all files and folders within the albums folder. Do the same thing for the include folder as well.
• Shell access
  If you have shell access to your server, you can apply the native CHMOD command on your files and folders. Go to your coppermine folder using your shell access, then apply the permissions to the albums and include folder and everything within it. As explained above, the user the apache daemon runs under needs write access, so you should CHMOD to 777 or 755, depending on your server setup.

Back to top

2.1.1.2 Apache on Windows

You have to understand that there is no such thing as CHMOD on Windows operating systems - this command is available on Unix/Linux only, even if your FTP application displays a CHMOD option. If you try to apply CHMOD on Windows, the command will simply be ignored and do nothing. However, there are permissions on Windows as well.

The apache webserver service runs under a particular user - if you have full access to the server, check the services control to find out which one it is. If you can't do this, ask your webhost.

As a temporary workaround, set permissions on folder and file level as suggested in the section IIS on Windows, but not for the IUSR (which only exists on IIS), but for "everyone". However, allowing "everyone" to have read, write and execute permissions might be a security risk and is not recommended at all.

Back to top

2.1.1.3 IIS on Windows

Pre-requisites: you will need full admin privileges over your server to execute this process. If you do not run the webserver yourself, your webhost has probably set up a web-based interface to let you change permissions. If you're not sure, contact your webhost.

The dialogs may differ slightly depending on the Windows version you have:

• Start Windows Explorer on your webserver and navigate to your coppermine folder
• right-click on the folder you want to change permissions for
• Choose "Properties"
• On the properties dialog, click on the "Security" tab
• Highlight the user "Internet guest account (hostname\IUSR_hostname). If it's not there already, use the "Add..." dialog to add this particular user
• Tick the "Allow"-checkbox for "Write"-access
• Click the "Advanced" button
• Just to make sure the write access propagates to all folders and files within the folder you're currently editing, tick the checkbox "Reset permissions on all child objects and enable propagation of inheritable permissions"
• click "OK"
• answer the confirmation dialog box that asks you if all permissions should be replaced with "Yes"
• depending on the number of child objects and your system's speed, wait until the permissions of all objects have been changed and the status window goes away.
• Click "OK" to close the permissions dialog

You have to understand that there is no such thing as CHMOD on Windows operating systems - this command is available on Unix/Linux only, even if your FTP application displays a CHMOD option. If you try to apply CHMOD on Windows, the command will simply be ignored and do nothing. However, there are permissions on Windows as well.

Back to top

2.1.2 The install screen

Back to top

2.1.3 What the installer does

After performing some basic checks, the installer creates the needed database tables for you and fills theof them fail to do so properly, which results in frustration both for users as well as supporters. To make this absolutely clear: the above mentioned steps are absolutely mandatory, no matter what skill level you have, no matter what upload method you have troubles with. Failing to do exactly as suggested will result in your request for help being ignored. Yes, this applies to you. We mean it!

Back to top

4.12 The gallery configuration page

This is where you will configure the most important parts of your coppermine gallery. Some settings have an impact on the files you upload - changing the ( * ) astericked options after you have alreaded added a large number of files in your gallery can be a difficult undertaking. For this reason, it is important that you spend time with your coppermine setup at the early stages of gallery development to get those settings exactly the way you want them, before actually uploading too many pics or listing the gallery to the general public.

4.12.1 General settings

Gallery name

Enter the name of your gallery in this text field. The name you enter will appear as the title that is displayed in the web browser's title bar and is also displayed in many of the different theme templates.

Gallery description

Enter a short description of your gallery in this text field. This description is also displayed in some of the theme templates just below the name of your gallery.

Gallery administrator email

All emails sent by the gallery will be sent using this email address. This must be a valid email address.

URL of your coppermine gallery folder

This is the URL where a user will be directed to when s/he clicks on the "See more pictures" link in an e-card. This must be the URL to the root of your coppermine installation followed by a forward slash (just the path to your coppermine folder, e.g. http://yourdomain.tld/coppermine/). Do not specify a specific file (such as index.php) or subfolder within the coppermine gallery in this field.

In previous versions of Coppermine, this field was called "Target address for the 'See more pictures' link in e-cards", but as this url is now being used for other functions in coppermine, it has been changed, appropriately.

URL of your home page

This is the URL where a user will be directed when he clicks on the "Home" button in the main menu.

You can use "/" for the root of your domain, "index.php" for your gallery's default starting page, or any other valid URL. By default this is "index.php".

[cpg1.4.0 or better required]

Allow ZIP-download of favorites

When enabled, users of your site may download files that they previously saved into their favorites collection. These files are dowloaded from the user's "My favorites" page and saved onto their computers in a zip-file format. This option requires zlib to be installed on your server (run phpinfo to check if this php library file exists on your server).

[cpg1.3.0 or better required]

Timezone difference relative to GMT

Specify the time zone difference between your local time and the time zone your webserver is in. This value will be used to adjust time stamps in ecards and other places.

[cpg1.4.0 or better required]

Enable encrypted passwords

This option affects changes on user passwords that are stored as plain text in your database (this is the case if you have upgraded from previous versions of coppermine that did not have this feature). It will encrypt all passwords in the database, and all future passwords will be stored encypted as well. This process can not be reversed: once encryption in turned on, it can not be turned off, so use this option only after giving it some serious consideration.

This option increases user security in coppermine, but comes with a drawback inherent to this method: even the admin will not be able to recover a lost password of a user (or his own password). The password can only be reset to another value using the "I forgot my password" option during login.

[cpg1.4.0 or better required]

Enable help-icons

Enables the display of help icons in various sections of the coppermine admin pages. When enabled, make sure you have also uploaded the "docs" folder into your coppermine folder on your webserver.

If you choose to set this to "Yes: everyone", logged in (registered) users will be able to see the help icons in strategic locations as well, e.g. when creating a user gallery.

As the help text is based on the documentation that comes with coppermine, it is available in English only. If the native language of your user(s) is not English, it is advisable to set this option to "Yes: admin only" to avoid confusion among your users.

It is strongly recommended that you do not disable the help icons altogether: even though you feel that you know your way around in your Coppermine install, the help icons might help you with the functinos of a new or unfamiliar option later.

[cpg1.4.0 or better required]

Enable clickable keywords in search

When enabled, a list of all keywords entered in the "Edit files" page will appear at the bottom of the search page, with each keyword being a clickable search link. Enabling this option is recommended only if you have a small number of keywords in use (e.g. less than 100) - it will provide your users with some ideas as to what they could be searching for in your gallery (in addition to the standard full-text search). Please note that enabling this option for a large list of keywords (e.g. thousands of keywords) can slow down the search page considerably and may be confusing for new users and visitors to your site.

[cpg1.4.0 or better required]

Enable plugins

Enable or disable plugins, with a link to the plugin manager. This is a brand-new feature of coppermine. This feature allows advanced copperminers to create plug-ins that can control the way coppermine looks and behaves without modifying the inherent code of the script itself. We anticipate many exciting, user-contributed, plug-ins in the near future. More details can be found in the plugins section of this documentation. Since plugins add on to the core Coppermine system, if you are having problems, try to disable all plugins using this setting to see if a plugin may be at fault. If so, you can then enable all plugins here, then uninstall or install one plugin at a time in the plugin manager to figure out which one is at fault.

[cpg1.4.0 or better required]