docs: update documentation

- Update README
- Create additional development documentation
- Update compose.yml

README.md

@@ -4,53 +4,89 @@ 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](LICENSE)" for more information.
 
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=org.folio%3Amod-record-specifications&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=org.folio%3Amod-record-specifications)
+
 ## Introduction
-Module for managing and validating records against predefined specifications.
 
-## Installing and deployment
+mod-record-specifications is a module for managing and validating records against predefined specifications.
+
+## Installation and Deployment
 
 ### Compiling
 
-Compile with 
+To compile mod-record-specifications, use the command: 
+
 ```shell
 mvn clean install
 ```
 
-### Running it
-Run locally on listening port 8081 (default listening port):
+### 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          |
+
+Change these variables as per your requirements.
+
+### Running The Module
 
-Using Docker to run the local stand-alone instance:
+#### Locally
+
+Run the module locally on the default listening port (8081) with the prescribed command:
 
 ```shell
-DB_HOST=localhost DB_PORT=5432 DB_DATABASE=okapi_modules DB_USERNAME=folio_admin DB_PASSWORD=folio_admin \
-   java -Dserver.port=8081 -jar target/mod-record-specifications-*.jar
+DB_HOST=localhost DB_PORT=5432 DB_DATABASE=okapi_modules DB_USERNAME=folio_admin DB_PASSWORD=folio_admin \ 
+java -Dserver.port=8081 -jar target/mod-record-specifications-*.jar
 ```
 
-### Docker
+#### Using Docker
 
-Build the docker container with:
+To run the module in a Docker container, first build the Docker image:
 
 ```shell
 docker build -t dev.folio/mod-record-specifications .
 ```
 
-Test that it runs with:
+Prepare infrastructure needed for the module: PostgreSQL database.
+Alternatively, you can use Docker Compose to manage the application's infrastructure.
+```shell
+docker compose up
+```
+
+Then run the container:
 
 ```shell
 docker run -t -i -p 8081:8081 dev.folio/mod-record-specifications
 ```
 
-### ModuleDescriptor
+### Module Descriptor
 
-See the built `target/ModuleDescriptor.json` for the interfaces that this module
-requires and provides, the permissions, and the additional module metadata.
+See the built target/ModuleDescriptor.json file for the interfaces, permissions, and additional modules required and provided by this one.
 
 ## Additional Information
 
-### Issue tracker
+### Development documentation
 
-See project [MSEARCH](https://folio-org.atlassian.net/browse/MSEARCH)
-at the [FOLIO issue tracker](https://dev.folio.org/guidelines/issue-tracker/).
+Additional development documentation exists in the [development.md](docs%2Fdevelopment.md)
+
+### Issue Tracker
+
+If you find any issues or bugs, please report at project [MRSPECS](https://folio-org.atlassian.net/browse/MRSPECS) at the FOLIO issue tracker.
 
 ### API Documentation
 
@@ -67,5 +103,6 @@ See [configuration](https://dev.folio.org/download/artifacts) for repository acc
 and the [Docker image](https://hub.docker.com/r/folioorg/mod-record-specifications/)
 
 ### Code of Conduct
+
 [FOLIO Code of Conduct](https://folio-org.atlassian.net/wiki/spaces/COMMUNITY/pages/4231255/FOLIO+Code+of+Conduct)
 

compose.yml

@@ -1,9 +1,9 @@
 services:
   postgres:
-    image: 'postgres:latest'
+    image: 'postgres:16-alpine'
     environment:
-      - 'POSTGRES_DB=modules'
-      - 'POSTGRES_PASSWORD=admin'
+      - 'POSTGRES_DB=okapi_modules'
+      - 'POSTGRES_PASSWORD=folio_admin'
       - 'POSTGRES_USER=folio_admin'
     ports:
-      - '5432'
+      - '5432:5432'

docs/development.md

@@ -0,0 +1,50 @@
+# Development documentation
+
+## Spectral
+
+Spectral is an extensible platform for creating linting rules to enforce your style guide across your API descriptions.
+
+Use it for linting API definition against [rules file](..%2F.spectral.yaml).
+
+You can install it locally via npm:
+```shell
+npm install -g @stoplight/spectral
+```
+
+You can run Spectral against your API definition from repository root like so:
+
+```shell
+spectral lint api/mod-record-specifications.yaml -F hint
+```
+
+Check out the [Spectral documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md) on how to write and organize rules.
+
+## Spring Boot Dev Tools
+
+Spring Boot DevTools is a set of tools and features providing developers with a better development experience.
+
+It does constitute several features including:
+* Automatic restart: Anytime files on the classpath change, the application is restarted. This saves the time often spent redeploying changes.
+* Live reload: With the LiveReload browser extension, you can automatically refresh your browser anytime files change.
+
+To use just start application as usual, do changes and code, build project and changes will be reflected without restarting.
+
+See the [official reference](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-devtools) for more information about Spring Boot DevTools.
+
+
+## Docker Compose Support in Spring Boot
+
+Docker Compose is a service that you can use to define and manage multiple container applications. 
+Spring Boot provides support for Docker Compose through the `spring-boot-docker-compose` module. 
+When included as a dependency, Spring Boot will automatically start the services defined in your `compose.yml`, 
+create service connection beans for each supported container and stop the services when the application is shutdown.
+
+To use Docker Compose with Spring Boot, you need to do the following:
+
+1. Ensure the docker and docker compose command-line applications are installed on your machine.
+2. Spring Boot will perform various tasks such as looking for a `compose.yml` and calling `docker compose up` and `docker compose stop` during its lifecycle. You can customize this process with properties such as `spring.docker.compose.lifecycle-management`, `spring.docker.compose.start.command`, and `spring.docker.compose.stop.command`.
+3. If your setup uses a custom image name, you can use a label `org.springframework.boot.service-connection: custom` in your `compose.yml` to ensure Spring Boot can find it.
+4. If you want to ignore a specific container in your compose file, tag it with the label `org.springframework.boot.ignore: true`.
+5. Finally, remember to run your application, and Spring Boot will take care of running the compose file, and creating service connections for supported containers. The setup should work automatically, but remember you have many options to tweak the behavior. Enjoy your streamlined Spring Boot and Docker Compose development process!
+
+More details can be found in the official [Spring Boot Docker Compose](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.docker-compose) documentation.