Registry Installation

Prerequisites

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

PHP

PHP 5.2.8 or later is required, along with php5-xsl (built with --with-xsl).

PHP will work with many different database servers but here we demonstrate how to test that PHP was built with support for MySQL or PostgreSQL, assuming that you have already installed and configured the database server and have created a user named registry_user.

error_reporting = E_ALL & ~E_STRICT

To test if PHP was built with support for MySQL create the file mysql-test.php with contents

<?php
mysql_connect("localhost", "registry_user", "a password goes here") or die(mysql_error());
echo "Connected to MySQL<br/>";
?>

To test if PHP was built with support for PostgreSQL create the file postgreSQL-test.php with contents

<?php
pg_connect("host=localhost dbname=test user=registry_user password=password") or die(pg_last_error());
echo "Connected to PostgreSQL<br/>";
?>

Either run the command line php tool on the file or serve it from your webserver and make sure that the script can connect to your database server.

Be sure to remove that file after testing so it is not exposed on your web server.

$ php -r 'phpinfo();' | grep pdo
pdo_mysql
pdo_mysql.default_socket => /var/lib/mysql/mysql.sock => /var/lib/mysql/mysql.sock
pdo_sqlite

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 Registry directory by embedding the <FilesMatch> element inside of an appropriate <Directory> element. See the Apache httpd documentation.
• Configure the directory holding COmanage Registry to allow symlinks, overrides, and accept index.php. For Apache, something like the following should work:

  <Directory "/path/to/docroot/registry">
      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 Registry 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 registry-source:

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

Deploy

Deploy the COmanage Registry 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 registry at a suitable URL such as https://some-vo.org/registry. A simple strategy to accomplish this when running under the Apache web server is to create a symlink in the DocumentRoot named registry that points to the directory .../registry-source/app/webroot:

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

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

You'll most likely want to move the registry-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/registry. The easiest way to do this on a Unix-like system is to create a symlink to the new directory.

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

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

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

Database Server Setup

COmanage Registry is tested against PostgreSQL and MySQL, but should work against any database supported by CakePHP.

If you are using MySQL, use the InnoDB storage engine, not MyISAM. To set this as the default storage engine on a Unix-like system, add the following to /etc/my.cnf and restart mysql before setting up the database tables:

# Set default engine to InnoDB
default-storage-engine=InnoDB

(You can also set the storage engine on a per-session or per-table basis, see the MySQL documentation for details.)

Create a new database for the COmanage Registry. You can name the new database whatever you like since you configure the Registry below with the name of the database.

Make a copy of the file registry-source/app/Config/database.php.default in that same directory named database.php. Set the configuration information, including the password to connect to the database with, in registry-source/app/Config/database.php. The configuration options are detailed in comments in that file but for reference we show an example configuration below for MySQL and for PostgreSQL (Note that you need to configure the 'prefix' => option to be "cm_" until this has been fixed).

var $default = array(
 'driver' => 'Database/Mysql',
 'persistent' => false,
 'host' => 'localhost',
 'login' => 'registry_user',
 'password' => 'a good password goes here',
 'database' => 'registry',
 'prefix' => 'cm_',
 );

var $default = array(
 'driver' => 'Database/Postgres',
 'persistent' => false,
 'host' => 'localhost',
 'login' => 'registry_user',
 'password' => 'a good password goes here',
 'database' => 'registry',
 'prefix' => 'cm_',
 );

Next set up the database schema. There are separate instructions for COmanage Registry version 0.3 and later and versions 0.2 and 0.1:

For COmanage Registry 0.3 and later

Set up the database schema.

$ cd app
$ ./Console/cake database
[...]
Database schema update successful

For COmanage Registry 0.1 and 0.2

Set up the database schema. You will need permission to write to the tmp directory (set above) to run this command.

$ cd registry-source/cake/console
$ sudo ./cake schema create -s 4
...
The following table(s) will be dropped.
...
Are you sure you want to drop the table(s)? (y/n)
[n] > n

The following table(s) will be created.
...
Are you sure you want to create the table(s)? (y/n)
[y] > y
...
End create.

Initial Configuration

Run the initial configuration script. Be sure to enter the username that will be returned by your web server's authentication engine. For example, under Apache this corresponds to $REMOTE_USER.

$ cd app
$ ./Console/cake setup
Enter administrator's given name
> Pat
Enter administrator's family name
> Lee
Enter administrator's login username
> plee@university.edu
Enter >= 40 character security salt or blank for random  Enter >= 40 character security salt or blank for random
>
Enter >= 29 digit security seed or blank for random
>
>

Testing

To test open a web browser and browse to https://yourserver.org/registry (or wherever you mounted the registry for your web server}. You should see a very plain page (this will be changed in the future) with "Welcome to COmanage" and a link to "Login". Click on the link and you should be prompted to authenticate using whichever mechanism you configured. After properly authenticating you should see the COmanage Registry dashboard.

Next Steps

After logging in as a platform administrator, you may wish to edit the CMP Enrollment Configuration to suit your needs.

Troubleshooting

• The directory registry-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).
• Following an upgrade, failure to login due to Auth.User.name doesn't exist may be due to caches that need to be cleared.

• Messages like Warning (2): preg_match(): Compilation failed: unknown option bit(s) set at offset -1 [CORE/Cake/Utility/Validation.php, line 782] are indicative of a bad version of PCRE, described above.