umd-oaipmh-server

OAI-PMH Server for Fedora

Purpose

This is an OAI-PMH server for publishing metadata records from a Fedora repository. It uses a Solr index for general queries, and connects directly to Fedora to retrieve the full metadata record for an item.

add-handles

In addition to OAI-PMH functionality, this repository provides an "add-handles" script that takes a CSV file generated by the Plastron "export" command and creates a handle for each item using the configured "umd-handle" server, returning a CSV file with the created handles suitable for import into Fedora. See docs/add_handles.md for more information.

Development Environment

Python version: 3.11

Installation

git clone [email protected]:umd-lib/umd-oaipmh-server.git
cd umd-oaipmh-server
pyenv install --skip-existing $(cat .python-version)
python -m venv .venv --prompt umd-oaipmh-server-py$(cat .python-version)
pip install -r requirements.test.txt -e .

Configuration

Create a .env file with the following contents:

# OAI-PMH repository administrator email address
ADMIN_EMAIL=...
# domain name for the target Fedora repo
OAI_NAMESPACE_IDENTIFIER=...
# OAI-PMH repository name
OAI_REPOSITORY_NAME=...
# earliest datestamp of items in this repository
EARLIEST_DATESTAMP=2014-01-01T00:00:00Z
# JWT SECRET for the server to generate its own token to access the Fedora repository
JWT_SECRET=...
# URL to the Solr core to search
SOLR_URL=...
# enable debugging and hot reloading when run via "flask run"
FLASK_DEBUG=1
# HTTP Proxy for the minted handles
# e.g (https://hdl.handle.net/)
# Don't forget to include the / at the end
HANDLE_PROXY_PREFIX=...
# Type of Dataprovider (Fedora, Avalon)
DATA_PROVIDER_TYPE=...

And, depending on whether you want to start an avalon or fedora server, rename the relevant solr_conf (solr_conf.yml.fedora or solr_conf.yml.avalon) file for whichever server you want to start.

For full configuration information, see Configuration.

Running

To run the application in debug mode, with hot code reloading:

flask --app "oaipmh.web:app(solr_config_file='solr_conf.yml', data_provider_type='Fedora')" run

The OAI-PMH service will be available at http://localhost:5000/oai/api, with a simple HTML landing page at http://localhost:5000/oai.

To change the port, add a BASE_URL environment variable to the .env file:

# set when using a URL and/or port other than
# the defaults ("localhost" and "5000")
BASE_URL=http://localhost:8000/oai/api

And add -p {port number} to the flask command:

# for example, to run on port 8000
flask --app "oaipmh.web:create_app(solr_config_file='solr_conf.yml', data_provider_type='Fedora')" run -p 8000

Testing

This project uses the pytest testing framework. To run the full test suite:

pytest

To run the test suite with coverage information from pytest-cov:

pytest --cov src --cov-report term-missing

This project also uses pycodestyle as a style checker and linter:

pycodestyle src

Configuration of pycodestyle is found in the tox.ini file.

Deploying using Docker

Build the image:

docker build -t docker.lib.umd.edu/oaipmh-server:latest .

If you need to build for multiple architectures (e.g., AMD and ARM), you can use docker buildx. This assumes you have a builder named "local" configured for use with your docker buildx system, and you are logged in to a Docker repository that you can push images to:

docker buildx build --builder local --platform linux/amd64,linux/arm64 \
    -t docker.lib.umd.edu/oaipmh-server:latest --push .

# then pull the image so it is available locally
docker pull docker.lib.umd.edu/oaipmh-server:latest

Run the container:

docker run -d -p 5000:5000 \
    -e ADMIN_EMAIL=... \
    -e OAI_NAMESPACE_IDENTIFIER=... \
    -e OAI_REPOSITORY_NAME=... \
    -e EARLIEST_DATESTAMP=2014-01-01T00:00:00Z \
    -e JWT_SECRET=... \
    -e SOLR_URL=... \
    docker.lib.umd.edu/oaipmh-server:latest

If you created a .env file (see Configuration), you can run the Docker image using that file.

docker run -d -p 5000:5000 \
    --env-file .env \
    docker.lib.umd.edu/oaipmh-server:latest

Note: To refer to services running on the host machine (e.g., Solr) in the configuration, you will need to use the hostname host.docker.internal instead of localhost.