{"id":23122815,"url":"https://github.com/folio-org/mod-configuration","last_synced_at":"2025-08-28T06:13:39.501Z","repository":{"id":10805492,"uuid":"65995478","full_name":"folio-org/mod-configuration","owner":"folio-org","description":"Configuration module based on the raml-module-builder and a set of raml and json schemas backed by a postgresdb async implementation","archived":false,"fork":false,"pushed_at":"2025-08-05T05:08:33.000Z","size":677,"stargazers_count":1,"open_issues_count":0,"forks_count":5,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-08-17T03:35:32.174Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/folio-org.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-08-18T12:31:23.000Z","updated_at":"2025-03-15T11:15:44.000Z","dependencies_parsed_at":"2024-12-17T07:30:47.337Z","dependency_job_id":"a985136f-5a93-468b-9c82-6640d36e7d29","html_url":"https://github.com/folio-org/mod-configuration","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/folio-org/mod-configuration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-configuration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-configuration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-configuration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-configuration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/folio-org","download_url":"https://codeload.github.com/folio-org/mod-configuration/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-configuration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272452421,"owners_count":24937465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-28T02:00:10.768Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T07:30:38.676Z","updated_at":"2025-08-28T06:13:39.487Z","avatar_url":"https://github.com/folio-org.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mod-configuration\n\n\nCopyright (C) 2016-2025 The Open Library Foundation\n\nThis software is distributed under the terms of the Apache License, Version 2.0. See the file [\"LICENSE\"](https://github.com/folio-org/mod-configuration/blob/master/LICENSE) for more information.\n\n## Purpose\n\nConfiguration module based on the raml-module-builder and a set of raml and json schemas backed by a PostgreSQL async implementation\n\n## Deprecation\n\n*mod-configuration has been deprecated due to security problems since March 2022. Modules still using mod-configuration have to move to other solutions after the Ramsons release.*\n\n*Please do not add new configuration values to this module.*\n\nInstead, consider either:\n* Using [mod-settings](https://github.com/folio-org/mod-settings), a conceptually similar centralized-configuration module which fixes [the security flaw](https://github.com/MikeTaylor/folio-docs/blob/main/doc/fixing-mod-configuration.md#backward-compatibility-and-migration) that makes this module unsuitable.\n* Creating CRUD APIs to store configuration and settings values in the storage module they belong to.\n\nFor Sunflower release the mod-configuration services will be restricted to read- and delete-only. This allows for migration.\n\nmod-configuration will be removed in the release following the Sunflower release.\n\nFor details see the [Technical Council RFC 006 Folio distributed vs. centralized configuration](https://github.com/folio-org/rfcs/blob/master/text/0006-folio-distributed-vs-centralized-configration.md).\n\n## Permission warning\n\nThe permission granularity is too coarse.  Permission is always granted to all values, there is no way to grant permission to only a selected set of values.  This applies to read access, and it also applies to write access.\n\nTherefore don't store passwords or other confidential or critical values in mod-configuration.  See previous section for other options.\n\n## Introduction\n\nThis project is built using the raml-module-builder, using the PostgreSQL async client to implement some basic configuration APIs. It is highly recommended to read the [raml-module-builder README](https://github.com/folio-org/raml-module-builder/blob/master/README.md) since there are many features that the mod-configuration module inherits from the raml-module-builder framework.\n\nThe idea behind this module is to provide a type of centralized configuration service. The service allows for the creation of module configurations. Within a module there are named configurations, and within a named configuration there are 1..N 'rows'.\n\n```sh\n-\u003e Module\n\n    -\u003e config 1 -\u003e row 1\n\n    -\u003e config 1 -\u003e row 2\n\n    -\u003e config 2 -\u003e row 1\n\n    -\u003e config 2 -\u003e row 2\n\n    -\u003e config 2 -\u003e row 3\n\n```\n\nThis would in turn look something like:\n\nModule| configName | updatedBy | default | enabled | code | value | desc | userId\n------------ | ------------- | -------------  | -------------  | -------------  | -------------  | -------------  | ------------- | -------------\n |  |\nCIRCULATION| import.uploads.files | Joe | false | true | path_2_file | PENDING | file to import | uid\nCIRCULATION| patron.drools | Joe | false | true | rule_name1 | base64enc_drools_file| rule file |\nCIRCULATION| patron.drools | Joe | false | true | rule_name2 | base64enc_drools_file| rule file | uid\n\nThe above table can be interpreted as follows:\n\nModule: **CIRCULATION**\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;Config name: **patron.drools**\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; row: **rule_name1** (the code of the row)\n\nNote that each tenant has its own schema with its own configuration tables. The userId field can be populated to associate an entry in the table with a specific user.\n\nsee configuration schema for an object description:\nhttps://github.com/folio-org/mod-configuration/blob/master/ramls/_schemas/kv_configuration.schema\n\n### Instructions\n\nclone / download mod-configuration then `mvn clean install`\n\nRun:\n\n`java -jar mod-configuration-server/target/mod-configuration-server-fat.jar -Dhttp.port=8081\n\n\nOr run via Dockerfile\n\nThe Configuration service can be run in either embedded PostgreSQL mode or with a regular PostgreSQL server.\n\nNote that the embedded PostgreSQL is started on a static port (6000)\n\n### Connecting to an existing configuration service\n\nThe configuration module also comes with a statically typed Java client.\nTo use the client via maven, add:\n\n```sh\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.folio\u003c/groupId\u003e\n      \u003cartifactId\u003emod-configuration-client\u003c/artifactId\u003e\n      \u003cversion\u003e1.0.0\u003c/version\u003e\n    \u003c/dependency\u003e\n```\n\n```sh\nConfigurationsClient cc = new ConfigurationsClient(\"config.server.host\", port, \"mytenantid\");\n\ncc.getEntries(\"module==CIRCULATION\", 0, 10, \"en\", response -\u003e {\n  response.bodyHandler(body -\u003e {\n    System.out.println(body);\n  });\n});\n\nString content = getFile(\"kv_configuration.sample\");\nConfig conf = new ObjectMapper().readValue(content, Config.class);\ncc.postEntries(null, conf, reply -\u003e {\n  reply.bodyHandler( handler -\u003e {\n   System.out.println(new String(handler.getBytes(), \"UTF8\"));\n  });\n});\n```\n\n#### Query syntax\nThe configuration module supports the [CQL (Contextual Query Language)](https://github.com/folio-org/raml-module-builder#cql-contextual-query-language) syntax.\n\nNote: Use `==` for string comparison. `=` is a full text word search.\n\n### Auditing\nEvery change to entries is automatically audited by the service.\nTo see an audit list:\n\n`http://\u003chost\u003e:\u003cport\u003e/configurations/audit`\n\n#### Querying audit records\n\nCQL syntax is also supported by the audit API\n\n### Examples\n\nMake sure to include appropriate headers as the runtime framework validates them.\n\n`Accept: application/json`\n\n`Content-Type: application/json`\n\n\n```sh\n\nQuery for all tables:\n(GET)\nhttp://localhost:8081/configurations/entries\n\n\nQuery for a specific module / config / row:\n(GET)\nhttp://localhost:\u003cport\u003e/configurations/entries?query=code==PATRON_RULE\n\n\n\nAdd an entry:\n(POST)\nhttp://localhost:8081/configurations/entries\n{\n  \"module\": \"CIRCULATION\",\n  \"configName\": \"validation_rules\",\n  \"updatedBy\": \"joe\",\n  \"code\": \"PATRON_RULE\",\n  \"description\": \"for patrons\",\n  \"default\": true,\n  \"enabled\": true,\n  \"value\": \"any value\"\n}\n\nDeleting / Updating specific entries is possible as well - See circulation.raml file.\n```\n\n## Additional information\n\n### Types of Configuration Records\n#### Tenant\nThese are records which are not associated with a user (no `userId` property).\n\nThey represent a configuration setting for a tenant, and is the default if no user setting is in place (see validation section for what how records are intended to be matched).\n\n#### User\nThese are records which are associated with a user (a `userId` property is present).\n\nThey represent a configuration setting for a specific user, which is considered to take precedence over a matching tenant setting (if present).\n\n### Defaults\n\n#### Enabled\nConfiguration records are defaulted to be enabled (`enabled` is true) if the client does not provide a value for the `enabled` property.\n\nThis applies to both newly created records, and records being replaced using PUT.\n\n### Validation\nAs of version 5.0.0, configuration records are validated to be unique for combinations of certain properties.\n\nDisabled properties (`enabled` is false) are ignored during these checks.\n\nThese checks are applied separately for tenant and user level records, in order for it to be possible to have user level record precedence for the same setting.\n\n#### Module and Config Name\nIf no code is present, a setting is considered to be unique for the `module` and `configName` properties.\n\n#### Module, Config Name and Code\nIf a code is present, a setting is considered to be unique for the `module`,  `configName` and `code` properties.\n\n#### Implementation\n\nThese checks are achieved by using four unique indexes.\n\nTwo of these are for the two variations above at the tenant level configurations and the other two at the user level.\n\nSee the [declarative schema](mod-configuration-server/src/main/resources/templates/db_scripts/schema.json) for how these are defined.\n\n### Other documentation\n\nThe [raml-module-builder](https://github.com/folio-org/raml-module-builder) framework.\n\nOther [modules](https://dev.folio.org/source-code/#server-side) are described,\nwith further FOLIO Developer documentation at [dev.folio.org](https://dev.folio.org/)\n\n### API documentation\n\nThis module's [API documentation](https://dev.folio.org/reference/api/#mod-configuration).\n\n### Issue tracker\n\nSee project [MODCONF](https://issues.folio.org/browse/MODCONF)\nat the [FOLIO issue tracker](https://dev.folio.org/guidelines/issue-tracker/).\n\n### Quick start\n\nCompile with `mvn clean install` and see further [instructions](#instructions).\n\nRun the local stand-alone instance:\n\n```\njava -jar mod-configuration-server/target/mod-configuration-server-fat.jar \\\n  -Dhttp.port=8081 embed_postgres=true\n```\n\nAdditional command-line [options](#instructions) and information.\n\n### ModuleDescriptor\n\nSee the built `target/ModuleDescriptor.json` for the interfaces that this module\nrequires and provides, the permissions, and the additional module metadata.\n\n### Code analysis\n\n[SonarQube analysis](https://sonarcloud.io/dashboard?id=org.folio%3Amod-configuration).\n\n### Download and configuration\n\nThe built artifacts for this module are available.\nSee [configuration](https://dev.folio.org/download/artifacts/) for repository access,\nand the [Docker image](https://hub.docker.com/r/folioorg/mod-configuration/).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-configuration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffolio-org%2Fmod-configuration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-configuration/lists"}