Page History

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 or later is required. No special build options are currently required, other than support for whatever database you plan on using.

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 and that the mod_rewrite module is enabled.

Install Source

Download the COmanage Registry source files to your selected directory.

$ svn co http://anonsvn.internet2.edu/svn/gears/tags/0.2a
$ ln -s 0.2a gears

Install the COmanage Registry directory wherever you like, and configure your web server to deliver it at a suitable URL (such as https://some-vo.org/registry or https://registry.some-vo.org). Specifically, set the web server to deliver gears/app/webroot as the document root.

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/gears/app/config/database.php). By default, these files will not be delivered.

You'll most likely want to move the gears/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 gears/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 gears/app/webroot/auth/login. For example, under Apache you may place an .htaccess the file in that directory with contents similar to this:

AuthType shibboleth
ShibRequestSetting requireSession 1
require valid-user

Database Server Setup

COmanage Registry is tested against Postgres 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.)

Create a new database for COmanage Registry. You can name the new database whatever you like. Set the configuration information, including the password to connect to the database with, in app/config/database.php.  You will also need to add the prefix "cm_" until this has been fixed.

For COmanage Registry 0.3 and later

Set up the database schema.

$ cd cake/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 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 cake/console
$ ./cake setup
Enter administrator's given name
> Pat
Enter administrator's family name
> Lee
Enter administrator's login username
> plee@university.edu

Installation Steps

1. PHP
2. Web Server
3. Download and Install Source
4. Database
5. Email
6. Registry Setup Script
7. Cron
8. Testing

9. Setting Up Your First CO

10. QA and Production Tiers
11. High availability (HA) considerations

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

...

• .