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

Table of Contents

Integrating the script with another application (bridging)

What bridging does

Coppermine can be integrated with other applications in terms of user management and sharing a common login on your overall website; this is what we call "bridging". It can create a more seamless end user experience, as your users will only have to register once; their login will stick both on the Coppermine pages as well as the pages you bridge with.

By default, bridging is turned off, and those who do not want to use it can safely leave it off forever. There are however issues when bridging at a later stage (after there is already content in Coppermine), so if you intend to use bridging you should enable it before you start adding content.

Originally, Coppermine bridging was designed to bridge with BBS apps. Later, bridges for other apps (that don't fall into the category "BBS") have been added - mostly Content Management Systems (CMS). However, the reference to BBS apps remained in some documents and strings. No reason to get alarmed.

Bridging does not integrate your gallery and the application you bridge with in terms of visual appearance. If you want a seamless visual integration, create a custom theme for your gallery that matches the look of your bridge app or your overall site and add links pointing from Coppermine's navigation to your bridge app and vice versa.

When bridging is turned on, Coppermine drops the user management it comes with and uses the user management of the app you bridge with (i.e. your BBS app). Subsequently, your users will register and log in on your bridge app (BBS). After they do, they may be redirected to coppermine (if they came from coppermine's login page in the first place and your bridge app allows redirects).

Available bridge files

Coppermine can be integrated with the following applications (eg. Coppermine and your bulletin board will share the same user database).


Pre-requistes

Authentication by cookie

The login integration uses your bulletin board cookies, therefore it won't work if your board cookies are not visible by Coppermine. So unless you are an expert, keep things simple and install Coppermine and your bridge app on the same domain.

This will work: This might work: This won't work:
Bridge app: http://yourdomain.com/board/
Coppermine: http://yourdomain.com/gallery/
Bridge app: http://board.yourdomain.com/
Coppermine: http://gallery.yourdomain.com/
Bridge app: http://yourfirstdomain.com/board/
Coppermine: http://yourseconddomain.com/gallery/

The cookie path in the forum's configuration should be set to '/' where this option is available.

The cookie names of your bridge app and coppermine must not be the same - they must differ!

Some bridging apps have an option to enable sub-domain independant cookies that you should enable if you own the entire domain.

Some bridging apps use a cookie path by default that will make the cookie only available for the bridging app itself and not for other apps that reside in different folders on the webserver. If this is the case for you, you have to review your bridging app's config first and make sure that it is set to allow the cookie from the bridging app to be read by coppermine.

In SMF 1.1.x, the setting is named "local storage of cookies". When enabled, the cookies issued by SMF will be accessible only for the forum and not for other apps. Therefore, when bridging Coppermine with SMF, you have to go to SMF's admin panel first and turn local storage of cookies off. In SMF, that option can be found under "Admin" → "Server Settings" → "Feature configuration" → "Enable local storage of cookies".
For other bridging apps, the setting may be named differently and may reside in a different navigation structure, but the result should be the same: the cookie issued by the bridging app should be stored in a way that makes it accessible for other apps on the same domain.

In many recent BBS apps you can specify whether you want to handle authentication of users by cookie or by session. If you want to bridge, you have to make sure that the app you bridge with is using cookies as authentication method - coppermine doesn't work with session-driven authentication!

Standalone version first

To avoid confusion, make sure to set up both coppermine and your bridge app as standalone first. Make sure they both run correctly without integration. Test all features of coppermine (like upload, registration etc.) when Coppermine is installed, before you even start integration.

Coppermine users, groups and pics uploaded by users are lost when integrating

Warning: If you already have users and custom groups in your coppermine database when you enable bridging, be aware that they will be lost. If your coppermine users have already created private albums and uploaded pics to them, they will be lost as well!

Detailed explanation:
As most community applications, coppermine stores everything that users (including the admin) do (like uploading pics, posting comments, rating files) inside the database. The reference to each user action is being kept using a unique user ID. The correlation between the user actions and the corresponding user profile is being kept by storing the user ID within each record in the database that determines the user action.
When bridging is enabled, coppermine's user management is being dropped in favor of the user management that comes with the application you bridge with. Subsequently, the user IDs from your bridging app (that differ from Coppermine's user IDs) are being taken into account.

Coppermine-user "Bill" has got the coppermine user ID "3". He used to upload several pics that went into the folder /albums/userpics/10003/. The URL of his personal gallery used to be http://yoursite.tld/your_coppermine_folder/index.php?cat=10003.
In the BBS application, the user "Linus" has got the user ID "3".
After enabling bridging, the URL http://yoursite.tld/your_coppermine_folder/index.php?cat=10003 points to the personal gallery of the user "Linus". All pics that Bill used to upload appear to be owned by Linus.

Summary:
Correlation between the actions that the unbridged coppermine users have performed and the "new" accounts from the app you bridged with is lost. Subsequently, you don't actually lose files that have been uploaded previously, but they appear to have been uploaded by a different user.

Backup

It is very advisable to backup both your coppermine database and your files before enabling bridging, so you can safely go back if the integration fails.

In fact you're encouraged to backup your database on a regular basis, and especially before applying code changes.

However, don't be afraid that bridging might cause your bridging app to malfunction: coppermine doesn't harm your forum (or the app you bridge with) at all. When enabling bridging, coppermine doesn't run write/alter queries against the bridging app's database tables nor does coppermine modify any of the files of the bridging app. The worst thing that may happen if something goes wrong is your coppermine gallery becoming inaccessible. It is completely impossible that coppermine bridging will do harm to your bridging application.

Integration steps

From cpg1.4.x on you can use the Bridge Manager that will provide a wizard-like interface to enable/disable bridging.

Using the bridge manager

The bridge manager is a new feature in cpg1.4, it is not available in older versions. Instead of manually editing coppermine code files, you can enable/disable bridging in your browser, using a wizard-like user interface. To start the bridge manager, log in as admin, choose "Bridge Manager" from the admin menu.

Note: with each step in the wizard, some information is being written to the coppermine database. Unlike other wizards (mostly on your local machine), the bridge manager doesn't have a "cancel" button! Once you have enabled bridging and everything is working fine, you shouldn't change any values just out of curiosity, as they will get written to the database, which might result in a bridging that used to work not working any more after "playing" with it.

Side-note
If you have a custom-made bridge file, just copy that bridge file into coppermine's bridge folder and it will show up on the bridge manager interface (the bridge file must reside in the coppermine sub-folder "bridge").

If a reset button () is displayed next to an input field, the field value doesn't have the default value. It can be perfectly OK to have a non-default value in a field, however you should keep in mind that if you have "played" with the bridge manager before, previous settings might exist in a field that are not correct - do not light-heartedly skip a step without paying attention to it. Use the reset button to revert to the default value (not necessarily "your" default value though).

Choose application to bridge coppermine with

In the first actual step of the wizard "choose application to bridge coppermine with", you have to choose the application you actually want to coppermine with. Note that you must have this application already installed on your webserver, it has to be properly configured and must be up-and-running. Don't use the bridge manager yet if you only plan to integrate coppermine with another application later.

Choose one of the available bridge files

Click "next"

The next steps

The next steps depend on the application you have chosen to bridge with: some applications need URLs to be entered, or paths. Some need cookie data to be entered, others don't. The point of the wizard is that it will only "ask" you the relevant settings for your application - if one or more items of the following description doesn't turn up for your application, there's no need to worry - just keep filling in the mandatory information and then hit "next". However, you have to understand that coppermine can proof-check only some of your input - some input goes unvalidated.

Path(s) used by your bridge app

There are various different ways used by coppermine's bridging mechanisms to get connected to the bridge application. Basically, the settings made in the bridge manager at this stage "tell" coppermine where your bridge app resides at and where the bridge app's config file is located that contains data that is being used by coppermine to "hook up" to the bridge app. As there are different approaches of bridge apps how this can be done, the method used in the bridge wizard might differ, depending on the bridge app you picked in the first step of the wizard. Therefore, not all of the settings mentioned below will apply for you. Just run the wizard and then look up the needed settings and enter them carefully.

Bridge app-specific settings

Enable/disable bridging

This is the last step of the bridge manager - it summarizes up the settings you have made in previous steps - you can enable or disable integration here. By default, integration is set to "disabled" after the bridge manager has been run for the first time. You should only enable integration if you're sure your bridge app is set up correctly. Click the "Finish" button in any case to finally write to the database, even if you choose to keep the current settings (leaving integration "disabled").

Recover from failed bridging

If you have provided improper settings using the bridge manager, your integration might fail, resulting (in the worst case) in a stituation where bridging is enabled, but you can not log in as admin to switch it off again (e.g. if you provided improper cookie settings that stops authentication from working). For this situation a recovery setting was built into the bridge manager: if you are not logged in as coppermine admin (in fact: not logged in at all) and you access the URL of your bridge manager (http://yourdomain.tld/your_coppermine_folder/bridgemgr.php) by entering it manually into the address bar of your browser, you are prompted to enter your admin account details - use the admin account you used to install coppermine with in the first place (the standalone admin account). This will not log you in, but switch integration off, so you can fix improper bridging settings then. To avoid others trying to guess your admin account details, there's a login threshold that rises every time you enter wrong credentials, so enter your admin account details with care.

Synchronising the bridge app groups with Coppermine's groups

Login using the admin account of your board. Go to the gallery, enter admin mode and click on the "Groups" button. This will synchronize Coppermine groups with those of your board. The permission you will see for each group will be completely messy, so take some time to set them properly.

Each time you add or delete a group in your board you will need to do the operation above in order to keep the synchronisation of the groups.

When you will try to login / logout or manage users from Coppermine, you will be redirected to the corresponding page of your bulletin board. Once the login or logout is performed you won't be redirected automatically to the gallery because your board does not have any function for that. It's up to you to add a link on your board to get you back to the gallery.

It's mandatory that you (as admin) go to the groups page directly after bridging or whenever you change anything in your bridging configuration or if you change anything in your groups settings on your bbs, as you need to trigger the re-sync.

Bridging support

With the explanations given above you should be able to bridge your (BBS) application with Coppermine. However, if things don't work as expected, you're welcome to look for help using the coppermine support board. When asking for support, please keep in mind that the supporters will need some information to enable them to help you:


Some config options get disabled

As explained on this page, coppermine will drop the user management it comes with in favor of the user management of the bridging app if you enable bridging. Subsequently, coppermine config options that apply to coppermine's user management will no longer apply (e.g. the user profile fields). Therefore, the config options that apply only to a standalone, unbridged coppermine will be disabled on the config screen if bridging is enabled.

Bridging files

In coppermine's root folder, you will find a subfolder named "bridge" - this is where the bridge files reside in. When coppermine is run (i.e. a visitor browses a coppermine-driven page), coppermine includes the bridge file that relates to the app you have bridged with. Using this file, coppermine does what is needed to authenticate the visitor. Even if coppermine is not bridged at all, there is still a file that is being included from the bridge folder ("coppermine.inc.php") that determines what tables to use.

Usually, you should not edit the files within the bridge folder - in fact the only important thing that you have to remember is that coppermine needs the bridge folder and the contents even if you haven't enabled the bridging feature. Just leave the files as they are. Power users who really know their way around are of course welcome to edit the bridge files and adjust them to their needs.

There have been users who tried to "run" the bridge files themselves directly in your browser - this will not work and do nothing but result in an error message. The bridge files are not meant to be run standalone - they get included by coppermine during runtime. If you have no idea what this means, just ignore those files and leave all in place. It won't hurt to have bridge files reside on your webspace even if you don't use the bridge that corresponds to a particular bridge file.

Creating a custom bridge file

In theory, coppermine could be bridged with all forms of third party applications that have a user management/authentication. There are thousands of applications available that could be potential candidates. Just because of the sheer number of possible bridges, but as well because of other restrictions (non-free software, lack of time, lack of need), the coppermine devs can not come up with a huge number of bridge files. That's why there is only a comparatively small number of bridge files available. If you are looking for a bridge file for another application that is not being covered by the bridge files that come with coppermine out-of-the-box, you're welcome to search the coppermine support board if there already is an existing user-contributed bridge, or (even better) you're encouraged to come up with a bridge file of your own and publish it on the board. We (the coppermine dev team) have to rely on user contributions for most potential bridge candidates.

Sadly, there is no particular piece of documentation available (yet) that explains how to create a custom bridge file, so the best method to create your custom bridge file is to look at existing bridge files and modify one to fit your needs.

Bridging philosophy

The coppermine developers believe that the bridging mechanism should not interfere with the application coppermine is being bridged with. That's why a genuine bridge file that can be considered to go into coppermine's core code can not be designed to make edits to the bridging app's code nor is it an option that the database structure of the bridging app is being modified by queries performed by Coppermine.
The reason for our reluctance to allow bridging to interfere with the bridging app is that we don't want the bridging app to break if something goes wrong.

However, there are bridge files contributed by third parties that don't work in the unobstrusive manner that we propose (like the Mehdi bridge for Joomla). We don't claim that those third party bridges are bad - in fact we appreciate that those bridge files are being made available. You have to understand though that we can not support those third party apps. We recommend that you make backups before bridging when using those third-party apps.

Individual bridge issues

There are some additional remarks that apply to particular bridge files:

Subdomain issues

There are a lot of users who frequently ask on the coppermine support board if bridging across sub-domains is possible: the answer is "yes", at least in theory. As suggested above, you can not bridge across different domains (using the word domain in a broader sense, it should actually be "second level domains"), but you can bridge across different subdomains of the second level domain if certain requirements are met that hardly can be influenced by the coppermine developers: the cookies from the domain where your bridge app resides on must be readable for coppermine and the both domains need to physically reside on the same server. This is the case for almost all users on shared webhosting.

File system

Most webhosts set up their servers to make a subdomain being just a sub-folder of the parent domain on file system level. We (the coppermine dev team) can't guarantee that this is the case for your webserver setup, so when in doubt you should ask your webhost for support. So here's just an explanation how sub-domains work on most webservers - don't sue us if this is not the case for you.

Your bridge app has got the URL http://forum.example.com/, with a absolute path on file system level like this: /var/www/your_account_name/public_html/forum/, with /var/www/your_account_name/public_html/ representing the webroot (i.e. http://example.com/). Your gallery is accessible with the URL http://gallery.example.com/, which equals the absolute path on file system level /var/www/your_account_name/public_html/gallery/. Seen from the webroot, the sub-domains "forum" and "gallery" are just representations of the sub-folders of the webroot that are named accordingly ("forum" and "gallery"). Therefore, if the bridge manager requires you to enter a relative path from the gallery to the bridge app, this would be ../forum/ (which reads "one folder level up, then into the sub-folder "forum").

Cookies

As pointed out several times, coppermine's authentication is cookie based. If bridging is enabled, coppermine needs to be capable to read the bridge app's cookie as well. This is only possible if you don't have restrictions in place that keeps coppermine from doing so. Many third-party apps (and many of the apps that coppermine can be bridged with) allow you to specify a cookie path. Sadly, not all of them clearly label the cookie path setting accordingly in their control panel app: some label them as local cookies as well without allowing you to specify a particular path. This option mostly exists for historical reasons: some time ago, many users couldn't afford a domain of their own, so they just got webhosting on a child folder of the parent domain. All their content used to reside in the one folder only and subsequently they needed an option in their applications to make sure that their cookies were not accessible for all users of the parent domain. Nowadays, universities often offer webspace to their students that looks like this: http://example.tld/~username/. Users on that sort of webhosting need the option to have a cookie path to make sure that someone else who is hosted on http://example.tld/~someone_else/ doesn't have access to his/her cookies.

If your gallery resides at http://example.tld/gallery/ and your bridge app resides at http://example.tld/forum/, it's not a bright idea to set up the cookie path of your bridge app to be /forum - this means that only pages that reside in the sub-folder /forum within the webroot are allowed to read the cookie. Since your gallery doesn't reside within that folder, it can not read your bridge app's cookie - as a result, bridging will not work as expected.

Bottom line: for 99% of all users, setting the cookie path to "" (nothing) will be the best choice.

www-subdomain

Many websites can be accessed with or without the leading www-subdomain: usually, http://example.tld/ works just as well as http://www.example.tld/. This is fine and user-friendly, but it has a drawback: a sub-domain is a different domain as far as cookies are concerned. Therefore, you need to be consistent with your use of the www-subdomain: bridging http://example.tld/gallery/ and http://www.example.tld/bridge-app/ will almost certainly cause cookie issues for you.

To circumvent this, review the setup both of coppermine as well as your bridge app: make sure that in both config panels you're either using the URL with the leading www-subdomain or without it.

Recomendation:

The leading www subdomain has been introduced in the early days of the world wide web. Technically, it is no longer needed, but many users have gotten used to specify a leading www subdomain when typing an URL. We recommend using your URL without the leading www to make it shorter to memorize. To make sure that those who type in the URL with the leading www, we recommend setting up a rewrite-rule in a custom .htaccess file that could look like this:

Replace yourdomain and tld in above code snippet. If your site actually resides at example.com, change the code mentioned above into something like
Please note though that setting up your rewrite rule is something beyond the scope of coppermine support - you should use your favorite search engine to find out details about it.