{"id":50533067,"url":"https://github.com/umd-lib/papaya","last_synced_at":"2026-06-03T15:02:02.368Z","repository":{"id":325334343,"uuid":"1099914160","full_name":"umd-lib/papaya","owner":"umd-lib","description":"IIIF Presentation API Application","archived":false,"fork":false,"pushed_at":"2026-05-27T15:44:31.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T17:12:54.268Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"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/umd-lib.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2025-11-19T15:49:16.000Z","updated_at":"2026-04-21T17:42:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/umd-lib/papaya","commit_stats":null,"previous_names":["umd-lib/papaya"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/umd-lib/papaya","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fpapaya","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fpapaya/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fpapaya/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fpapaya/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umd-lib","download_url":"https://codeload.github.com/umd-lib/papaya/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fpapaya/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33870026,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"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":"2026-06-03T15:02:01.547Z","updated_at":"2026-06-03T15:02:02.363Z","avatar_url":"https://github.com/umd-lib.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# papaya\n\nIIIF Presentation API Application\n\n## Configuration\n\n### Environment Variables\n\n* **`PAPAYA_URL`** Public facing base URL of this application.\n* **`PAPAYA_FCREPO_ENDPOINT`** URL of the Fedora repository. This is not \n  directly accessed, but is used when translating between URIs and IIIF \n  identifiers.\n* **`PAPAYA_FCREPO_PREFIX`** Prefix string to use in IIIF identifiers for \n  resources in the Fedora repository.\n* **`PAPAYA_SOLR_ENDPOINT`** URL of the Solr server that will provide the \n  metadata about the resources.\n* **`PAPAYA_SOLR_TEXT_MATCH_FIELD`** Field name in Solr to use for text \n  queries that will return hit highlight annotation lists\n* **`PAPAYA_IIIF_IMAGE_ENDPOINT`** URL of the IIIF Image API server that \n  provides additional metadata about the images.\n* **`PAPAYA_IIIF_IMAGE_ORIGIN`** Actual request URL to use for the IIIF \n  Image API server, if it differs from `PAPAYA_IIIF_IMAGE_ENDPOINT`\n* **`PAPAYA_THUMBNAIL_WIDTH`** Maximum width of thumbnail images included \n  in the manifest.\n* **`PAPAYA_LOGO_URL`** URL of an image file to be used as the logo in the \n  manifest.\n* **`PAPAYA_METADATA_QUERIES_FILE`** YAML or JSON formatted file that \n  contains a mapping from metadata field label to a\n  [jq query](https://jqlang.org/manual/) to retrieve the value or values \n  for that field from the Solr document for a resource.\n\n### Files\n\n* **`METADATA_QUERIES_FILE`** YAML or JSON file that maps metadata field \n  labels to `jq` queries. It also includes the queries necessary to build \n  the IIIF Manifest structure (see `papaya.source.Resource` for more info). \n  For example:\n\n    ```yaml\n    Title: .object__title__display[]?\n    Date: .object__date__edtf\n    Bibliographic Citation: .object__bibliographic_citation__display[]?\n    Creator: .object__creator[]?.agent__label__display[]\n    Contributor: .object__contributor[]?.agent__label__display[]?\n    Subject: .object__subject[]?.subject__label__display[]\n    # structural metadata fields\n    # used by Papaya to generate canvases, sequences, etc.\n    $uri: .id\n    $label: .object__title__display[]?\n    $date: .object__date__dt?\n    $license_uri: .object__rights__same_as__uris[0]\n    $page_uris: .page_uri_sequence__uris[]?\n    $page_image_ids: .iiif_thumbnail_sequence__ids[]?\n    $*page_doc: .object__has_member[]|select(.id == $uri)\n    $*page_label: .object__has_member[]|select(.id == $uri).page__title__txt\n    $*file_page_uri: .object__has_member[]|select(.page__has_file[].id == $uri).id\n    ```\n\n### IIIF Image Service Endpoint vs. Origin\n\nThe `PAPAYA_IIIF_IMAGE_ENDPOINT` is the canonical base URI for the\nIIIF Image server associated with this instance of Papaya. For many cases,\nit will also be the base URL that is used to make requests to that service.\n\nHowever, there are cases where it makes more sense to be able to separate \nthe canonical base URI from the request base URL. For instance, consider \nthe case where both Papaya and the IIIF Image server are running inside a \nKubernetes cluster and can be connected directly without leaving the \ninternal Kubernetes network. In this case, it would be beneficial to be \nable to use the cluster-internal base URL to make the HTTP connections, \nwhile retaining the canonical URI any links in the generated manifest.\n\nIn this case, use `PAPAYA_IIIF_IMAGE_ORIGIN` to set the request base URL \nfor the IIIF Image service. When this value is set, Papaya will use it \ninstead of `PAPAYA_IIIF_IMAGE_ENDPOINT` to generate request URLs. In \naddition, Papaya will create a set of `X-Forwarded-*` headers to add to \nrequests that reflect the canonical URI.\n\nFor example, given:\n\n* `PAPAYA_IIIF_IMAGE_ENDPOINT` is `https://iiif.example.com/images/iiif/2`\n* `PAPAYA_IIIF_IMAGE_ORIGIN` is `http://papaya:3001/iiif/2`\n\nThe headers would be:\n\n* `X-Forwarded-Proto: https`\n* `X-Forwarded-Host: iiif.example.com`\n* `X-Forwarded-Path: /images`\n\nThe `X-Forwarded-Path` is calculated by removing the path of the origin \nURL (e.g., `/iiif/2`) from the end of the path of the endpoint URI (e.g., \n`/images/iiif/2`).\n\n## Development Setup\n\nRequires Python 3.14\n\nThese setup instructions also assume that you are running the development \nstacks for both [umd-fcrepo](https://github.com/umd-lib/umd-fcrepo) and\n[umd-iiif](https://github.com/umd-lib/umd-iiif).\n\n```zsh\ngit clone git@github.com:umd-lib/papaya.git\ncd papaya\npython -m venv --prompt \"papaya-py$(cat .python-version)\" .venv\nsource .venv/bin/activate\n```\n\n```zsh\npip install -e . --group test\n```\n\nCreate a `.env` file with the following contents:\n\n```dotenv\nFLASK_DEBUG=1\nPAPAYA_URL=http://localhost:3001/manifests\nPAPAYA_FCREPO_ENDPOINT=http://fcrepo-local:8080/fcrepo/rest\nPAPAYA_FCREPO_PREFIX=fcrepo:\nPAPAYA_SOLR_ENDPOINT=http://localhost:8985/solr/fcrepo\nPAPAYA_SOLR_TEXT_MATCH_FIELD=extracted_text__dps_txt\nPAPAYA_IIIF_IMAGE_ENDPOINT=http://localhost:8182/iiif/2\nPAPAYA_THUMBNAIL_WIDTH=250\nPAPAYA_LOGO_URL=https://www.lib.umd.edu/images/wrapper/liblogo.png\nPAPAYA_METADATA_QUERIES_FILE=metadata-queries.yml\n```\n\n### Running\n\n```zsh\nflask --app papaya.web run\n```\n\nThe application will be available at \u003chttp://localhost:5000\u003e\n\nTo listen on a different port, supply the `--port` option:\n\n```zsh\nflask --app papaya.web run --port 3001\n```\n\n### Tests\n\n```zsh\npytest\n```\n\nWith coverage information:\n\n```zsh\npytest --cov src --cov-report term-missing tests\n```\n\n### API Documentation\n\n```zsh\npip install -e . --group docs\npdoc papaya\n```\n\nAPI documentation generated by [pdoc](https://pdoc.dev/)\nwill be available at \u003chttp://localhost:8080/\u003e.\n\nTo serve the documentation on an alternate port:\n\n```zsh\npdoc -p 8888 papaya\n```\n\nNow the documentation will be at \u003chttp://localhost:8888/\u003e.\n\n### Docker Image\n\nBuild the image:\n\n```zsh\ndocker build -t docker.lib.umd.edu/papaya .\n```\n\nWhen running in a Docker container, the `PAPAYA_SOLR_ENDPOINT` and\n`PAPAYA_IIIF_IMAGE_ENDPOINT` environment variables will need to be\nadjusted to refer to the correct hostname.\n\nCopy the `.env` file set up earlier to `docker.env`, and make these\nchanges:\n\n```dotenv\nPAPAYA_SOLR_ENDPOINT=http://host.docker.internal:8985/solr/fcrepo\nPAPAYA_IIIF_IMAGE_ENDPOINT=http://host.docker.internal:8182/iiif/2\n```\n\nRun, using this new `docker.env` file:\n\n```zsh\ndocker run --rm -it -p 3001:5000 --env-file docker.env docker.lib.umd.edu/papaya\n```\n\n## Name\n\nThis application is so-named because the phrase \"Presentation API \nApplication\" could be abbreviated \"PAPIA\", which could be pronounced the \nsame as \"papaya\", and because it is paired with the\n[Cantaloupe](https://cantaloupe-project.github.io/) IIIF image server in \nthe UMD Libraries' IIIF services stack.\n\n## License\n\nApache-2.0\n\nSee the [LICENSE](LICENSE) file for license rights and limitations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumd-lib%2Fpapaya","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumd-lib%2Fpapaya","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumd-lib%2Fpapaya/lists"}