Introduction

When the initial development of a new back-end (server-side) module is established, and snapshot artifacts are being reliably generated by the continuous integration, then it is able to be added to the folio-snapshot reference environments (and hence to the relevant virtual machine VMs).

There is a separate procedure to install a new front-end module.

(After the new module has been operating in snapshot reference environments, and an initial release is ready to be made, then instead follow the release procedures.)

Avoid typical mistakes

Before proceeding, ensure that the backend module does not make some of the typical mistakes that cause disruption.

Note that this is not an exhaustive list.

• The module version number (e.g. in Maven POM) is a semantic version number and snapshot designator, i.e. in mainline branch it should be x.y.z-SNAPSHOT. Avoid common mistakes like x.y-SNAPSHOT or x.y.z with no appended -SNAPSHOT.
• The port numbers are matching – the same in ModuleDescriptor, Dockerfile, and in program code and configuration.
• For Spring Way modules, the default port is 8080. FOLIO does not care which port. However if the module is going to use a different port, then be sure to also declare that server.port in its application.yaml file.
• For Spring Way modules, the replacement tokens in Descriptors use delimiters “@” rather than the normal “$”.
• Ensure that the ModuleDescriptor is generated from its template and that tokens are replaced. For Maven-based modules, the POM will have configuration to “filter-descriptor-inputs” and “rename-descriptor-outputs”.
• Other …

Verify MD and required interfaces

Ensure that this new module’s ModuleDescriptor is deployed and that any required interfaces are available.

For example, consider the mod-notes module. Obtain its MD from the registry and extract the “requires” section:

curl -s -S -w'\n' \
  'https://folio-registry.dev.folio.org/_/proxy/modules?filter=mod-notes&latest=1&full=true' \
  | jq '.[].requires'

That shows that it requires various interfaces, including “users 15.1” and “configuration 2.0”.

Now ensure that each needed interface version is available. One method is to visit the https://folio-snapshot.dev.folio.org/settings/about page.

Ensure LaunchDescriptor

Ensure that this new module’s ModuleDescriptor includes the Docker-based LaunchDescriptor.

Its properties will specify the memory allocation, whether this module utilises a database, and can document other environment variables, etc.

Ensure module health endpoint

The module must provide the module health check endpoint to enable verification of the module deployment.

Prepare special requirements

If there are special requirements beyond those declared in the default LaunchDescriptor, then document those in the module README.

Remember that there are other systems operators, as well as FOLIO DevOps, that need to know how to install the module.

Also prepare beforehand if there are special requirements for FOLIO infrastructure, additional to what is already provided. Add Jira tickets (as described below) to completely explain the services that the new module requires. Do not expect us to know. Allow sufficient time to establish these.

Ensure recent local VM

Ensure that the module will operate with a recent local Vagrant VM.

Follow the guide to verify Deploy a module.

That procedure will verify that the most recent published module is ready to be installed in the reference environments.

Request add new module

Before proceeding, verify that the module is ready to be added, including the above-mentioned steps.

Prepare the Jira ticket to guide the process, and request that the new backend module be enabled for the snapshot reference environments.

If there are special requirements, then provide a link to that section of the module README.

Raise a FOLIO DevOps Jira ticket.

Note: Plan for plenty of time for this phase. Our team will already have a full Sprint. So it will likely be a subsequent Sprint.

The DevOps team will configure the module and conduct various configuration tests.

Verify deployment

After merge, await the scheduled build of the folio-snapshot reference environments.

Visit the Software versions page of each to verify that the new module is present.