-
Notifications
You must be signed in to change notification settings - Fork 9
Operation
Notes on common administration tasks for an installed registry instance. See Installation for how to install an instance and perform the initial configuration.
- Starting the registry service
- Stopping the registry service
- Restarting the nginx proxy
- Updating the registry software
- Backups
- Text index
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
The registry service runs a Tomcat web app. To halt it use:
sudo service tomcat7 stop
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.
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).
The critical state information for the registry is all kept in the operational area (normally /var/opt/ldregistry/). All of this directory tree should be preserved. 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. |
The core information to backup is the content of the underlying triple store (/var/opt/ldregistry/store). This may be saved as a database dump (in compressed n-quad format) at any point, even if concurrent updates are occuring.
This is supported through the user interface Admin > Backups > Schedule backup.
A backup can also by trigger by sending a POST request to:
{registrybase}/system/backup
A GET request from that endpoint will return a plain text status message initially:
Backup in progress: {filename}
then, when the backup has completed, it will return
Last backup: {filename}
In a typical deployment a CRON job can be used to schedule regular database backups.
The location of the generated dump file is configured through the app.conf settings and defaults to /var/opt/ldregistry/backup.
To restore the system from a backup of /var/opt/ldregistry/ it should be sufficient to stop the application server (e.g. Tomcat), restore the state directory tree and restart the server.
The triple store maintains a journal file on the filesystem and will recover any transactions which had not been flushed onto the database disks blocks at the time of the backup.
In some cases a file level restore may leave the lucene text index locked. This may be solved by deleting /var/opt/ldregistry/index/write.lock.
Rebuild the store from a dump file using the Apache Jena command line tools.
tdbloader --loc store backup-{timestamp}.nq.gz
rm -r /var/opt/ldregistry/store
mv store /var/opt/ldregistry/store
The text search index may be rebuild from an existing, or newly restored, triple store by using the Apache Jena text indexing tools.
java -cp $FUSEKI_HOME/fuseki-server.jar jena.textindexer --desc=index.ttl
rm -r /var/opt/ldregistry/index
mv index /var/opt/ldregistry/index
where $FUSEKI_HOME is points to an installation of Apache Jena fuseki (or similar).
An example index assembler file is provided in tools/index.ttl in this repository. If the deployed instance has customized the indexed properties (through the app.conf settings) then a matching customization of the assembler file will be required.
In normal operation then adding an entry, whether by UI upload or by external API request, should cause it to be automatically indexed in the text index.
However, there are situations where the text index can get out of date. Firstly, true deletion will not reliably delete text index entries. Secondly, direct manipulation of the database files as part of system maintenance has been known to result in a disconnect between the triple store and text index.
The text index can be rebuilt using the menu Admin > Rebuild text index. This is a highly invasive action and is best performed when other users are not using text search. Restarting the tomcat war after a re-index is a useful check that the index has really succeeded and that in-memory state is clean, though should not be necessary.
The text index can also be rebuilt while the registry is not running using raw Jena commands. The easiest way to do this is to obtain a copy of the fuseki jar file (which contains a full set of Jena operations included jena-text). For example, a java7-compatible distribution is available from http://archive.apache.org/dist/jena/binaries/jena-fuseki1-1.1.2-distribution.tar.gz
Then (assuming a standard layout):
cd /var/opt/ldregistry
curl -s https://raw.githubusercontent.com/UKGovLD/registry-core/master/tools/index.ttl > index.ttl
java -cp $FUSEKI_HOME/fuseki-server.jar jena.textindexer --desc=index.ttl
Where $FUSEKI_HOME is set to the directory where you installed the fuseki distribution or jar.