View Source

Prerequisites

While COmanage Directory is designed to work in a LAMP environment, the only required component is PHP. Other modern operating systems and web servers should work. Configuration of these prerequisites is generally beyond the scope of this documentation.

PHP

PHP 5.2.8 or later is required, with LDAP support enabled (built with --with-ldap).

Web Server Setup

The web server should be configured to deliver content over HTTPS (via TLS/SSL).

Make sure the server is capable of rendering PHP. On Linux systems most often the installation of PHP enables the php5_module but you should confirm it has been enabled. The configuration of Apache to use the module and parse .php files as PHP is also often done when PHP is installed but you should confirm that your Apache configuration contains lines similar to these:

<IfModule mod_php5.c>
    <FilesMatch "\.ph(p|tml)$">
        SetHandler application/x-httpd-php
    </FilesMatch>
    <FilesMatch "\.phps$">
        SetHandler application/x-httpd-php-source
    </FilesMatch>
</IfModule>

You may wish to restrict the configuration for parsing of .php files to the COmanage Directory directory by embedding the <FilesMatch> element inside of an appropriate <Directory> element. See the Apache httpd documentation.

Configure the directory holding COmanage Directory to allow symlinks, overrides, and accept index.php. For Apache, something like the following should work:

<Directory "/path/to/docroot/directory">
    Options Indexes FollowSymLinks
    DirectoryIndex index.php
    AllowOverride All
    Order allow,deny
    Allow from all
</Directory>

Make sure that the mod_rewrite Apache module is installed and enabled.

Checkout Source

Checkout the COmanage Directory source files somewhere into the file system. The location you put the files does not have to be the location from where the files are served by the web server. Create a symlink from the tag to directory-source:

$ svn co http://anonsvn.internet2.edu/svn/comanage/directory/tags/0.1
$ ln -s 0.1 directory-source

Deploy

Deploy the COmanage Directory directory wherever you like. Note that the user that the web server runs as needs to be able to read all the files.

Configure your web server to deliver the directory at a suitable URL such as https://some-vo.org/directory. A simple strategy to accomplish this when running under the Apache web server is to create a symlink in the DocumentRoot named directory that points to the directory .../directory-source/app/webroot:

$ cd /var/www
$ ln -s /path/to/directory-source/app/webroot directory

You should verify that the web server will not deliver unprocessed files, especially configuration files such as the LDAP configuration file (ie: https://some-vo.org/directory/app/Config/ldap.php). By default, these files will not be delivered.

You'll most likely want to move the directory-source/app/tmp directory, since it is bad practice to have writable directories on the file system delivering web content. A reasonable alternative would be /var/cache/directory. The easiest way to do this on a Unix-like system is to create a symlink to the new directory.

$ cd directory-source/app
$ sudo cp -r tmp /var/cache/directory
$ sudo chown -R $HTTPUSER /var/cache/directory
$ sudo chmod 700 /var/cache/directory
$ mv tmp tmp.not
$ ln -s /var/cache/directory tmp

In order to integrate COmanage Directory with your authentication system, configure your Web server to protect the directory directory/app/webroot/auth/login. For example, under Apache your configuration may look something like

DocumentRoot /var/www
<Directory /var/www/directory/auth/login>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
</Directory>

LDAP Server Setup

Edit directory/app/Config/ldap.php to have settings suitable for your LDAP server. Contact your LDAP administrator for the appropriate settings.

Database Server Setup

COmanage Directory does not use a database server.

Testing

To test open a web browser and browse to https://yourserver.org/directory (or wherever you mounted the directory for your web server}. You should be able to search for entries from your LDAP server.

Troubleshooting

The directory directory-source/ contains a .htaccess with necessary mod_rewrite directives. Not all Apache configurations by default allow configuration options within .htaccess files. Be sure that your Apache configuration has the necessary AllowOveride configuration to allow that .htaccess file to be processed (this is not the default on Debian Squeeze and other Linux distributions).