mod-record-specifications

Copyright (C) 2024 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.

Introduction

mod-record-specifications is a module for managing and validating records against predefined specifications.

Installation and Deployment

Compiling

To compile mod-record-specifications, use the command:

mvn clean install

Tenant attributes

It is possible to define specific tenant parameters during module's initialization for particular tenant.

Tenant parameter	Default value	Description
syncSpecifications	true	Sync Specifications as module is enabled for the new tenant

Environment Variables

Below are the environment variables used by this module:

Variable Name	Default Value	Description
DB_HOST	localhost	Postgres hostname
DB_PORT	5432	Postgres port
DB_USERNAME	folio_admin	Postgres username
DB_PASSWORD	folio_admin	Postgres username password
DB_DATABASE	okapi_modules	Postgres database name
DB_MAXPOOLSIZE	10	Max pool size allowed, including both idle and in-use connections
DB_MINIMUM_IDLE	10	Min number of idle connections that HikariCP tries to maintain in the pool
DB_CONNECTION_TIMEOUT	30000	Max number of milliseconds that a client will wait for a connection from the pool
DB_IDLE_TIMEOUT	600000	Max amount of time that a connection is allowed to sit idle in the pool, applicable when DB_MINIMUM_IDLE < DB_MAXPOOLSIZE
DB_KEEPALIVE_TIME	0	Frequency of connection keep alive attempts by HikariCP to prevent time-out by database/network. 0 means disabled
DB_MAX_LIFETIME	1800000	Max lifetime of a connection in the pool
DB_VALIDATION_TIMEOUT	5000	Max amount of time a connection is tested for aliveness. Must be less than DB_CONNECTION_TIMEOUT
DB_INITIALIZATION_FAIL_TIMEOUT	30000	Defines whether the pool will 'fail fast' if it can't be seeded with an initial connection
DB_LEAK_DETECTION_THRESHOLD	30000	Time a connection can be out of the pool before a message is logged for a possible connection leak. 0 means disabled
KAFKA_HOST	kafka	Kafka broker hostname
KAFKA_PORT	9092	Kafka broker port
KAFKA_SECURITY_PROTOCOL	PLAINTEXT	Kafka security protocol used to communicate with brokers (SSL or PLAINTEXT)
KAFKA_SSL_KEYSTORE_LOCATION	-	The location of the Kafka key store file. This is optional for client and can be used for two-way authentication for client.
KAFKA_SSL_KEYSTORE_PASSWORD	-	The store password for the Kafka key store file. This is optional for client and only needed if 'ssl.keystore.location' is configured.
KAFKA_SSL_TRUSTSTORE_LOCATION	-	The location of the Kafka trust store file.
KAFKA_SSL_TRUSTSTORE_PASSWORD	-	The password for the Kafka trust store file. If a password is not set, trust store file configured will still be used, but integrity checking is disabled.

Change these variables as per your requirements.

Running The Module

Using Docker Compose (Recommended)

The recommended way to run the module locally is using Docker Compose. This provides a complete development environment with all dependencies.

# Build the module JAR
mvn clean package -DskipTests

# Start all services (infrastructure + module)
docker compose -f docker/app-docker-compose.yml up -d

# View logs
docker compose -f docker/app-docker-compose.yml logs -f mod-record-specifications

For detailed Docker Compose documentation, see docker/README.md.

Local Development with IntelliJ IDEA

For local development, you can run the application directly from IntelliJ IDEA with the dev profile. Spring Boot will automatically start the required infrastructure services (PostgreSQL, Kafka) using Docker Compose.

1. Open the project in IntelliJ IDEA
2. Run the main application class with the dev profile active
3. Spring Boot will automatically start infrastructure containers from docker/infra-docker-compose.yml

Manually Running the Module

Run the module locally on the default listening port (8081) with infrastructure services:

# Start infrastructure services
docker compose -f docker/infra-docker-compose.yml up -d

# Run the module
DB_HOST=localhost DB_PORT=5432 DB_DATABASE=okapi_modules DB_USERNAME=folio_admin DB_PASSWORD=folio_admin \
KAFKA_HOST=localhost KAFKA_PORT=29092 \
java -Dserver.port=8081 -jar mod-record-specifications-server/target/mod-record-specifications-fat.jar

Using Docker (Legacy)

To run the module in a Docker container:

# Build the module JAR
mvn clean package -DskipTests

# Build the Docker image
docker build -t dev.folio/mod-record-specifications .

# Run with Docker Compose
docker compose -f docker/app-docker-compose.yml up -d

Module Descriptor

See the built target/ModuleDescriptor.json file for the interfaces, permissions, and additional modules required and provided by this one.

Additional Information

Development documentation

Additional development documentation exists in the development.md

Issue Tracker

If you find any issues or bugs, please report at project MRSPECS at the FOLIO issue tracker.

API Documentation

This module's API documentation.

Code analysis

SonarQube analysis.

Download and configuration

The built artifacts for this module are available. See configuration for repository access, and the Docker image

Code of Conduct

FOLIO Code of Conduct