3. Configuring Turtles

Turtles is configured via YAML files containing YAML configuration objects. This chapter introduces each of these YAML configuration objects, and the chapter Turtles Configuration Reference offers a complete reference of their syntax.

• Turtles Plugin Building Operations need to know about:

  • One or more plugin sets, specified by plugin set definitions (see Configuring a Plugin Set) and/or plugin set catalog definitions (see Configuring a Plugin Set Catalog), or, if neither are specified, by a Default Plugin Set Catalog File.

  • plugin signing credentials, specified by a plugin signing credentials definition (see Configuring Plugin Signing Credentials), or, if not specified, by a Default Plugin Signing Credentials File.

• Turtles Plugin Deployment Operations need to know about one or more plugin registries, specified by plugin registry definitions (see Configuring a Plugin Registry) and/or plugin registry catalogs (see Configuring a Plugin Registry Catalog), or, if neither are specified, by a Default Plugin Registry Catalog File.

3.1. Configuring a Plugin Set

Tip

For detailed information about plugin set definitions, see Plugin Set Definition Reference.

Most plugin set code projects are Maven projects that use the parent POM org.lockss:lockss-plugins-parent-pom. In this typical scenario, the plugin set definition looks like this:

---
kind: PluginSet
id: my-plugin-set
name: My Plugin Set
builder:
  type: maven

This requires a display name (name), and an identifier [1] (id).

Conventionally, this definition is stored in a file named turtles.yaml (or turtles.yml, or alternatively a .yaml or .yml file named after the plugin set's id) in the project's top-level directory, that is, in the directory containing the project's pom.xml file:

|
+-- src/
|   +-- main/
|   |   +-- java/
|   |       +-- ...
|   +-- test/
|   |   +-- java/
|   |       +-- ...
+-- pom.xml
+-- turtles.yaml

Legacy Ant projects (deprecated)

Warning

This plugin set type is deprecated.

Some LOCKSS plugin code project are Ant projects that use the LOCKSS Program's legacy Ant build (from the LOCKSS 1.x system). In this legacy situation, the plugin set definition looks like this:

---
kind: PluginSet
id: my-plugin-set
name: My Plugin Set
builder:
  type: ant

This requires a display name (name), and an identifier [1] (id).

This definition is stored in a file named turtles.yaml in the project's top-level directory, that is, in the directory containing the project's build.xml file:

|
+-- plugins/
|   +-- src/
|   |   +-- ...
|   +-- test/
|   |   +-- src/
|   |       +-- ...
+-- build.xml
+-- turtles.yaml

3.2. Configuring a Plugin Set Catalog

Tip

For detailed information about plugin set catalog definitions, see Plugin Set Catalog Definition Reference.

If you are working with multiple plugin sets, and even if you are working with just one, it is convenient to list one or more plugin sets in a plugin set catalog. Furthermore, to avoid specifying a plugin set catalog each time you invoke one of the Turtles Plugin Building Operations, you can save this plugin set catalog definition in a Default Plugin Set Catalog File which is loaded by default when no plugin sets and/or plugin set catalogs are specified.

A plugin set catalog definition looks like this:

---
kind: PluginSetCatalog
plugin-set-files:
  - /opt/plugins/our-plugin-project/turtles.yaml
  - /opt/plugins/secondary-plugin-project/turtles.yaml
  - ...

Relative plugin set file paths are understood to be relative to the plugin set catalog definition file.

3.2.1. Default Plugin Set Catalog File

If no plugin set nor plugin set catalog is specified with --plugin-set/-s or --plugin-set-catalog/-S options (respectively), Turtles loads a default plugin set catalog file, trying each of the following until one is found:

1. $HOME/.config/lockss-turtles/plugin-set-catalog.yaml, which is typically /home/$USER/.config/lockss-turtles/plugin-set-catalog.yaml for the given user on the machine

2. /etc/lockss-turtles/plugin-set-catalog.yaml

3. /usr/local/share/lockss-turtles/plugin-set-catalog.yaml

3.3. Configuring a Plugin Registry

Tip

For detailed information about plugin registry definitions, see Plugin Registry Definition Reference.

The simplest kind of plugin registry has a single layer, conventionally named production, and is a directory of plugin JAR files, each a .jar file named after the plugin's identifier (plugin_identifier in the plugin definition XML). The plugin registry definition in this scenario would look like this:

---
kind: PluginRegistry
id: our-project-plugin-registry
name: Our Project Plugin Registry
layout:
  type: directory
layers:
  - id: production
    name: Our Project Plugin Registry Plugin Registry (Production)
    path: /var/www/props.ourproject.org/plugins/production
plugin-identifiers:
  - org.ourproject.plugin.plugin1.Plugin1
  - org.ourproject.plugin.plugin2.Plugin2
  - ...

Plugin registries with two layers are also common, conventionally one called testing and the second production:

---
kind: PluginRegistry
id: our-project-plugin-registry
name: Our Project Plugin Registry
layout:
  type: directory
layers:
  - id: testing
    name: Our Project Plugin Registry Plugin Registry (Testing)
    path: /var/www/props.ourproject.org/plugins/testing
  - id: production
    name: Our Project Plugin Registry Plugin Registry (Production)
    path: /var/www/props.ourproject.org/plugins/production
plugin-identifiers:
  - org.ourproject.plugin.plugin1.Plugin1
  - org.ourproject.plugin.plugin2.Plugin2
  - ...

Relative plugin registry layer directory paths are understood to be relative to the plugin registry definition file. Using the two-layer example above, this means that another way to express the same plugin registry definition would be to store it in the file /var/www/props.ourproject.org/plugins/turtles.yaml and write its layers section as:

layers:
  - id: testing
    name: Our Project Plugin Registry Plugin Registry (Testing)
    path: testing
  - id: production
    name: Our Project Plugin Registry Plugin Registry (Production)
    path: production

3.4. Configuring a Plugin Registry Catalog

Tip

For detailed information about plugin registry catalog definitions, see Plugin Registry Catalog Definition Reference.

If you are working with multiple plugin registries, and even if you are working with just one, it is convenient to list one or more plugin registries in a plugin registry catalog. Furthermore, to avoid specifying a plugin registry catalog each time you invoke one of the Turtles Plugin Deployment Operations, you can save this plugin registry catalog definition in a Default Plugin Registry Catalog File which is loaded by default when no plugin registries and/or plugin registry catalogs are specified.

A plugin registry catalog definition looks like this:

---
kind: PluginRegistryCatalog
plugin-registry-files:
  - /var/www/props.ourproject.org/plugins/turtles.yaml
  - /var/www/props.otherproject.net/plugins/turtles.yaml
  - ...

Relative plugin registry file paths are understood to be relative to the plugin registry catalog definition file.

3.4.1. Default Plugin Registry Catalog File

If no plugin registry nor plugin registry catalog is specified with --plugin-registry/-r or --plugin-registry-catalog/-R options (respectively), Turtles loads a default plugin registry catalog file, trying each of the following until one is found:

1. $HOME/.config/lockss-turtles/plugin-registry-catalog.yaml, which is typically /home/$USER/.config/lockss-turtles/plugin-registry-catalog.yaml for the given user on the machine

2. /etc/lockss-turtles/plugin-registry-catalog.yaml

3. /usr/local/share/lockss-turtles/plugin-registry-catalog.yaml

3.5. Configuring Plugin Signing Credentials

Tip

For detailed information about plugin signing credential definitions, see Plugin Signing Credentials Definition Reference.

Each user who might sign plugins requires plugin signing credentials. A plugin signing credentials definition looks like this:

---
kind: PluginSigningCredentials
plugin-signing-keystore: /home/user123/secrets/user123.keystore
plugin-signing-alias: user123

This requires a path to a plugin signing keystore (plugin-signing-keystore) and the alias of the user within the keystore (plugin-signing-alias). A relative plugin signing keystore path is understood to be relative to the plugin signing credentials definition file.

3.5.1. Default Plugin Signing Credentials File

If no plugin signing credentials are specified with --plugin-signing-credentials/-c option, Turtles loads a default plugin signing credentials file, trying each of the following until one is found:

1. $HOME/.config/lockss-turtles/plugin-signing-credentials.yaml, which is typically /home/$USER/.config/lockss-turtles/plugin-signing-credentials.yaml for the given user on the machine

2. /etc/lockss-turtles/plugin-signing-credentials.yaml

3. /usr/local/share/lockss-turtles/plugin-signing-credentials.yaml

---

Footnotes

[1]

Although Turtles does not enforce a particular syntax, the intended shape of these identifiers is that they are made of lowercase letters and digits, optionally separated by hyphens or underscores, excluding spaces and other characters/punctuation. Turtles may specify the exact syntax of identifiers in a future version.