Coppermine Photo Gallery v1.4.18: 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:

1.1 Technical requirements

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

1.2 Personal requirements

Coppermine is aimed at webmasters who have at least basic HTML know-how and some experience in setting up pre-made scripts. The Coppermine dev team is aware that there are Coppermine users who set up their gallery using auto-installers who have little or no experience in setting up similar scripts, which is fine as well. We just ask you to read the documentation thoroughly before asking questions on the Coppermine support board, as this should answer most newbie questions. You can use coppermine just fine using the pre-made themes that come with the coppermine package. However, if you want to modify existing themes or come up with a theme of your own (that matches the look of the rest of your site), you should have basic to intermediate HTML and CSS skills.

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 them with default values. It creates the file include/config.inc.php within the coppermine folder on your server that stores the database details you entered during install. If you should change your mysql database details later (i.e. if you change the password of your mysql user account or if you migrate your gallery to another server), you will need to edit include/config.inc.php manually to reflect the changes. The file include/config.inc.php also keeps the install script from being run twice: if the installer is run, a check is performed wether the config file exists - if yes, the installer will stop and redirect the user to the index page.

Back to top

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

2.2.1 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
• 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
  

2.2.2 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 be 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.

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

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

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

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

2.2.7 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

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

Back to top

2.3 Creating or upgrading your own themes

Coppermine comes with a powerful engine that allows you to create your own theme, giving your gallery a unique look that matches the overall layout of your entire site. Other applications call them "skins" or "templates", well call them "themes".

There is a (constantly growing) number of user-contributed themes that can be previewed and downloaded from the Coppermine web site.

2.3.1 Themes that come with Coppermine

The Coppermine package comes with some pre-made themes:

• Classic
  The default theme with white background and a horizontal menu
• Eyeball
  A theme with a dark background and a horizontal menu that expands for user interaction features
• Fruity
  A colorful theme with a vertical menu on the left
• Hardwired
  A theme with a dark background and a smallish font size that works well for narrow space and smaller resolutions. Comes with two horizontal menus
• IGames
  A dark theme with 3D-effects and a horizontal menu
• Mac OX X
  A theme with light background and an expanding horizontal menu that resembles the look of a Mac
• Project VII
  A theme with white background featuring a horizontal expanding menu
• Rainy Day
  A theme with dark background and rounded edges
• Sample
  The sample theme would look identical to the classic theme. It will not be displayed using the theme selector - it is just meant as a template to copy from when creating or modifying your own theme.
• Waterdrop
  A theme with a light background and a "conventional" horizontal menu

2.3.2 Upgrading your custom theme

To upgrade an existing custom theme from cpg1.3.x to version 1.4.x, read the theme upgrade documentation.

You only have to upgrade your custom theme when upgrading between major versions (e.g. from cpg1.3.x to cpg1.4.x), as from one major version to the next, the theming engine is subject to changes. When only upgrading from minor versions to the next (e.g. from cpg1.4.x to cpg1.4.y), you don't have to update your custom theme.

The core themes that come with Coppermine packages don't need to be updated, as they should be replaced during the upgrade and therefor will contain all needed changes. However: if you have based your custom theme on one of the core themes that come with coppermine (e.g. the classic theme), pay attention to possible changes. As suggested below, it's advisable to rename your custom theme to make sure that it doesn't accidentally get overwritten when upgrading.

2.3.3 Content of a theme

Coppermine themes are stored in the "themes" directory, each consists of 3 primary files :

• "template.html" the main template in plain HTML.
• "style.css" the stylesheet associated with the template
• "theme.php" the PHP theme file

Additionally, there usually is a folder named "images" that resides within the theme folder (themes/theme_name/images/) that contains the images used by the particular theme (logos, bullets, backgrounds and other graphical resources needed).

2.3.4 The sample theme - a template to copy from

Your Coppermine installation also includes a "sample" theme directory. The "sample" theme includes each of these files but does not show up in the user selectable list of themes in your Coppermine display. Sample's theme.php also holds a copy of every themeable function and template for your reference. If you opt to use the "sample" theme to begin creating your own theme, you should follow the theme.php instructions in the "theme upgrade documentation" and begin with a blank theme.php.

To clarify: you mustn't edit the sample theme (as it will not be displayed), but copy the sections you want to see changed from it into your custom theme. Don't copy the whole content from themes/sample/theme.php into your custom theme, as this will only clutter your custom theme and will make upgrading very hard in the future. Instead, copy the sections you want to modify.

2.3.5 How the theme engine works

When a Coppermine page is being parsed, the core code will call theme functions. If those functions exist in your custom theme, they will be taken into account. If a particular function does not exist in your custom theme, the core function will be used. The core functions (the default theme behaviour if you want to put it that way) reside in includes/themes.inc.php. Therefor, you mustn't edit includes/themes.inc.php, under no circumstances, as all your changes will be lost when upgrading in the future. Everything that possibly could be accomplished by editing include/themes.inc.php can be accomplished by editing themes/yourtheme/theme.php as well - stuff defined in your custom theme will take precedence over the core theme functions.

2.3.6 Creating your custom theme

2.3.6.1 Rename your theme first

To create a new theme, the best solution is to use an existing one as its copy template. To do that, make a copy of the folder of the theme you want to use as a basis. Then edit the "template.html", "style.css" and "theme.php" files and replace all occurences of "themes/old_theme_dir" with "themes/new_theme_dir" in order for the links to point to the correct place.
Avoid using spaces and special chars in your custom theme name - only use alphanumerals and the underscore (_).

Also keep in mind that despite this file being located in the "themes/your_theme_dir" directory, it must be coded as if it was in the main directory of the coppermine installation. For example, in order to display an image, you must use <img src="themes/theme_dir/images/image.gif" alt=""/> and not just <img src="images/image.gif" alt=""/>. The same principle applies for the "theme.php" file.

It is strongly recommended to rename your custom theme as suggested above, even if you only plan to accomplish minor changes to a default theme that coppermine comes with. The reason is quite simple: when upgrading at a later stage, you will not run into issues (e.g. accidentally overwrite your customized theme with an updated default theme).

2.3.6.2 Tipps & tricks

If you're not sure how to go about creating your own theme, you could also have a look at the download section of the coppermine homepage: there are many user-contributed themes available for download that can be previewed on the coppermine demo page.

While you're in the process of creating or testing a new theme, you might not want your theme to be displayed to visitors of your site, but you (as the coppermine admin) may want to still be able to preview your theme. To do that, simply add theme=your_theme_name to the url in your browser.

2.3.6.3 Using WYSIWYG-editors

If you are using an HTML editor to design your template, the easist working solution might be to save the "template.html" file into the main directory of your coppermine installation and edit it there. Whenever you load Coppermine, if the script finds a file named "template.html" in the main directory it will load it instead of the default one that you assigned in the CONFIG menu. Once you have finished editing your theme be sure to move the file back into the directory it belongs. Don't forget to remove the temporary template.html file from the Coppermine root folder once you are done editing!

It is strongly recommended not to use a WYSIWYG-editor at all to edit Coppermine files. The coppermine dev team is aware that it might seem easier for beginners to use those graphical editors. However, they have some major drawbacks:

• Some editors (mostly MS Frontpage) are notorious for "beautifying" the code in a manner that renders embedded PHP code invalid. Subsequently, if you use a WYSIWYG-editor to edit theme.php, the file may get corrupt (i.e. un-usable)
• Graphical editors tend to create deprecated, invalid, proprietary HTML. You have more control if you use a plain text editor instead.
• You don't learn anything. Sooner or later, you will want to do something your precious WYSIWYG-editor isn't capable to do. Now what? You have always used the editor to do your work - you don't understand HTML. When using a plain text editor, the learning curve may be steep, but it's much more entertaining.

2.3.6.4 Editing template.html

The file template.html is the core file of each theme: it can only contain HTML/CSS/JavaScript code (no PHP!) plus some placeholder tokens that will get replaced with content when the theme is being parsed (i.e. when the HTML output of a gallery page is being generated). Template.html determines the overall layout of your gallery pages. Use it to make your gallery match the overall look of your entire website.

2.3.6.5 Template tokens

When editing the "template.html" file do not remove the elements between {} - these are the placeholders used by the script. Think of those items in curly brackets as placeholders that will be replaced later with dynamic content when your template is being parsed. You can move the placeholder tokens around to obtain different layouts. However, you have to understand that the {GALLERY}-token is a special placeholder: think of it more as a separator than an actual placeholder token. When the template is being parsed, the {GALLERY}-token will be replaced with the actual core component of the gallery. Other placeholders tokens in curly braces that come before the {GALLERY} token are being handled by the pageheader function; placeholder tokens that come after the {GALLERY}-token are being handled by the pagefooter function. Therefor, you have to keep in mind that you can freely move tokens around in template.html as long as you don't reverse the position of the token you move and the {GALLERY}-token.

2.3.6.6 List of tokens in template.html

Token	Description	Default position	Needed?	Dependancies
{LANG_DIR}	Language direction Possible values are LTR and RTL. Should not be changed or modified at all.	pageheader	mandatory	Filled by Coppermine, depending on the orientation of the language the end user has chosen
{CHARSET}	Character set Determines the character set used - filling the HTML tag . Do not change unless you really know what you're doing.	pageheader	mandatory	Filled by Coppermine, depending on the encoding the admin has chosen in config.
{TITLE}	Page Title The page title that is mainly taken into account by search engines. The human visitor sees the title tag in the browser window.	pageheader	mandatory	Title tag is being composed in the individual coppermine core file (e.g. displayimage.php, thumbnails.php etc.), handed over to the pageheader function.
{META}	Meta tags Meta tags that depend on the dynamic content of a page are being inserted here. Currently, Coppermine uses the keywords meta tag (<meta name="keywords" content="DYNAMIC CONTENT HERE" />) and the refresh meta tag (<meta http-equiv="refresh" content="5; URL=REDIRECTION_PAGE" />). If you want to add other meta tags (e.g. author meta data like <meta name="author" content="Firstname Lastname" />), do not replace the token, but add your custom meta tags below the {META}-token.	pageheader	mandatory	Populated dynamically by the script, e.g. for meta keywords based on file keywords or for redirection for status change screens.
{CUSTOM_HEADER}	Custom Header If the corresponding option has been set in config, this token will be replaced with the output that your custom header generates. If you don't use the custom header feature, you can remove the {CUSTOM_HEADER}-token from your template, but it's advisable to leave it in place if you decide to use the feature later.	pageheader	optional	Path to custom header include set up in config
{GAL_NAME}	Gallery name Will be replaced with the gallery name you set up in config when the template is being parsed. You might want to remove this token, especially if you already have a banner in your theme that displays your gallery name.	pageheader	optional	Gallery name set in config
{GAL_DESCRIPTION}	Gallery description Will be replaced with the gallery description you set up in config when the template is being parsed. You might want to remove this token, especially if you already have a banner in your theme that displays your gallery name.	pageheader	optional	Gallery description set in config
{SYS_MENU}	System menu Determines the position of the first level menu the end user will see on your page (the one that contains the login/logout link). Even if you want to get rid of the menu or parts of it, do not remove the {SYS_MENU} token itself, but remove the menu items you don't want displayed by editing theme.php instead.	pageheader	mandatory	Login/Logout link: Status of user (admin/registered user/guest). Upload-link: Permission of current user to upload (determined in groups panel). Register-link: Allow new user registrations enabled/disabled in config. FAQ-link: Display FAQ enabled/disabled in config.
{SUB_MENU}	Sub menu Determines the position of the second level menu the end user will see on your page (the one that contains the links "Album list" / "Last uploads" / "Last comments" / "Most viewed" / "Top rated" / "My Favorites" / "By Date" / "Search"). Even if you want to get rid of the menu or parts of it, do not remove the {SUB_MENU} token itself, but remove the menu items you don't want displayed by editing theme.php instead.	pageheader	mandatory	n/a
{LANGUAGE_SELECT_FLAGS}	Language selector (flags) Will display a row of flags representing the languages available for the end user to choose if corresponding config setting is enabled.	pageheader	optional	Display language flags enabled/disabled in config.
{LANGUAGE_SELECT_LIST}	Language selector (list) Will display a dropdown list of languages available for the end user to choose if corresponding config setting is enabled.	pageheader	optional	Display language list enabled/disabled in config.
{THEME_SELECT_LIST}	Theme selector (list) Will display a dropdown list of themes available for the end user to choose if corresponding config setting is enabled.	pageheader	optional	Display theme list enabled/disabled in config.
{ADMIN_MENU}	Admin menu Displays the admin menu.	pageheader	mandatory	Admin must be logged in. Admin controls mustn't be hidden.
{GALLERY}	Gallery	n/a	mandatory
{CUSTOM_FOOTER}	Custom Footer If the corresponding option has been set in config, this token will be replaced with the output that your custom footer generates. If you don't use the custom footer feature, you can remove the {CUSTOM_FOOTER}-token from your template, but it's advisable to leave it in place if you decide to use the feature later.	pagefooter	optional	Path to custom footer include set up in config
{VANITY}	Vanity block If your custom theme is defined as valid theme and you have enabled the corresponding option in config, the {VANITY}-placeholder will be replaced with mini-banners that link to PHP.net, mysql.com and the HTML and CSS validators of the W3C.	pagefooter	optional	Display the vanity block on themes that are defined as XHTML and CSS compliant enabled in config. Theme defined XHTML and CSS compliant in theme.php

2.3.6.7 Modifying colors

To modify the colors, fonts, font sizes, etc... used by the script, you should edit the "style.css" stylesheet whenever possible. For example, if you want to increase or decrease the size of the fonts you can simply modify the line with : table { font-size: 12px; }. Most of the font sizes used by the script are defined as a percentage of this size.

2.3.6.8 Editing theme.php

The "theme.php" file contains all the HTML templates used by the script. You can edit them, as well. When making modifications to these templates, be careful that you do not alter the lines that start with <!-- BEGIN xxx --> and <!-- END xxx -->. These lines are often used to identify the start and end of specific code blocks that the script will use to display your gallery.

Back to top

2.4 Safe mode issues

A significant number of webhosts on the Internet run PHP in safe mode. Coppermine runs without any problem in safe mode and with the "open basedir restriction" active, provided safe mode is properly configured. Unfortunately, on many hosts, safe mode is not configured properly.

If your webhost is running PHP in safe mode but is misconfigured, you may need to do the following :

• With a FTP program, change the mode of Coppermine's "include" directory on your server to 0777.
• Do the same for the "albums" and "userpics" directories.
• Check that at the beginning the the "include/config.inc.php" file, you have a line with : "define('SILLY_SAFE_MODE', 1);"

Back to top

2.5 Using SMTP to send emails

By default the script uses the PHP built-in mail function to send emails. In some cases, the PHP built-in function can't be used.

If, in order to send emails with PHP, you are required to supply a hostname, a username and a password, you will need to edit the CONFIG menu section "Email settings" and insert the correct values there. If you don't need a username and password to connect to your SMTP server, just leave these lines blank. If you don't know what settings to enter, you will need to check with your webhost.

Back to top

3. Upgrading

3.1 Upgrade steps

3.1.1 Upgrading from version 1.0

If you already have installed version 1.0 and you want to transfer your albums to version 1.4x follow the following steps:

• First, make a backup (dump) of your database.
• Install version 1.4.x as you normally would but in a directory different from the one where you v 1.0 is. Note that in order to use the upgrade script, tables for version 1.0 and 1.4.x must be stored in the same database.
• Copy the "albums" directory of version 1.0 into the directory where you installed version 1.4.x
• The upgrade script assumes that you used the "CPG_" prefix for tables (default value) when you installed version 1.0, if this is not the case, edit upgrade-1.0-to-1.2.php and edit the $prefix10 variable.
• Login to your 1.4.x Gallery, enter the admin mode
• And call the upgrade script, http://yousitename/coppermine_dir/upgrade-1.0-to-1.2.php
• The upgrade from 1.0 to 1.4.x is a two-step process. You must click the link which comes up on the bottom of the page to complete the upgrade!.
• Delete upgrade-1.0-to-1.2.php from your server.
• If you get an error, go to Coppermine 1.4.x config page, enable debug mode, try to call the upgrade script again and check what errors you get.

This upgrade process leaves your v1.0 gallery untouched

Back to top

3.1.2 Upgrading from cpg1.1.x, cpg1.2.x or cpg1.3.x to version cpg1.4.x

• First, make a backup (dump) of your database.
• Backup your include/config.inc.php file, your anycontent.php file and your "albums" directory.
• Unpack the archive
• Except for the "albums" directory, upload all of the new files and directories making sure not to overwrite the include/config.inc.php file, your anycontent.php file or the albums directory.
• Delete all leftover, outdated language files in the lang folder
• If you have not already done so, create a folder called "edit" within your "albums" directory - this folder will be used by coppermine as a temporary folder, do not ftp-upload files there. Make sure the new "edit"-folder is CHMODed the same way your albums-directory is (755 or 777, depending on your server's config)
• Run the file "update.php" in the coppermine directory once in your browser (e.g. http://yourdomain.tld/coppermine/update.php). This will update your coppermine install by making all necessary changes in the database.
• If you have made a custom theme, apply the changes that were introduced in the themes structure to your custom-made theme - refer to the theme-upgrade guide.
• You can not use language files from older versions of Coppermine as primary language (the language the admin will use) - make sure you only have the language files that come with this package inside of your lang folder (delete or rename all files from older versions within the lang folder).
  If you need to use a language that hasn't been translated for cpg1.4.x, you can try using the language file from cpg1.3.x, however there are certain caveats:
  • You need to enable the language fallback option in coppermine's config page
  • cpg1.4.x-phrases that don't exist in your old language file will go untranslated or show in english
  • Coppermine can't be administered using an old language file - the admin needs to use a "true" cpg1.4.x language file
  • You're free to try using old language files, however when running into issues or error messages, switch to US-English and see if the issue goes away then. Using outdated language files goes unsupported
• The bridging method has changed from cpg1.3.x to cpg1.4.x. When upgrading, your bridged coppermine install will be unbridged - you will have to re-apply the bridging using the bridge-manager (using your standalone admin account you initially used to set up coppermine). You will not lose anything though, don't worry.

Please note: as there have been changes both in the coppermine files and the database from cpg1.3.0 or better to cpg1.4.x, users of previous versions will have to apply all steps mentioned above: both the files have to be replaced and the update.php script has to be run once.

3.1.3 Upgrading from cpg1.4.0 or better to version cpg1.4.18

• First, make a backup (dump) of your database.
• Backup your include/config.inc.php file, your anycontent.php file and your "albums" directory.
• Unpack the archive
• Except for the "albums" directory, upload all of the new files and directories making sure not to overwrite the include/config.inc.php file, your anycontent.php file or the albums directory.
• Run the file "update.php" in the coppermine directory once in your browser (e.g. http://yourdomain.tld/coppermine/update.php). This will update your coppermine install by making all necessary changes in the database.
• If you have made a custom theme, apply the changes that were introduced in the themes structure to your custom-made theme - refer to the theme-upgrade guide.

Please note: as there have been changes both in the coppermine files and the database from cpg1.4.0 or better to cpg1.4.18, users of older versions than cpg1.4.18 will have to apply all steps mentioned above: both the files have to be replaced and the update.php script has to be run once.

Back to top

3.2 Why upgrade?

There are major and minor releases of Coppermine. Major releases have so far been cpg1.0, cpg1.1, cpg1.2.x, cpg1.3.x and cpg1.4.x. The next major release will be cpg1.5.x (which currently is in the dev pipeline - no scheduled release date yet). Minor releases (the third number in the version numbering scheme) represent updates, also known as "maintenance releases". Major releases contain new features (compared to the previous major release), minor releases do not contain new features, but only bug fixes and slight improvements (like additional language files).

To understand the release policy of the coppermine dev team you have to understand how bugs are being fixed: we maintain a repository where the core code of each major release is being constantly being improved. Major and minor bugs that are reported on the coppermine support board are being fixed in that repository. Once a new package is being bundled, all fixes that have been made in that repository go into the new maintenance release.

There is a good reason for every new maintenance release: they are usually being packaged when a new bug or vulnerability is being discovered that is relevant in terms of security. As suggested above, there are several minor bugfixes that go into each new release as well, not only the one major bug or vulnerability that lead to the maintenance release. Therefor, it will not be enough to just fix the single vulnerability that has been the initial reason for a new package to be released. Instead, always upgrade to the most recent stable release as soon as it has been announced.

3.2.1 Reasons for package releases

This is a list of minor releases of cpg1.4.x and the reason why they have been released. It is meant to explain why you should upgrade as soon as possible to the most recent stable release if you are running an outdated version.

As you can see, the coppermine dev team is constantly fixing and improving coppermine. Every non-trivial piece of software contains bugs, so there is no guarantee that the version that currently is the most recent one will be the final, ultimately bug-free version to be released in the cpg1.4.x series. It is absolutely vital that you perform regular updates as soon as new packages are being released.

3.2.2 Changelog

Details on the changes that went into a release can be found in the changelog that comes with each package. The changelog file can be found in the root directory of the coppermine package. The changelog contains more information on additional languages and the time and date of the fix as well.

The changelog is a plain-text file that can be read using a simple editor - on Windows-driven machines, notepad.exe is fine.

Back to top

3.3 The version check tool

Since the release of cpg1.3.2 Coppermine comes with an additional version checking tool to help you resolve issues with upgrades and updates easily. Except for specific files of coppermine that will only work for the version that it had been originally designed for, the versioncheck tool can be used with all versions starting from cpg1.2.1. To launch the versioncheck, simply add versioncheck.php to your browser's address bar after being logged into coppermine as admin (example: http://yourdomain.tld/your_coppermine_folder/versioncheck.php). With version 1.4x, you can run the versioncheck utility from the Admin Tools menu.

3.7.1 What it does

The script "versioncheck" is meant for users who have updated their coppermine install. This script goes through the files on your webserver and tries to determine if the local file versions on your webserver are the identical to the ones at the repository of http://coppermine.sourceforge.net. Files that do not match are displayed and are the files you should update as well. In Cpg1.4.x you can toggle the URL to the latest update for individual files in the versioncheck page.

It will show everything in red that needs to be fixed. Entries in yellow need looking into. Entries in green (or your theme's default font color) are OK and should be left alone. When an entry is red or yellow, a help icon will appear next to it. Click it to find out more. Hovering with your mouse over an item will display additional information as well (tooltip).

The versioncheck screen has several sections:

• Section 1 explains what the versioncheck tool can be used for
• Section 2 ("Options") displays the options you can chose
• Section 3 will display a warning if coppermine was not able to connect to the online repository (where the most recent version data is being stored). The script will default to a local copy of the repository file. If connection to the online repository was succesfull, there will of course be no error message (no section 3).
• Section 4 will show what version of coppermine you actually use. The versioncheck script draws this piece of information from the file include/init.inc.php - if you haven't replaced your copy of this file with the new version during upgrade, your old (outdated) version will appear in this section.
• Section 5 will show the core of versioncheck's file: the version comparison. The script will loop through all files that are suppossed to exist (based on repository data) and compare them to the files you actually have on your webserver.
• Section 6 will display a summary of the files and folders checked

3.3.2 Options

The options screen lets you configure the versioncheck, or rather what is being displayed. The options aren't saved anywhere, so you will have to adjust them each time you run versioncheck. The default options should be OK for most users - only change them if you have good reasons to do so.

• show optional folders/files
  Uncheck this to hide files that are tagged as "optional" (display mandatory files only)
• show mandatory files
  Uncheck this to hide files that are tagged as "mandatory" (Note disabling both optional and mandatory files will of course result in no files being displayed at all)
• show additional information
  Toggles whether informaton about the installed coppermine version and the repository connection status are being displayed. Uncheck if your're making screenshots to save space and reduce dimensions.
• show file versions
  Toggles wether additional version information of a file that belongs to the release version you're using should be displayed. When viewing the source code of a coppermine file, the file version is the number that looks like this: Id: index.htm,v 1.66 2004/08/26 04:42:19 gaugau Exp (in this example the file version is 1.66)
• show folders/files with errors only
  Toggles display of files that don't have errors. Enable this option if you want to make a screenshot and ask for support on the coppermine forum.
• coppermine is installed in the webroot
  Experimental: if all your files are being displayed as "non-existant", you probably have installed coppermine in your webroot, or you are using subdomains. Check this option only if you are experiencing problems. This option hasn't been tested thoroughly yet, there's no guarantee it will work on your setup.
• try connecting to the online repository
  Toggles wether versioncheck should try to connect to the online repository (checked by default). Only uncheck this option if you're sure you can not access the online repository because of your server setup and you want to reduce the time the script needs to execute a bit.
• show folder permissions
  Toggles the option to show/hide the read/write permissions of a folder.
• don't display web svn link / display web svn link to stable branch / display web svn link to devel branch
  Toggles wether to show an additional column that contains a link to the web svn. Only recommended if your cpg version is OK (green), but your file version appears to be outdated. You can then connect to the web svn to get a more recent version of your file. Only recommended if you know what you're doing (or you have been told to do so from a supporter from the coppermine support board).
• show condensed ouput (for easier screenshots)
  When checked, this options reduces the width of the version comparison columns. This will allow you to create screenshots with reduced dimensions and size.

3.3.3 Version comparison

There is a lot of information packed into a small space. Here's an example of a possible output and what the output means:

• The column "icon" shows if the entry is a folder or a file. Clicking on the icon takes you to the page, e.g. clicking on util.php will take you to the "admin tools page" (although not all coppermine files can be opened directly by running them in the browser).

  In above example, rows "A" to "E" are folders, rows "F" to "K" are files.

• The column "folder/file" holds the relative path from your coppermine root to the folder/file in question.
  

  If an entry is in your default font color, it exists (in above example, all rows but "G" and "H").
  

  If the entry is in yellow (row "G"), the corresponding folder/file doesn't exist on your webserver, but it is only considered to be optional (e.g. a language file that comes with the coppermine package that you don't want to use can be deleted from the webserver. It will then be shown in yellow, as it's only optional to have it). It's up to you if you need it.

  If the entry is in red (row "H"), the folder/file in question doesn't exist on your webserver, but it is mandatory to have it. You should upload the file from your coppermine package to your webserver. Only leave it as-is if you really know what you're doing.

• The column "writable" shows information if the folder in question is writable, and whether this is correct or not. The write permissions for files are not being displayed, as this would slow down the script considerably. Usually, there are icons that show the writable status of your folder (if you have the icon resources on your webspace). Optionally, a plain text message in brackets might be visible (if you don't have the icon resources).
  • A white pencil with a green "x" indicates that the folder is not writable and is isn't suppossed to be writable - everything is OK then (row "A")
  • A green pencil indicates that the folder is writable and it is suppossed to be writable as well - everything is OK then (row "D"
  • A white pencil with a red "x" indicates that the folder is not writable, although it should be (row "C"). You should change write permissions (CHMOD) for this folder and everything within it, usually using your FTP software.
  • A red pencil indicates that the folder is writable, but it shouldn't be (row "E"). Unless absolutely necessary, leaving files writable could be a security risk. Where possible, you should change permissions for this folder and everything within it to read/execute only.
• A question mark in a yellow box (help icon) indicates that there is additional information available. Click on the icon to display the pop-up window with this information.
• The column "cpg version" displays what coppermine package your file on your webserver is from, and what version it should be from. The data is being extracted from the header of the file, that's why folders are shown as "n/a" - they have no header information containing their coppermine version (rows "A" to "E").

  Files that contain header information are being displayed with your file version and the cpg version of the file in the repository, separated with a slash. It is possible that a file version may differ from the version of your whole package - this doesn't matter as long as both your version and the repository versions match (the are displayed in green) - in above example: rows "F", "J" and "K".

  Of course, version numbers from files that don't exist can't be extracted, that's why rows "G" and "H" have a dash as cpg version. If your cpg version is lower than the repository version, your version is being displayed in red: if this is the case, you probably haven't successfully uploaded the proper file of files from the coppermine package to your webserver (replacing files that may have already existed on your webserver) - you should do so now (row "I").

  If your local version is being displayed in yellow, you are using a file that belongs to a higher coppermine version than the rest of your files - you probably downloaded a file from the devel branch: remember that using devel files go unsupported, do so on your own risk (if you know what you're doing). If most or all of your files are being displayed in yellow, you probably have upgraded some files, but you forgot to upgrade the file "include/init.inc.php" (that holds the version info for your install). Make sure to upload all files from the package to your server.

• The column "file version" holds the individual file's version that get's increased during development of a new coppermine version (each time a developer modifies a certain file, the version number increases by one). As folders can't contain such version numbers, they are again labelled as "n/a" (rows "A" to "E"); the same applies to files that don't exist, that's why their file version is displayed as dash (rows "G" and "H"). Also the file version is irrelevant when comparing files from different coppermine packages, that's why row "I" has a dash as well.

  The coloring scheme is similar to the cpg version system: green means "everything is OK", red means "you're using an outdated version" and yellow means "you're using a newer version than you're actually suppossed to.

  The difference between the cpg version and the file version columns is indicative of the way you should obtain the file that you need to replace the existing one on your server: a red entry in the cpg version column means the file on your server hasn't been replaced with the file from the coppermine package; a red entry in the file version column (row "J") usually means that there have been updates to a certain file after the release of the package - you should either check if there is a newer package available or get the most recent file from the SVN (enable the web svn link column in the versioncheck options).

• The column "web svn" (off by default) links to the corresponding file in the SVN. You're recommended to use this only if there appears to be a newer version in the svn than your coppermine package has and you know what you're doing.

Back to top

3.4 Downgrading from cpg1.4.x to an older version

CPG1.4.x incorporates many new features (compared to older versions), so we encourage all users to upgrade. However, there may be some who want to test cpg1.4.x and decide later that they want to go back to an older version. You have to keep in mind that a full upgrade changes the overall layout of copp