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).
Coppermine can be integrated with the following applications (eg. Coppermine and your bulletin board will share the same user database).
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.
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!
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.
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.
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.
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.
From cpg1.4.x on you can use the Bridge Manager that will provide a wizard-like interface to enable/disable bridging.
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.
If you run the bridge manager for the first time, there will only be one button that lets you actually start the wizard (if you return to the bridge manager later, you will also find a switch to enable/disable bridging) click 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).
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 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.
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.
Full URL of your bridge app folder (including the leading http:// bit, e.g. http://www.yourdomain.tld/forum/).
Please note that you mustn't specify a file at the end of the URL - if your bridge app actually resides at http://www.yourdomain.tld/forum/index.php, just specify the URL of the folder that contains the bridge app's index file.
Make sure to add a trailing slash - the URL must be http://www.yourdomain.tld/forum/ and not just http://www.yourdomain.tld/forum
Absolute path to your bridge app seen from the webroot
You have to understand that this setting is not the absolute path on file system level on your web-server, but only the absolute path seen from the webroot.
On file system level of your web-server, the absolute path your webroot might be something like /var/www/your_account_name/public_html/. Subsequently, the app you bridge with might reside in an absolute path on file system level like this: /var/www/your_account_name/public_html/forum/. Your coppermine gallery might reside in an absolute path on file system level that looks like this: /var/www/your_account_name/public_html/gallery/. However, it's the webroot folder that matters in this aspect - coppermine doesn't dig deeper on file system level and doesn't take the absolute paths into account that you might be using with other applications or to include files - it just uses the path seen from the webroot (the stuff that can be accessed directly in the browser). Hence, in this example the absolute path seen from the webroot would be /forum/ - nothing more, nothing less.
Relative path to your bridge app, seen from your Coppermine folder (e.g. "../forum/" if your bridge app is at http://www.yourdomain.tld/forum/ and Coppermine at http://www.yourdomain.tld/gallery/)
A relative path does not start with a slash - that's the visual difference to an absolute path. You need to think on folder/sub-folder level to understand the concept of relative paths. Imagine that all folders on your webserver where the branches of a tree that was turned upside down: the root being at the top and branches going to the bottom. The relative path describes the way you need to take from a particular folder (the folder where coppermine resides in) to another folder (the folder where your bridge app resides in). The notation for relative paths contains a special way to say "one level up": that's two dots, followed by a forward slash (../). This being said, let's look at some examples:
| Your coppermine install | Your bridge app install | Relative path |
|---|---|---|
| http://example.com/gallery/ | http://example.com/forum/ | ../forum/ |
| http://example.com/gallery/ | http://example.com/community/board/ | ../community/board/ |
| http://example.com/pictures/coppermine/ | http://example.com/bbs/ | ../../bbs/ |
| http://example.com/gallery/ | http://example.com/ | ../ |
| http://example.com/ | http://example.com/forum/ | forum/ |
| http://example.com/community/pix/ | http://example.com/community/ | ../ |
| http://example.com/some/very/complicated/folder/ | http://example.com/ | ../../../../ |
| http://example.com/gallery/ | http://example.com/community/forum/ | ../community/forum/ |
This has to be the cookie name of the application you bridge with. Do not enter the cookie prefix of your coppermine gallery here! You can not make this setting up - you have to look it up in the documentation or settings that come with the application you're going to bridge with.
The popular BBS application "phpBB2" is using the default cookie prefix phpbb2mysql - this can be changed by the forum administrator, so if you're not sure what your cookie prefix is, go to the config panel of the app you bridge with and look the cookie prefix up.
The cookie prefix must not be confused with the cookie path - they are entirely different animals. The cookie prefix (in some applications it is being called "cookie name" as well) is something on application level - something the people who designed your bridge app have come up with.
Should Coppermine import the special groups that exist in your bridge app? If you select no, then Coppermine will use the standard groups it comes with (Administrator, Registered and Anonymous) which makes administration easier. If you enable this option by selecting yes, you will have a more granular permissions management in coppermine and you can assign permissions in coppermine based on the membership within custom groups of your bridge app. You can change this setting later as well.
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").
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.
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.
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:
I have the following issue when trying to bridge coppermine and XXX: [error message or problem description here] Coppermine install: http://mysite.tld/my_coppermine_folder/ Bridging app install: http://mysite.tld/my_forum_folder/ Coppermine version: cpg1.5.0 Bridging app version: SuperDuper BBS app v0.8.15 Test user account: some_testuser_name / the_password_for_the_test_user_account BridgeManager settings: Bridge app URL: http://mysite.tld/test/foo_bar Relative path to your bridge app's config file: ../bla/ Cookie name or prefix: forum Use post-based groups?: 1
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.
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.
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.
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.
There are some additional remarks that apply to particular bridge files:
meta_refresh(3, append_sid("{$phpbb_root_path}index.$phpEx"));
$message = $message . '<br /><br />' . sprintf($user->lang['RETURN_INDEX'], '<a href="' . append_sid("{$phpbb_root_path}index.$phpEx") . '">', '</a> ');and replace withmeta_refresh(3, request_var('redirect', append_sid("{$phpbb_root_path}index.$phpEx")));
$message = $message . '<br /><br />' . sprintf($user->lang['RETURN_INDEX'], '<a href="' . request_var('redirect', append_sid("{$phpbb_root_path}index.$phpEx")) . '">', '</a> ');
Admin recognition for upgraded forums: if your forum has been upgraded from phpBB2 to phpBB3 you need to perform an additional step.
Edit phpbb3.inc.php, find
$this->admingroups = array(5);Change the 5 to the admin group in phpbb3. You can find this out by doing the following
$page_title = pun_htmlspecialchars($pun_config['o_board_title']).' / '.$lang_common['Login'];and add before it
$redirect_url = (isset($_GET['redir'])) ? $_GET['redir'] : $redirect_url;Then find:
redirect('index.php', $lang_login['Logout redirect']);and change to: redirect(isset($_GET['redir']) ? $_GET['redir'] : 'index.php', $lang_login['Logout redirect']);
$page_title = pun_htmlspecialchars($pun_config['o_board_title']).' / '.$lang_common['Login'];and add before it
$redirect_url = (isset($_GET['redir'])) ? $_GET['redir'] : $redirect_url;Then find
redirect('index.php', $lang_login['Logout redirect']);and change toredirect(isset($_GET['redir']) ? $_GET['redir'] : 'index.php', $lang_login['Logout redirect']);
$path = '/';just inside the top of the function
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.
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").
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.
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.