Download Source
Downloading the Latest Release
In general, you should download the latest release. This will make it easier to track where your deployment is versus the current development work for purposes of reporting bugs, diagnosing issues, and understanding available features.
Registry PE is currently in an Early Adopter phase, and is using Milestone Releases. Milestone Releases can be treated like regular releases, but they do not follow Semantic Versioning.
Download the COmanage Registry PE source files somewhere into the file system. The location you put the files does not have to be the location from which the files are served by the web server. Create a symlink to the directory called registry-pe-current (or something similar):
$ mkdir /srv/comanage $ cd /srv/comanage $ wget https://github.internet2.edu/COmanage/registry/archive/refs/tags/5.0.0.tar.gz $ tar xzf MR12.tar.gz $ ln -s MR12 registry-pe-current
Downloading the Latest Master
The main branch has the latest features that should be stable enough for use, but may not be feature complete. (Typically, though, main is the same as the latest release.) If you want the latest main, you can download it instead:
$ wget https://github.internet2.edu/COmanage/registry/archive/refs/heads/main.tar.gz
You can also download the develop branch, which is usually more bleeding edge.
$ wget https://github.internet2.edu/COmanage/registry/archive/refs/heads/develop.tar.gz
Cloning the Git Repo
If you plan on mucking around with the code, you can also clone the git repo.
Configure Web Server
Deploy the COmanage Registry PE 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-pe. A simple strategy to accomplish this when running under the Apache web server is to create a symlink in the DocumentRoot named registry-pe that points to the directory .../registry-pe-current/app/webroot:
$ cd /var/www/html $ ln -s /path/to/registry-pe-current/app/webroot registry
The preferred path /var/www or /var/www/html may vary according to your operating system, distribution, or web server configuration.
Installation at /registry Currently Recommended
It is not required to install at the URL path registry or /registry-pe. However, it is recommended to use one of these paths unless a specific reason requires the use of a different path.
Verify File Permissions
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-pe/app/config/database.php). By default, these files will not be delivered.
Create /tmp and /logs Directories
Registry PE uses local/tmp and local/logs to write temporary files and log records. You'll most likely want to make these symlinks to another location, since it is bad practice to have writable directories on the file system delivering web content. Reasonable alternatives would be /var/cache/registry-pe and /var/log/registry-pe. The easiest way to do this on a Unix-like system is to create a symlink to the new directory.
The basic required structure for the tmp directory is included in local/tmp. Be sure to replicate this in the target location.
$ cd registry-pe-current/local $ sudo mkdir /var/cache/registry-pe $ sudo mkdir /var/log/registry-pe $ sudo cp -r tmp /var/cache/registry-pe $ sudo chown -R $HTTPUSER /var/cache/registry-pe /var/log/registry-pe $ sudo chmod 700 /var/cache/registry-pe /var/log/registry-pe $ mv tmp tmp.dist $ mv logs logs.dist $ ln -s /var/cache/registry-pe tmp $ ln -s /var/log/registry-pe logs
Log Files May Be Written To The Cache Directory
The CakePHP framework may write error and debugging logs to the logs directory. You may wish to monitor and/or rotate these files. By default, the framework usually rotates the log files when they get large.
Integrate Web Server Authentication
In order to integrate COmanage Registry with your authentication system, configure your Web server to protect the directory registry-pe/app/webroot/auth/login. For example, under Apache your configuration may look something like
DocumentRoot /var/www <Directory /var/www/registry-pe/auth/login> AuthType shibboleth ShibRequestSetting requireSession 1 Require shib-session </Directory> <Location / > AuthType shibboleth Require shibboleth </Location>
For Apache, it is recommended that you place this configuration in httpd.conf rather than .htaccess, to simplify future upgrades.
If you choose to use a SAML2 service provider (SP) such as the Shibboleth Native SP or SimpleSAMLPhP for authentication you may find the COmanage Registry Shibboleth Embedded Discovery Service Plugin useful.
Integrate Web Server Logout
COmanage Registry uses a standard PHP session to track requests per user. Clicking the "Logout" button ends the PHP session but does not end any other session such as a session created during authentication by the web server authentication mechanism or module such as the Shibboleth Native SP for Apache (Shibboleth) or mod_auth_openidc. The web server authentication mechanism should be configured so that any necessary session termination happens when the browser accesses registry-pe/auth/logout.
For example with Shibboleth the following configuration will terminate the Shibboleth session and then allow the browser to continue to access registry/auth/logout:
RewriteEngine On
RewriteCond %{QUERY_STRING} !after_redirect
RewriteRule ^/registry-pe/auth/logout.* https://%{SERVER_NAME}/Shibboleth.sso/Logout?return=https://%{SERVER_NAME}/registry-pe/auth/logout/?after_redirect [L,R]