-
Notifications
You must be signed in to change notification settings - Fork 2
Configuration
- Directory layout
- Security configuration
- Bootstrap registers
- Base URI
- General configuration
- Logging
- UI templates
All configuration and operating information for the registry is stored (by default) in the directory /var/local/registry.
When a registry instance first starts up then each area of the directory will be initialized if it does not exist. The only exception to this is that, for technical reasons with the Tomcat context definition, an empty ui/ directory should exist for successful start-up.
The layout of the operating directory is summarized below.
Directory or file | Purpose
----|------|----
boot/ | Definitions of bootstrap registers used when starting a registry with no data.
boot/system | The bootstrap definition of the system registers.
config/ | Configuration and initialization files.
config/root-register.ttl | RDF file describing the root register, used during bootstrapping only.
config/services.conf | Configuration parameters for the software, defines the set of service components that make up the registry and provides configuration parameters for them.
config/user.ini | Initialization for the security database, provides OpenIDs and grant information for initial users. Not consulted once the userstore database exists.
index/ | Lucene free text index for the registry content.
log/ | Log files
log/registry.log | The current log recording recent registry requests.
logstore/ | File copies of all uploaded registration and update payloads.
proxy-conf.sh | Script used to trigger the nginx proxy to reconsult configuration information, should be set to be sudo executable by the tomcat user.
proxy-registry.conf | Proxy configuration script generated by the registry. Other scripts with the naming pattern proxy-*.conf may be added here to support additional manual proxy rules.
store/ | The RDF data store (an Apache Jena TDB instance).
templates/ | Set of templates defining the built in UI, written in Apache Velocity.
ui/ | Resources (CSS, image and javascript files) which should be served from the /ui path of the registry URL.
userstore/ | Database holding security information (registrations and grants), an embedded instance of Apache Derby.
Once the registry is running all security information is held in the database in the userstore directory. Configuration of user permissions is then done through the user interface.
If no userstore database exists then it will be initialized by loading the initial user information from config/user.ini. If no such configuration file exists then a null one will be created.
To set up an administrator for a new installation then the bootstrap userstore should be removed and the bootstrap config/user.ini should be edited to define the administrator.
The user.ini file comprises a set of declarations, one per line (lines beginning with # are comment lines).
User registration entries start with the user keyword and take the form:
user openid "name"
For example:
user https://profiles.google.com/1147194443288764760228 "Alice"
An OpenID profile for anyone with a Google account can be obtained from their profile or Google-plus home page and copying the long number from there into the above URL pattern. A general Google login generates an OpenID which depends on the requesting web site as well as the user. To determine the ID in that case start the bootstrap registry, register the target user and note the resulting OpenID, then shutdown the registry and modify the initialization file accordingly.
There is a built in anonymous user with pseudo OpenID of http://localhost/anon. It is convenient to declare that user in the initialization file as well, so as to bind a visible name to that id. For example:
user http://localhost/anon "Any authenticated"
The second type of declaration line is used to grant permissions to a user. These take the form:
openid permission
For example:
https://myopenid Update:/register/item
https://myotheropenid GrantAdmin
In particular the GrantAdmin permission makes the user an administrator.
Thus a minimal user.ini configuration looks something like:
user https://profiles.google.com/1147194443288764760228 "Alice"
user http://localhost/anon "Any authenticated"
https://profiles.google.com/1147194443288764760228 GrantAdmin
When a registry instance runs for the first time it needs to create an initial RDF description. There are two parts to this bootstrapping - the root register and all other registers (including the system registers and manager-supplied initial data).
The root register is a special case because of its different naming convention and because there is no register into which to add it. The root register is bootstrapped by loading an initial RDF file (/config/root-register.ttl) which must contain both the reg:Register declaration and an associated reg:RegisterItem. Each of these must meet minimum constraints for the versioning model (have an owl:versionInfo value and a version:currentVersion link, which can point to itself). The URI of the root register must match the declared base URI for the registry installation (see below).
Once the root register is in place then the normal API mechanisms for loading register declarations and registered items can function. In particular use of "relative" addresses is then possible so any such bootstrap files can be independent of the registry base URI.
The additional initial registers are loaded from the area boot/. Each directory in the boot area corresponds to a register and should contain a metadata.ttl defining it. It may also contain sub-directories for sub-registers and other *.ttl files defining items to be included in the register.
When a registry first starts up, if the bootstrap files for either of these kinds of register do not exist then a default minimum set will be created. Then if the RDF data store does not exist (store/ and the associated free index in index/) then one will be created and initialized from the bootstrap files.
Thus if you start a blank registry installation that will create both a minimal set of bootstrap files and an initialized store. Normally you will then need to halt the registry, edit the bootstrap files to suit the deployment requirements and delete the initial store/ and index/ areas. Restarting the registry will then rebuild the store based on your customized bootstrap.
The registry will create and serve all data relative to an assumed base URI. This needed not be the same as the URL at which the registry installation is hosted - either because this is a staging deployment or because some external proxy will map requests from the real URI to the hosting system.
The base URI can only be set at the time that a registry instance initially starts up. Once the initial store has been created all data in that store will hold absolute URIs which are based on the configured base URI.
There are two places where the base URI must be configured.
Firstly, the registry software itself is configured from the file config/services.conf, see below. In that file change the following line to give a suitable base URI:
registry.baseURI = http://ukgovld-registry.dnsalias.net/
Secondly, the initial bootstrap RDF for the root register must be consistent with this. This is defined in config/root-register.ttl (see above).
The registry software is configured through a single file config/services.conf. This file uses the Java Properties format. The file is used to configure a series of software components which together make up the registry. It is possible to provide alternative implementations of some of these components and configure them through this file. The configuration is a series of blocks, one for each component, which take the form:
component = qualified.name.of.class
component.prop1 = value1
...
component.propN = valueN
In most cases the name of the component is arbitrary, when one component depends on another an explicit parameter setting is used to give the name of the dependent component to use.
The parameter string ${webapp} and be used in configuration values and will be expanded with the location of the running registry application.
In normal use very few of these parameters should need customization, so we will only summarize the key ones.
The registry service itself.
| Key property | Meaning |
|---|---|
| baseURI | The base URI at which the registry is assumed to operate. |
| pageSize | The number of items that should be returned by list views of collections (i.e. registers). |
| log | Area used for recording registration/update payloads. |
| bootSpec | A sequence of possible locations for the bootstrap root register, tried in order. |
| systemBoot | The location of the boot areas for loading system and other registers. |
| store, forwarder, userStore | References to the other required components |
The template rendering system used the generate the default UI.
| Key property | Meaning |
|---|---|
| production | If true then run in production mode where macros cannot be updated and templates, once cached in memory, are assumed not to change. If false then any change to a template will be detected and cause a change to the UI. |
| templates | Directory where the template files are located. |
The RDF data store for the registry.
| Key property | Meaning |
|---|---|
| location | The directory where the RDF database is held. |
The (Lucene) free text index.
| Key property | Meaning |
|---|---|
| location | The directory where the text index is held. |
The user registration and authorization database.
| Key property | Meaning |
|---|---|
| initfile | The bootstrap file to use to initialize the user database if it does not exist. |
| dbfile | The directory in which the user database is stored. |
Component used to manage forwarding/proxy configurations. This will handle redirects itself and will implement any proxy forwarding by dynamically configuring a separate nginx instance.
| Key property | Meaning |
|---|---|
| proxyConfDir | Directory where nginx proxy scripts will be written. |
| proxyRestartScript | Shell script which will be used to cause nginx to reconsult the configuration scripts. |
Logging of accesses to the registry is done by the nginx front end proxy. See the nginx configuration documentation.
In addition all requests that reach the registry itself will be logged. For requests from authenticated users the user name and their OpenID will be included, for other requests the originating IP address is (should be, when that's fixed!) recorded. This log will also include messages from internal software components. The registry logging is configured by log4j.properties within the registry application itself. Currently this will log to file (log/registry.log) and to standard output (which means it will be captured by the velocity logging).
The html styling for an registry pages requested in text/html format is handling by the velocity templating system. The builtin registry UI is implemented using these templates. The templates are all stored in the templates/ directory within the operating area. As usual, if this area does not exist at registry start up time then one will be created containing the default templates.
The key templates for customization are:
| Template | Use |
|---|---|
main.vm |
The entry point, the registry will invoke main.vm in response to any request to a registry resource in text/html format. |
header.vm |
Included in all top level templates to provide the HTML header information including page title and loading of style sheets. |
navbar.vm |
Included in all top level templates to render the top level navigation bar. |
footer.vm |
Included in all top level templates to provide the running foot, load all required javascript libraries and close the HTML page. |
root.vm |
Called by the main.vm to render the home page of the registry (root register). |
In addition to the calls of main.vm from the registry itself, requests to the /ui area of the registry are handled specially. They can either directly invoke a UI template or are served as files to provide the style sheets, images and javascript libraries needed for the UI.
| Request URI | Action |
|---|---|
/ui/template |
If a template called template.vm exists then it will be used to render the response, examples include about.vm and login.vm. |
/ui/* |
All other requests fall through to the underlying Tomcat engine, which in turn serves these files from the ui/ directory in the operating area. |
Configuring the document base from which Tomcat will serve the plain UI files is currently done by setting an alias in a META-INF/context.xml file in the web app itself. The configuration of aliases is Tomcat specific so that switching to a different application server would require some minor modifications to the web app.
When a velocity template is invoked the following environment variables will be bound
| Variable | Bound to | Instance of |
|---|---|---|
| $uri | The relative path of the resource being requested | String |
| $registry | The Registry object, access configuration info and invoke API operations from here | com.epimorphics.registry.core.Registry |
| $subject | The security subject, can test if the user is authenticated and check permissions | org.apache.shiro.subject.Subject |
| $requestor | Name of the person making the current request | String |
| $request | The incoming HTTP request | javax.servlet.http.HttpServletRequest |
| $language | The language code for the user's locale | String |