{"id":23122752,"url":"https://github.com/folio-org/mod-settings","last_synced_at":"2025-08-17T02:31:11.948Z","repository":{"id":73374582,"uuid":"580459805","full_name":"folio-org/mod-settings","owner":"folio-org","description":"Secure global and per-user settings for FOLIO","archived":false,"fork":false,"pushed_at":"2025-07-29T15:37:36.000Z","size":180,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-07-29T18:23:27.812Z","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":"2022-12-20T16:03:50.000Z","updated_at":"2025-07-29T15:37:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"eab8d314-80d9-483d-9d28-fd63d2e7e55f","html_url":"https://github.com/folio-org/mod-settings","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/folio-org/mod-settings","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-settings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-settings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-settings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-settings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/folio-org","download_url":"https://codeload.github.com/folio-org/mod-settings/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-settings/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270798894,"owners_count":24648047,"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-17T02:00:09.016Z","response_time":129,"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:14.302Z","updated_at":"2025-08-17T02:31:11.939Z","avatar_url":"https://github.com/folio-org.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mod-settings\n\nCopyright (C) 2022-2025 The Open Library Foundation\n\nThis software is distributed under the terms of the Apache License,\nVersion 2.0. See the file \"[LICENSE](LICENSE)\" for more information.\n\n## Introduction\n\nmod-settings is a key-value store that provides a more secure\nconfiguration system than the old mod-configuration.\n\nSee [Fixing the security problem in mod-configuration](https://github.com/MikeTaylor/folio-docs/blob/main/doc/fixing-mod-configuration.md)\nfor more information.\n\nIt is currently implemented with PostgresQL as storage.\n\nA setting consists of these required properties\n\n* `id`: unique identifier (UUID)\n* `scope`: it is a namespace for the setting. This could be module\n* `key`: a readable identifier; not necessarily for display\n* `value`: any type (integer, string, object, array)\n\nAnd optionally:\n\n* `userId`: the owner of the setting\n\nWe call settings without userId 'global'. Global settings must be unique\nfor scope and key. Non-global settings must be unique for scope, key\nand userId.\n\nSettings are protected by permissions.\n\nIn order to write to a global setting, the client must have permission\n`mod-settings.global.write.`scope, where scope is used in the setting.\nTo read this type of setting, the client must have\n`mod-settings.global.read.`scope.\n\nIn order to write to a setting with any userId, which we call a user\nsetting, the client must have permission `mod-settings.users.write.`scope ,\nwhere scope is used in the setting. To read this type of setting,\nthe client must have `mod-settings.users.read.`scope.\n\nIn order to write to user's own setting, the client must have permission\n`mod-settings.owner.write.`scope, where scope is used in the setting.\nTo read this type of setting, the client must have\n`mod-settings.owner.read.`scope.\n\nWith 'read' in this context we mean able to read the content of\nthe setting. With 'write' in this context we modify storage\nusing POST, PUT and DELETE.\n\nWe expect that most users will have read-write permission on their own\nsettings, and read-only permission on global entries.\n\nThe API is CRUD-like, but with some important changes for some.\n\nCreate a setting [with](https://s3.amazonaws.com/foliodocs/api/mod-settings/settings.html#operation/postSetting):\n\n    POST /settings/entries\n\nThis is write operation and returns 204 if successful. The\n`id` property is required and must be supplied by the client.\n\nFetch a particular setting [with](https://s3.amazonaws.com/foliodocs/api/mod-settings/settings.html#operation/getSetting):\n\n    GET /settings/entries/{id}\n\nThis fetch is protected by permissions. If the client does not\nhave permission to read the setting with the scope or if the setting\ndoes not exist, then mod-settings will return a 404 failure. It is a\ndeliberate choice to not distinguish between these two cases.\n\nGet a list of settings [with](https://s3.amazonaws.com/foliodocs/api/mod-settings/settings.html#operation/getSettings):\n\n    GET /settings/entries\n\nThe latter takes optional `query`, `limit` (default 10), `offset` (default 0) parameters.\nQuery is expressed in Contextual Query Language\n([CQL](https://dev.folio.org/reference/glossary/#cql))\nand supports queries on the `id`, `scope`,\n`key` and `userId` fields. Query terms can mostly only be used in\nexact-value matching: the exception is that the key field supports\nright-truncated searches, e.g. `scope=foo and key=bar*` to find all\nentries in the `foo` scope that begin with `bar`.\n\nThe GET operations are \"read\" operations. The entries returned\nare limited by client permissions.\n\nUpdate a setting\n[with](https://s3.amazonaws.com/foliodocs/api/mod-settings/settings.html#operation/putSetting):\n\n    PUT /settings/entries/{id}\n\nThis returns 204 if the setting was updated. This is strictly \"write\", i.e.\ndoes not return the newly modified setting.\n\nDelete a setting\n[with](https://s3.amazonaws.com/foliodocs/api/mod-settings/settings.html#operation/deleteSetting):\n\n    DELETE /settings/entries/{id}\n\nThis is a write operation and returns 204 if the setting was deleted.\n\nIt's also possible to upload (or \"import\") settings\n[with](https://s3.amazonaws.com/foliodocs/api/mod-settings/settings.html#operation/uploadSettings):\n\n    PUT /settings/upload\n\nSettings are created/updated with this service. The provided settings must\nnot include an identifier. An identifier will be assigned by the server when\nnecessary.\n\n## Compilation\n\nRequirements:\n\n* Java 17 or later\n* Maven 3.6.3 or later\n* Docker (unless `-DskipTests` is used)\n\nNote: Debian package maven-3.6.3-1\n[does not work with Java16/Java17](https://bugs.launchpad.net/ubuntu/+source/maven/+bug/1930541)\n\n\nYou need `JAVA_HOME` set, e.g.:\n\n   * Linux: `export JAVA_HOME=$(readlink -f /usr/bin/javac | sed \"s:bin/javac::\")`\n   * macOS: `export JAVA_HOME=$(/usr/libexec/java_home -v 17)`\n\nBuild all components with: `mvn install`\n\n## Server\n\nYou will need Postgres 12 or later.\n\nYou can create an empty database and a user with, e.g:\n\n```\nCREATE DATABASE folio_modules;\nCREATE USER folio WITH CREATEROLE PASSWORD 'folio';\nGRANT ALL PRIVILEGES ON DATABASE folio_modules TO folio;\n```\n\nThe module's database connection is then configured by setting environment\nvariables:\n`DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD`, `DB_DATABASE`,\n`DB_MAXPOOLSIZE`, `DB_SERVER_PEM`.\n\nOnce configured, start the module with:\n\n```\njava -Dport=8081 -jar target/mod-settings-fat.jar\n```\n\n## Running with Docker\n\nIf you feel adventurous and want to run mod-settings in a docker container, build the container first:\n\n```\ndocker build -t mod-settings:latest .\n```\n\nAnd run with the module port exposed (`8081` by default):\n\n```\ndocker run -e DB_HOST=host.docker.internal \\\n  -e DB_USERNAME=folio \\\n  -e DB_PASSWORD=folio \\\n  -e DB_DATABASE=folio_modules \\\n  -p 8081:8081 --name settings mod-settings:latest\n```\n\n**Note**: The magic host `host.docker.internal` is required to access\nthe DB and may be only available in Docker Desktop.\nIf it's not defined you can specify it by passing\n`--add-host=host.docker.internal:\u003cdocker bridge net IP\u003e` to the run command.\n\n**Note**: Those docker build and run commands do work as-is with\n[Colima](https://github.com/abiosoft/colima).\n\n## Additional information\n\n### Issue tracker\n\nSee project [MODSET](https://issues.folio.org/browse/MODSET)\nat the [FOLIO issue tracker](https://dev.folio.org/guidelines/issue-tracker).\n\n### Code of Conduct\n\nRefer to the Wiki\n[FOLIO Code of Conduct](https://wiki.folio.org/display/COMMUNITY/FOLIO+Code+of+Conduct).\n\n### ModuleDescriptor\n\nSee the [ModuleDescriptor](descriptors/ModuleDescriptor-template.json)\nfor the interfaces that this module requires and provides, the permissions,\nand the additional module metadata.\n\n### API documentation\n\nAPI descriptions:\n\n * [OpenAPI](src/main/resources/openapi/settings.yaml)\n * [Schemas](src/main/resources/openapi/schemas/)\n\nGenerated [API documentation](https://dev.folio.org/reference/api/#mod-settings).\n\n### Code analysis\n\n[SonarQube analysis](https://sonarcloud.io/dashboard?id=org.folio%3Amod-settings).\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 images for [released versions](https://hub.docker.com/r/folioorg/mod-settings/)\nand for [snapshot versions](https://hub.docker.com/r/folioci/mod-settings/).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-settings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffolio-org%2Fmod-settings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-settings/lists"}