{"id":29687257,"url":"https://github.com/thepalaceproject/library-registry","last_synced_at":"2026-04-01T22:48:57.997Z","repository":{"id":38204545,"uuid":"364668134","full_name":"ThePalaceProject/library-registry","owner":"ThePalaceProject","description":"Application for tracking the registry of libraries used in the Palace Project web and mobile apps.","archived":false,"fork":false,"pushed_at":"2026-03-26T08:46:33.000Z","size":11750,"stargazers_count":2,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-27T02:58:59.352Z","etag":null,"topics":["backend","library-registry","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThePalaceProject.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-05-05T18:17:11.000Z","updated_at":"2026-03-26T08:46:37.000Z","dependencies_parsed_at":"2022-08-08T23:19:43.019Z","dependency_job_id":"3a78ad6c-93d7-4f62-ab8d-9e1def5214e3","html_url":"https://github.com/ThePalaceProject/library-registry","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/ThePalaceProject/library-registry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Flibrary-registry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Flibrary-registry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Flibrary-registry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Flibrary-registry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThePalaceProject","download_url":"https://codeload.github.com/ThePalaceProject/library-registry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Flibrary-registry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["backend","library-registry","python"],"created_at":"2025-07-23T04:36:28.613Z","updated_at":"2026-04-01T22:48:57.973Z","avatar_url":"https://github.com/ThePalaceProject.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Library Registry\n\nA discovery service for matching people to the libraries that serve them.\n\n[![Test Library Registry \u0026 Build Docker Image](https://github.com/ThePalaceProject/library-registry/actions/workflows/test-build.yml/badge.svg)](https://github.com/ThePalaceProject/library-registry/actions/workflows/test-build.yml)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336)](https://pycqa.github.io/isort/)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://github.com/pre-commit/pre-commit)\n![Python: 3.12,3.13,3.14](https://img.shields.io/badge/Python-3.12%20%7C%203.13%20%7C%203.14-blue)\n\nThis is a [LYRASIS](http://lyrasis.org)-maintained fork of the NYPL\n[Library Simplified](http://www.librarysimplified.org/) Library Registry.\n\nDocker images are available at:\n\n- [library-registry](https://github.com/orgs/ThePalaceProject/packages?repo_name=library-registry)\n\n## Cloning the Library Registry Repositories\n\nYou will need both this repository and the separate front end repo, in order to build the local development images. The\nregistry front end repo should be checked out into a directory named `registry_admin` in the same parent directory as\nthe `library-registry` repo itself. If it is not, you will need to change the host mount instructions in the\n`docker-compose.yml` file to accommodate its location. To get them both in the same directory, execute the following\nfrom that directory:\n\n```shell\ngit clone https://github.com/thepalaceproject/library-registry.git\ngit clone https://github.com/thepalaceproject/library-registry-admin.git\n```\n\n## Key Environment Variables\n\nThese environment variables are generally applicable, regardless of installation method, and are included here because\nthey are not discussed elsewhere in this document.\n\n- EMAILER_RECIPIENT_OVERRIDE: If set, `emailer` will send all non-test email to this email address.\n\n## AWS configuration setup for the storage\n\n- SIMPLIFIED_AWS_S3_BUCKET_NAME (mandatory): The name of the bucket to use on S3\n- SIMPLIFIED_AWS_S3_ENDPOINT_URL: The API endpoint for the S3 bucket\n\nOf the above, only the `SIMPLIFIED_AWS_S3_BUCKET_NAME` is a mandatory configuration.\nThe underlying boto library will manage the credentials and authentication mechanism. [[source](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)]\n\n## Installation (Docker)\n\nIf not using Docker, skip to section entitled [\"Installation (non-Docker)\"](#installation-non-docker)\n\nBecause the Registry runs in a Docker container, the only required software is\n[Docker Desktop](https://www.docker.com/products/docker-desktop). The database and webapp containers expect to be able\nto operate on ports 5432 and 80, respectively--if those ports are in use already you may need to amend the\n`docker-compose.yml` file to add alternate ports.\n\n_Note: If you would like to use the `Makefile` commands you will also need `make` in your `PATH`. They're purely\nconvenience methods, so it isn't strictly required. If you don't want to use them just run the commands from the\ncorresponding task in the `Makefile` manually. You can run `make help` to see the full list of commands._\n\nWhile they won't need to be changed often, there are a couple of environment variables set in the `Dockerfile` that are\nreferenced within the container:\n- `LIBRARY_REGISTRY_DOCKER_HOME` is the app directory.\n\n### Building the Images\n\nLocal development uses two Docker images and one persistent Docker volume (for the PostgreSQL data directory). To create\nthe base images:\n\n```shell\ncd library-registry\nmake build\n```\n\n## Usage\n\n### Running the Containers\n\nYou can start up the local compose cluster in the background with:\n\n```shell\nmake up\n```\n\nAlternatively, if you want to keep a terminal attached to the running containers, so you can see their output, use:\n\n```shell\nmake up-watch\n```\n\n### Controlling the Cluster\n\n- `make stop` to stop (but not remove) the running containers\n- `make start` to restart a stopped cluster\n- `make down` to stop and remove the running containers\n- `make clean` to stop and remove the running containers and delete the database container's data volume\n\n### Accessing the Containers\n\nWhile the cluster is running, you can access the containers with these commands:\n\n- `make db-session` - Starts a `psql` session on the database container as the superuser\n- `make webapp-shell` - Open a shell on the webapp container\n\n### Viewing the Web Interface\n\nThe Library Registry listens (via Nginx) on port 80, so once the cluster is running you should be able to point a\nbrowser at `http://localhost/admin/` and access it with the username/password `admin/admin`.\n\nThe [Library Registry Admin](https://github.com/thepalaceproject/library-registry-admin.git)\nfront end is implemented as a Node package. The name and version of this package are configured in\n`admin/config.py`. In addition, either or both may be overridden via environment variables. For example:\n\n```shell\nTPP_LIBRARY_REGISTRY_ADMIN_PACKAGE_NAME=@thepalaceproject/library-registry-admin\nTPP_LIBRARY_REGISTRY_ADMIN_PACKAGE_VERSION=1.0.0\n```\n\n#### Debugging/Development of the Web Interface\n\nThe default configuration will result in the admin client being served from a content delivery\nnetwork. To enable use of a local copy to support development/debugging, ensure that this\nrepo and that of the admin UI have the same parent directory and then perform the following\nfrom the base of this repo:\n- `(cd admin \u0026\u0026 npm link ../../library-registry-admin)`\n\nThis will link the admin UI project into the admin directory in a manner that is compatible with\nboth docker and non-containerized development. If the package is properly linked, admin UI assets\nwill be served from the linked package, rather than the CDN.\n\n## Installation (non-Docker)\n\nTo install the registry locally, you'll need the following:\n\n- PostgreSQL 16+\n- PostGIS 3\n- Python 3.12+\n- Appropriate system dependencies to build the Python dependencies, which may include:\n    - `make` / `gcc` / `build-essential` (debian) / `build-base` (alpine) / XCode CLI Tools (mac)\n    - Compression libs like `bzip2-dev`, `zlib-dev`, etc.\n    - PostgreSQL development libs: `libpq`, `postgresql-dev`, etc., for [`psycopg2`](https://www.psycopg.org)\n    - Image processing libs for [`Pillow`](https://pillow.readthedocs.io/en/stable/) such as `libjpeg-dev`\n\n### Creating the Databases\n\nWith a running PostgreSQL/PostGIS installation, you can create the required test and dev databases by executing:\n\n```SQL\nCREATE DATABASE simplified_registry_dev;\nCREATE USER simplified WITH PASSWORD 'simplified';\nGRANT ALL PRIVILEGES ON DATABASE simplified_registry_dev TO simplified;\n\nCREATE DATABASE simplified_registry_test;\nCREATE USER simplified_test WITH PASSWORD 'simplified_test';\nGRANT ALL PRIVILEGES ON DATABASE simplified_registry_test TO simplified_test;\n\n\\c simplified_registry_dev\nCREATE EXTENSION fuzzystrmatch;\nCREATE EXTENSION postgis;\n\n\\c simplified_registry_test\nCREATE EXTENSION fuzzystrmatch;\nCREATE EXTENSION postgis;\n\n\\c simplified_registry_dev postgres\nGRANT ALL ON SCHEMA public TO simplified;\n\n\\c simplified_registry_test postgres\nGRANT ALL ON SCHEMA public TO simplified;\n```\n\nThe database configuration is exposed to the application via environment variables.\n\n```SHELL\nSIMPLIFIED_TEST_DATABASE=postgresql://simplified_test:simplified_test@localhost:5432/simplified_registry_test\nSIMPLIFIED_PRODUCTION_DATABASE=postgresql://simplified:simplified@localhost:5432/simplified_registry_dev\n```\n\nFor development work, you should create a `.env` file in the project directory that includes these variables\nset to the appropriate values for your environment.\n\n### Installing Python Dependencies\n\nThe project expects to use [`poetry`](https://python-poetry.org) for dependency and virtualenv management, so first\n[install that](https://python-poetry.org/docs/#installation).\n\nHaving done so, you should be able to run the following in the project directory to install all dependencies.\n\nFor a development environment:\n\n```shell\npoetry install\n```\n\nFor a production environment:\n\n```shell\npoetry install --only main,pg\n```\n\n_Important note_: The `uszipcodes` dependency is pinned because we also rely on a [repo-local](./data/simple_db.sqlite)\ncopy of the [release-specific version](https://github.com/MacHu-GWU/uszipcode-project/releases) of the\nassociated \"simple\" (versus \"comprehensive\") database (e.g.,\n[this file](https://github.com/MacHu-GWU/uszipcode-project/releases/download/1.0.1.db/simple_db.sqlite)\nfor release 1.0.1). When updating this dependency, it is important to obtain the corresponding database and store it as\n`./data/simple_db.sqlite`, since that is where the code expects to find it.\n\n### Initialize the database\n\nTo initialize a fresh database (ie no tables yet created) use the following script:\n\n```shell\npoetry run ./bin/migrate_database\n```\n\n### Upgrade/Downgrade an existing database\n\nDuring development you may wish to use Alembic to upgrade or downgrade to a particular database version.\nYou can fulfill this desire using the `-u/--upgrade \u003cversion\u003e` or `-d/--downgrade \u003cversion\u003e` parameters, respectively.\nFor example to upgrade to version \"ee43af3\" you would execute the following command:\n\n```shell\npoetry run ./bin/migrate_database -u ee43af3\n```\n\nDatabase versions can be found in the alembic/versions directory.\n\n### Running the Registry\n\nTo start the registry inside the virtualenv that `poetry` creates:\n\n```shell\nFLASK_APP=app.py poetry run flask run\n```\n\n## Continuous Integration\n\nThis project runs all the unit tests through Github Actions for new pull requests and when merging into the default\n`main` branch. The relevant file can be found in `.github/workflows/test-build.yml`. When contributing updates or fixes,\nit's required for the test Github Action to pass for all python environments. Run the `tox` command locally before\npushing changes to make sure you find any failing tests before committing them.\n\n### Code Style\n\nCode style on this project is linted using [pre-commit](https://pre-commit.com/). This python application is included\nin our `pyproject.toml` file, so if you have the applications requirements installed it should be available. pre-commit\nis run automatically on each push and PR by our [CI System](#continuous-integration).\n\nYou can run it manually on all files with the command: `pre-commit run --all-files`.\n\nFor more details about our code style, see the\n[code style section of the circulation README](https://github.com/ThePalaceProject/circulation#code-style).\n\n### Testing\n\nGithub Actions runs our unit tests against different Python versions automatically using\n[tox](https://tox.readthedocs.io/en/latest/).\n\nTo run `pytest` unit tests locally, install `tox`.\n\n```shell\npoetry install --only ci\n```\n\nTox has an environment for each python version and an optional `-docker` factor that will automatically use docker to\ndeploy service container used for the tests. You can select the environment you would like to test with the tox `-e`\nflag.\n\n#### Environments\n\n| Environment | Python Version |\n|-------------|----------------|\n| py312       | Python 3.12    |\n| py313       | Python 3.13    |\n| py314       | Python 3.14    |\n\nAll of these environments are tested by default when running tox. To test one specific environment you can use the `-e`\nflag.\n\nTest Python 3.12\n\n```shell\ntox -e py312\n```\n\nYou need to have the Python versions you are testing against installed on your local system. `tox` searches the system\nfor installed Python versions, but does not install new Python versions. If `tox` doesn't find the Python version its\nlooking for it will give an `InterpreterNotFound` errror.\n\n[Pyenv](https://github.com/pyenv/pyenv) is a useful tool to install multiple Python versions, if you need to install\nmissing Python versions in your system for local testing.\n\n#### Docker\n\nIf you install `tox-docker` tox will take care of setting up all the service containers necessary to run the unit tests\nand pass the correct environment variables to configure the tests to use these services. Using `tox-docker` is not\nrequired, but it is the recommended way to run the tests locally, since it runs the tests in the same way they are run\non Github Actions. `tox-docker` is installed automatically as part of the `ci` poetry group.\n\nThe docker functionality is included in a `docker` factor that can be added to the environment. To run an environment\nwith a particular factor you add it to the end of the environment.\n\nTest with Python 3.12 using docker containers for the services.\n\n```shell\ntox -e py312-docker\n```\n\n#### Override `pytest` arguments\n\nIf you wish to pass additional arguments to `pytest` you can do so through `tox`. The default argument passed to `pytest`\nis `tests`, however you can override this. Every argument passed after a `--` to the `tox` command line will the passed\nto `pytest`, overriding the default.\n\nOnly run the `test_app.py` tests with Python 3.12 using docker.\n\n```shell\ntox -e py312-docker -- tests/test_app.py\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepalaceproject%2Flibrary-registry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthepalaceproject%2Flibrary-registry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepalaceproject%2Flibrary-registry/lists"}