Installation

This section applies only to first-time installation. If you are upgrading, see the Upgrading chapter instead.

 

dmBridge is a client-server system. The client is (or can be) the template engine, which drives one or more of your custom template sets. The server is the dmBridge core (HTTP API) component, which drives the template engine and the PHP API. The client can run on any server, including the CONTENTdm® server, but the server must run on the CONTENTdm® server. It's your decision on which server you want to the template engine to reside, but to keep the instructions simple, we'll put everything on the CONTENTdm® server for now. Moving it later will be as simple as moving the files and setting the new URL in the Control Panel. Extracting a downloaded dmBridge distribution will result in a single folder called something like dmbridge-x.x.x. Within it there are four folders:

api
The dmBridge core
data
Configuration data required by dmBridge (and possibly social data as well)
objects
The template engine
ctrl
The Control Panel (essentially a graphical front-end to dmBridge's main configuration file, data/config/config.xml)

Each folder is a separate component that requires a few simple installation steps, documented in the following subsections. But before we proceed, we want to move our downloaded files onto the web server:

  1. Rename the dmbridge-x.x.x folder to dm
  2. Move the dm folder into your CONTENTdm® web server's document root. (This is the same place where your current cdm4 and dmscripts folders reside.

Next, we are ready to set up our individual components.

Core (HTTP API)

Installation of the dmBridge core (HTTP API) involves two main steps: installation of the core itself, and installation of the configuration data.

Please read these steps very carefully.

  1. Move the dm/data folder somewhere where it is not web-accessible. This may be anywhere outside your web server's document root; or you may be able to lock down a directory with an Apache/IIS configuration directive. Failure to complete this step means that your database password and/or social data will be exposed to the public.
  2. Make sure the permissions on the dm/data folder are set so that the web server process has read/write access to all of the files and folders inside it.
  3. CONTENTdm® 4.x only; if running 5.x, skip to the next step. In Content4/docs/dmscripts/DMSystem.php, find the following line near the very top:

    $slash = getPath();

    And change it to (don't worry, this shouldn't adversely affect anything):

    // Modified for dmBridge (your name, date)
    $slash = $_SERVER['DOCUMENT_ROOT'] . '/';
    // $slash = getPath(); // commented out for dmBridge
  4. CONTENTdm® 5.x only; if running 4.x, skip to the next step. In Content5/docs/dmscripts/DMSystem.php, find the following around line 1811:

    print("<!-- $url //-->\n");

    And comment it out by appending two slashes to it:

    // print("<!-- $url //-->\n");

  5. Open api/config.php.
  6. Change CDM_ROOT to the absolute path to your CONTENTdm® PHP API folder (called dmscripts).
  7. Change DATA_ROOT to the absolute path to your data folder from step 1. (Locating it with a relative path ["../"] will not work.)

    If you are unsure of the absolute path, create an empty PHP script in the same folder, type the following code into it, and load it in a web browser:

    <?php die(dirname(__FILE__)); ?>

  8. This will show you the full path to your dmBridge core folder. Adjust it appropriately to point to your data folder instead. Make sure to change any backslashes to forward slashes.

  9. If necessary, change the other settings in the file. If not sure, skip to the next step.
  10. Navigate to the following URLs and verify that they output XML without any <dmException> elements showing up (you may have to view the page source to see it):
    • http://my_cdm_server/dm/api/?r=collections.xml
    • http://my_cdm_server/dm/api/?r=objects/uw.xml
    • http://my_cdm_server/dm/api/?r=objects/uw/5.xml

    (Change "/uw" in the URLs above to a different collection alias ("CISOROOT") if the Sample Collection is not live on your CONTENTdm® server.)

If everything appears OK, the installation was successful. This was the hardest component to install; the others will be easier.

Template engine

The template engine is a one-step installation process.

  1. Open dm/objects/config.xml. If necessary, change the <param name="api.url"> element to the URL of the dmBridge core that you set up in the previous section. (By default, http://localhost/dm/api/.)

The template engine is now installed, but it does not work yet. We need to configure some stuff in the Control Panel first, which we will get to soon.

Control Panel

Installing the Control Panel takes two steps:

  1. Open dm/ctrl/config.php and set CDM_ROOT and DATA_ROOT appropriately.
  2. Open dm/ctrl/config.php and set URL_OF_LOGIN_EXE to the full URL of your login.exe file. Normally this will just mean changing "my_cdm_server" to your web server's hostname.

Finally, try to log in by navigating to http://my_cdm_server/dm/ctrl/ and entering your CONTENTdm® username and password. (This is the same username and password you use to log into the admin module located at /cgi-bin/admin/start.exe on your server.)

Once you are in, you need to complete some initial setup:

  1. In the Basic Setup section, set all URLs appropriately.
  2. In the Collections -> Template Set Mapping section, click Change.
  3. If you do not have the Sample Collection (the UW Buildings collection with alias of "/uw") installed:
    1. Go to Template Sets -> View All
    2. Click Edit next to the Basic template set
    3. Choose a new default collection for it.

Finally, navigate to http://my_cdm_server/dm/objects/. You should see your default collection appear in the basic template set. At this point, you are done with the essential installation steps, but there are some other things you'll want to look at before deploying dmBridge in a production environment, which the remainder of this section will discuss.

Securing the Control Panel

By default, anyone on the Internet can get to the Control Panel's login page. If you only plan on using the Control Panel internally, you may want to block it off from the public Internet by restricting access to the dm/ctrl folder from outside your LAN (or your desktop PC, or whatever). The procedure for doing this varies depending on your web server.

Apache

Host-based access control is available with Apache's mod_authz_host. Create an .htaccess file in your dm/ctrl folder something like the following:

<Files "*">
Order deny,allow
Deny from All
Allow from my_great_institution.edu
Allow from 100.x.x.
</Files>

You can put this in your httpd.conf as well, but remember to change Files "*" to the location of your Control Panel folder.

IIS

Please post a comment if you are familiar with this.

Data store

If you wish to use the commenting, social tagging, or rating features, you will need to configure a data store on the server. dmBridge currently supports three different data stores:

SQLite 3 (default)
A simple file-based database library that is fast, reliable, and easy to configure. Recommended if you don't have access to a MySQL or PostgreSQL server. Requires the PHP PDO extension. Will not work over an NFS or CIFS share.
MySQL
Requires the PHP PDO extension.
PostgreSQL
Requires the PHP PDO extension.

Configuring MySQL/PostgreSQL

The MySQL/PostgreSQL data store options are intended for institutions that already have a MySQL/PostgreSQL server set up and available for use, and have someone on staff who knows the basics of administering them. If this is not the case, you should use SQLite instead. Installation instructions for the MySQL/PostgreSQL databases themselves will not be provided here; we will assume they are already up and running at your site.

Configuring with PHP

MySQL and PostgreSQL require the PHP PDO extension for use with dmBridge. To verify that it is installed, run phpinfo():

<?php
phpinfo
();
?>

And search for a "PDO" section. If you don't also see a "pdo_mysql" or "pdo_pgsql" section (depending on your database), you will need to install the appropriate PDO driver. Depending on your OS distribution, it may be available as a package, or you may have to install it from PECL:

# pecl install pdo_mysql
# pecl install pdo_pgsql

Please post a comment if you need assistance.

Creating the database

dmBridge does not have a tool for creating the database; you will have to create it yourself. You should not have to create the tables; see the next section.

Enabling in the Control Panel

The final step is to enter the database connection settings. Log in to the Control Panel, navigate to the Data Store section, select your database, and enter the connection settings.

If the database does not already have the required dmBridge tables, the Control Panel will attempt to create them. If this should happen to fail for some reason, you can manually run (and if necessary, tweak) one of the sample SQL scripts provided in the dm/ctrl/core/data/schema folder.

Configuring SQLite

Downloading and installing SQLite

Note: The OCLC hosted environment already has SQLite installed, so hosted users can skip this section.

Windows

From the SQLite download page, download the "sqlitedll-3_x_x.zip" file and unzip it into your windows\system32 folder. Restart IIS.

Linux

SQLite may already be installed. Check your package manager or try find / -name 'libsqlite*' and see if anything turns up. If not, download the "sqlite-3.x.x.so.gz" file from the SQLite download page, install it, and restart Apache. Please post a comment if you need assistance with this.

Solaris

Please post a comment if you have any information about SQLite on Solaris.

Configuring with PHP

SQLite requires the PHP PDO extension. To verify that it is installed, run phpinfo():

<?php
phpinfo
();
?>

And search for a "PDO" section. If you don't also see a "pdo_sqlite" section, you will need to install the PDO driver for SQLite:

# pecl install pdo_sqlite

Please post a comment if you need assistance.

Enabling in the Control Panel

The final step (which is the same across all platforms) is to enable the SQLite in the Control Panel. Log in to the Control Panel, navigate to the Data Store section, select SQLite 3 and enter the path to the database file.

Clean URLs

The HTTP API and Templating Engine both support URL rewriting, which is optional, but recommended. Check it out:

A cool URI befitting of the Mobots

Using the HTTP API as an example, some normal URLs might look like this:

http://my_cdm_server/dmapi/?r=objects/uw/3
http://my_cdm_server/dmclient/?r=uw/3

With URL rewrite support enabled, these would become:

http://my_cdm_server/dmapi/objects/uw/3
http://my_cdm_server/dmclient/uw/3

The latter are cleaner and more "taxonomically correct," if you will. They go further toward hiding your implementation details, which is a good thing. They become uniform resource identifiers rather than just lowly locators.

URL rewriting is easy to get working on both Apache and IIS. On Apache, it requires the mod_rewrite module to be enabled in httpd.conf. On IIS, there are a few different options, but one that we have minor experience with is ISAPI Rewrite. The free Lite version does not support .htaccess files, but it's easy enough to add global rules instead. Here is a sample set:

RewriteCond %{REQUEST_FILENAME} !-f [OR]
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^/dm/objects(.*)$ /dm/objects/index.php?q=$1 [L,QSA]

This gets saved in C:\Program Files\Helicon\ISAPI_Rewrite3\httpd.conf. Naturally, you want to change /dm/objects to the path to your template engine. You can use the same rules in your Apache httpd.conf as well if you can't or don't want to use .htaccess files. (Keep reading.)

The dmBridge template engine includes a .htaccess file which the web server should read (if it is configured to do so; in Apache, see the AllowOverride directive in httpd.conf). This is all that is needed; just enable rewriting in dm/objects/config.xml and it will be enabled in all of your template sets. Do the same thing in dm/api/config.php as well and it will be enabled in the HTTP API, too.

If you are worried about the performance impact of enabling .htaccess files, they will typically add less than a few thousandths of a second to each page request, depending on the performance of the server and the depth of the folder in the filesystem.

Reference URL redirection

Reference URLs are persistent locators for CONTENTdmĀ® objects that look like this:

http://digital.library.unlv.edu/u?/hughes,87

Notice how the page that loads has a different URL than the reference URL. Accessing a reference URL redirects you to the CONTENTdmĀ® template corresponding with that object. dmBridge, however, is going to use a different template, with a different URL. You will, therefore, want to selectively redirect your reference URLs depending on which templating system the object appears in. The way to do this is by installing the provided replacement reference URL routing script.

The default reference URL routing script lives in /u/index.php (relative to your CONTENTdmĀ® server's document root). The replacement script lives in the dm/api/u/ folder. Follow the directions below to hook it up:

  1. Make a backup of /u/index.php
  2. Copy dm/api/u/index.php to /u/index.php
  3. Open /u/index.php and edit DMAPI_ROOT, if necessary
  4. Set up your redirects in the "Reference URLs" section of the Control Panel