- PHP
- Web Server
- Checkout and Install Source
- Database
- Email Configuration
- Initial Configuration
- Testing
- Next Steps
- Troubleshooting
(add next/prev or TOC to each page?)
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.6.1 $ ln -s 0.6.1 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
Installation at /registry Currently Required
COmanage Registry currently assumes it is installed at the URL path /registry
(CO-299). Until this is fixed, you should make COmanage Registry available at https://your-site.org/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>
If your authentication system supports a logout directive, create a similar configuration protecting auth/logout
.
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
Upgrading From 0.1 to 0.3
Upgrading from 0.1 to 0.3 or later is not supported and edu_person_affiliation was renamed to affiliation.
Upgrading Database Schemas Past 0.3
When upgrading the database schema (past 0.3) on Postgres, you may see "Possibly failed to update database schema" instead. This is probably OK. (CO-165)
Database Upgrade Required for 0.5
When upgrading to 0.5 from 0.4 or earlier, a database schema update is required.
Database Upgrade Required for 0.6
When upgrading to 0.6 from 0.5 or earlier, a database schema update is required.
In addition, types for the table cm_identifiers have changed in order to support Extended Types. Given the pre-production nature of the code, there is no automated tool to update these types. Manually alter cm_identifiers:type
values to match the new definitions. eg: update cm_identifiers set type='eppn' where type='EP';
Error: Database connection "Mysql" is missing, or could not be created
This error indicates the command line php
utility can't find the appropriate PDO library. Go back and make sure your PHP was built correctly.
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.
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
Upgrading from 0.1 to 0.2 is not supported due to a structural change in the data model.
Email Setup
COmanage Registry can use email to deliver invitations for enrollment and for notifications. By default, mail is configured to use CakePHP's MailTransport class, which itself uses PHP's mail() function.
You can change the default configuration via app/Config/email.php
.
You can specify the mail From:
address on a per-Enrollment Flow basis.
Support for further reconfiguration of mail delivery via the UI is planned. (CO-390)
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 > >
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.
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 necessarymod_rewrite
directives. Not all Apache configurations by default allow configuration options within.htaccess
files. Be sure that your Apache configuration has the necessaryAllowOveride
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.