Operation

Notes on common administration tasks for an installed registry instance. See Installation for how to install an instance and perform the initial configuration.

Contents

• Starting the registry service
• Stopping the registry service
• Restarting the nginx proxy
• Updating the registry software
• Backups

Starting the registry service

The registry service runs a Tomcat web app. To start it use:

sudo service tomcat7 start

or

sudo service tomcat7 restart

Look at the start-up log messages to check for any issues:

sudo tail -f /var/log/tomcat7/catalina.out

Stopping the registry service

The registry service runs a Tomcat web app. To halt it use:

sudo service tomcat7 stop

Restarting the nginx proxy

The nginx proxy runs as a separate service and should not normally need restarting.

To force it to reconsult the configuration information use:

/var/local/registry/proxy-conf.sh

The service can be completely restarted using:

sudo service nginx restart

This is also useful if a general software update has updated the nginx software but not restarted the running instance.

Updating the registry software

Changes to the registry software can affect two aspects of the system. Firstly, the web app software itself may be upgraded. Secondly, the UI templates and possibly the associated style sheets, images and javascript resources may be updated.

Updating the software itself simply requires deploying a new war to the tomcat running instance. In practice this is best done by stopping the service, completely replacing the war, and then restarting it.

However, any change to the templates and ui resources is complicated by the existence of the external copies in the operational area (normally /var/local/registry) and any customization of them.

If no customization of the UI templates has been performed then the full installation process is:

# Assumes in directory with updated registry war
sudo service tomcat7 stop
sudo rm -rf /var/lib/tomcat7/webapps/ROOT*
sudo rm -rf /var/local/registry/templates /var/local/registry/ui/*
sudo cp ukl-registry-*.war /var/lib/tomcat7/webapps/ROOT.war
sudo service tomcat7 start

When the registry starts up the templates and the different resource areas under ui will be recreated with the new version.

If any of the templates or style information has been changed then these will need to be reinstalled after the update. Whether this can be done at the file level or by patching individual files depends on the nature of the customization (and the nature of changes made in the webapp).

Backups

The critical state information for the registry is all kept in the operational area (normally /var/local/registry/). All of this directory tree should ideally be preserved but the critical areas are:

Directory or file | Purpose ----|------|---- store/ | The RDF data store (an Apache Jena TDB instance). index/ | Lucene free text index for the registry content. userstore/ | Database holding security information (registrations and grants), an embedded instance of Apache Derby. proxy-registry.conf | Proxy configuration script generated by the registry.

Backup options are:

Option	Discussion
EBS	Arrange for the operations area /var/local/registry/ to be stored on an EBS volume. Since EBS itself provides replication and high reliability that may be sufficient for some continuity goals.
Hot snapshots	Each of the stores used attempts to maintain consistent state on disk, e.g. in the form of journal files. So that a backup of the operational area while the service is running should be safe.
Stable snapshots	For absolute safety of backups then stop the running service before taking a snapshot of the operations area.
Journal replay	For the registry content itself then a complete record is kept of registration and update actions, including the associated payload. In principle it would be possible to replay these to reconstruct a registry state even in the event of total corruption of the running store. The in-progress message queue infrastructure will make this option more practical.

These options can be combined. In particular, running on EBS means that the EBS snapshot facility can be used to take a snapshot of the whole area.

Restoring a snapshot should only be done when the service is stopped. In some circumstances restarting the service over a restored snapshot may trigger a complaint from the text indexing service that the index area is locked. This can be resolved by deleting a Lucene lock file /var/local/registry/index/write.lock.