Renaming In Progress
COmanage Gears is being renamed to COmanage Registry. Some paths have not yet been changed, and so you may still see some references to /gears
.
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.
PCRE Bug May Cause Problems
There are known issues with earlier versions of the PCRE library that will cause COmanage Registry to be unable to set up its database tables. Version 6.6 and earlier are known to have problems, while versions 8.02 and later are known to work. You can check the version that PHP was built against by running this command:
php -r 'phpinfo();' | grep PCRE
If you are using an old version of PCRE, you'll first need to install a more recent version. Be sure to configure it with the --enable-utf8 --enable-unicode-properties
flags. You'll then need to rebuild PHP against the newer version of the PCRE library.
Alternately, you may be able to rebuild PHP using its own internal copy of PCRE.
Install Source
Download the COmanage Registry source files to your selected directory.
$ svn co http://anonsvn.internet2.edu/svn/gears/tags/0.2 $ ln -s 0.2 gears
Web Server Setup
The web server should operate under SSL. Make sure the server is capable of rendering PHP.
Install the COmanage Registry directory wherever you like, and configure your web server to deliver it at a suitable URL (such as https://site.edu/registry
or https://registry.site.edu
). 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://site.edu/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
.
Set up the database schema. You will need permission to write to the tmp directory (set above) to run this command.
Installing from trunk?
Run ./cake schema create -s 3
below, instead.
$ cd cake/console $ sudo ./cake schema create ... 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.
If you get the error message /path/to/app/config/schema/schema.php could not be loaded
while trying to create the schema, you are running an old version of the PCRE library. See the warning earlier on this page for more information.
Upgrading from 0.1 to 0.2
There is not currently an elegant way to upgrade database schemas that involve new tables (see COmanage and CakePHP issue tracking).
To upgrade 0.1 to 0.2, run ./cake schema create -s 3
as above. Be sure to answer no when asked to drop the existing tables, or else you will lose all your existing data. You will also see a bunch of errors about tables already existing – you can safely ignore those.
[...] The following table(s) will be dropped. [...] Are you sure you want to drop the table(s)? (y/n) [n] > n <-- be sure to answer n here! The following table(s) will be created. [...] Are you sure you want to create the table(s)? (y/n) [y] > y [lots of warnings about existing tables]
TBD: It's unclear if this will catch ALTER TABLE
statements. If not, running ./cake schema update -s 3
afterwards should fix things up.
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
setup
is intended to be run once. After you run it, you should be able to login via the web interface and make whatever changes you need that way. If you need to run it again, the easiest approach is to drop the database and start over.