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

Table of Contents

Installation and Setup

How to install the script

Minimum requirements

Make sure that you fullfill the minimum requirements to run Coppermine on your webserver.

Unpack the archive preserving the directory structure

You can (and should) rename the coppermine folder, but not the files or folders within.

Details

You need an application that can unpack an archive like 7-Zip if your OS doesn't support unpacking out of the box (Windows XP or better comes with support for zip files; most Desktop Linux distributions come with corresponding clients like File Roller as well). In some Packing/Unpacking Applications like WinZip there is a toggle that allows the end user to specify if the folder structure within the archive should be kept intact or if all files contained in the archive should be unpacked into one flat folder without sub-folders. For Coppermine, the option that preserves the folder structure must be enabled.

A good place to unpack your copy of the Coppermine package to is the Desktop or another temporary folder. In this explanation, we'll assume that you have unpacked the archive on the Desktop.

After unpacking, you should have a folder on your desktop named cpg15x. You are welcome (and encouraged) to change the name of this folder to something that makes more sense for usage on the internet, but make sure to use a web-safe name: don't use special characters except the dash (-) and the underscore (_), don't use spaces, don't use accented characters, Umlauts or any other special characters. Avoid capitalization if possible. In fact, you should use latin alphanumerals only (a to z and 0 to 9). This recommendation does not only apply for the Coppermine folder, but any folder or file you upload to a web-server.

Here's a list of good names for the folder:
  • gallery
  • pictures
  • images
  • multimedia
  • galerie (if the majority of users speaks German, as the German word for gallery is Galerie with one middle L)
The folder name you pick here will later correspond to the URL of your gallery, so it's advisable to pick a name that is easy to memorize. You get a small extra bonus in terms of search engine friendliness if you choose a descriptive name like gallery. Don't be to concerned about which name to pick for the folder that coppermine will reside in: you can always change the name of the folder at a later stage.

Upload all files onto your webserver

It's mandatory to upload all folders and files that come with the Coppermine package to the webserver.
Details

Use your FTP client application to upload the folder you unpacked in the first step to your webserver. Do not use browser add-ons or any other crutch to upload the files, but use a real FTP app. Do not trust uploaders that often come with WYSIWYG-editors like MS Frontpage or Dreamweaver, as those built-in uploaders tend to "beautify" the code files, crippling them that way. Those editors and the tools they come with are OK for other purposes, but they often cause issues when used with pre-made scripts like Coppermine, that's why the Coppermine dev team strongly recommends not to use such WYSIWYG-editors at all. If you don't have an FTP app yet, take a look at the list of tools recommended by the Coppermine developers. Do not use crap like WebFTP applications: while those applications are fine for a casual upload when you're away from your home and don't have access to a computer you have full control over, WebFTP is not OK to be used to install a package like Coppermine because of the limitations built-into such applications.

To use your FTP application, you will of course need to know the FTP details for your webspace. If you're not sure about those details, ask your webhost for support.

Make sure to use the correct FTP mode when uploading.

If you plan to make Coppermine your primary application that shows on your site's start page, you don't necessarilly have to put the Coppermine files into a separate folder: you can savely upload the content of the Coppermine package into the webroot of your server,

Set permissions on the "albums" and "include" folders in your Coppermine directory

Set permissions on file system level for the Coppermine script. Coppermine needs write access for some folders within the Coppermine folder. Setting permissions can sometimes be hard for newbies, that's why a separate section of the documentation has been created that explains permissions in detail.
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 relevant 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.
Details
If no database exists for your website, you will need to create one, or have one created for you by your webhost. Your webhost can best provide you with instructions on how to go about doing this. For installation purposes, you will need to know the path of the database server that you will be using with Coppermine and details of the MySQL user account through which Coppermine will connect to the server. You must have the database server path (usually 'localhost'), your MySQL username, MySQL password, and MySQL database name prior to installing Coppermine. The user installing Coppermine must have all relevant access rights to this database.
If you are using a newly created database, there is no need for you to manually add any tables. Coppermine will create the necessary tables in the database during installation process.

Run the install script on your server

Type the following URL into the address bar of 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.
Example
If your website is example.com and the name of your Coppermine folder was "gallery", the address you would have to type is is http://example.com/gallery/install.php

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.

Related information

There are some additional pieces of information that are related to installing:

Server configuration

When installing Coppermine, you might run into issues not directly related to Coppermine, but to webserver setup. Therefore, this section of the docs can only give a rough overview about the webserver setup issue. We can only give recommendations, but it's beyond the scope of the coppermine support board to actually advise how to configure a webserver in the first place. This being said: if you have issues related to webserver setup, ask your webhost for support instead of asking your question on the coppermine support board.

register_globals

In older versions of PHP, the default setting for register_globals used to be "on", which resulted in many PHP coders coming up with sloppy code in terms of security (simply because they were not aware of the dangers that lay in such sloppy coding). As a result, there used to be many scripts that relied on the server variable "register_globals" to be turned on. However, as many malevolent attacks against scripts are being carried out that rely on register_globals to be turned on, it's advisable to turn that feature off in the config of your webserver's PHP settings. In recent versions of PHP, the default setting is "off". However, your webhost may still have enabled register_globals to allow you to run outdated scripts that rely on register_globals.

To make this absolutely clear: coppermine does not need register_globals=on, but it will run both with register_gloabls turned on or off. It's just the security impact of this variable turned on that we want to alert end users about. If your webserver has register_globals turned on, the installer will warn you about this fact, but it will continue anyway.

The Coppermine dev team strongly recommends to turn register_globals off on your server. However, we can not tell you how to accomplish that: it's a webserver-setting, not a Coppermine setting. Usually (when you're on shared hosting) you can ask your webhost to turn register_globals off for you on your server. A good webhost should do that for you or tell you how to accomplish this (if they allow you to configure your server). Please do not ask question on register_globals on the Coppermine support board - that's beyond the scope of that support forum.

There will be no negative impact for your Coppermine install if you leave register_globals turned on: nobody but you (the admin) will notice the mesages of the script that warn about the dangers that lie in register_globals. There might however be an impact for other applications on your webspace - we can't tell for sure.