A publication catalog server compatible with OPDS 1.2, written in Python with a straightforward management REST API for CRUD operations.
Although this project is already in use in a production environment, work is still in progress, and the API remains unstable. If you wish to deploy the project, please feel free to open a discussion or send us an email. We are actively working on new features and documenting existing ones, but it takes time.
The main goal is to implement the complete OPDS 1.2 and later OPDS 2.0 specifications. The ordered list below represents the current progress:
- Previously Acquired Content
- Subscriptions (
/opds/subscriptions
)
- Subscriptions (
- Facets
- Search
- Pagination
- Complete acquisition feeds
The implementation is based on these RFCs:
- RFC7807: Problem Details for HTTP APIs
- RFC7617: The 'Basic' HTTP Authentication Scheme
- RFC6705: The OAuth 2.0 Authorization Framework: Bearer Token Usage
- RFC5005: Feed Paging and Archiving (not implemented yet)
A pre-built Docker image is available on the GitHub Container registry as evilflowerscatalog.
The repository contains a working example of a docker-compose.yml
file configured for a development environment.
You can use a similar configuration for production usage. The application image will be built from the source.
Setup steps (container name may differ):
- Initialize containers
docker-compose up
- Import languages, currencies, and set up CRON jobs
docker exec -it evilflowerscatalog-django-1 python3 manage.py setup
- Create a superuser
docker exec -it evilflowerscatalog-django-1 python3 manage.py createsuperuser
The server will start on port 8000.
We use poetry for dependency management and PostgreSQL 15 (12+ should be compatible) as a data storage (acquisition files are stored on the filesystem, not in the database). To set up an instance with a demo database, follow these simple steps:
- Create a Python virtual environment (
python -m venv venv
) - Enter the environment (
source venv/bin/activate
) - Install dependencies
poetry install
- Create a JWK (if you are unsure how, check this mkjwk generator) and keep it private
- Create an
.env
file according to.env.example
- Execute migrations
python manage.py migrate
- Import currencies, languages, and set up CRON jobs using
python manage.py setup
- Create a superuser using
python manage.py createsuperuser
A portion of the API is described using OpenAPI, with the documentation available here: REST API. The complete REST API description is included in the Insomnia collection, accessible here. Additional features are detailed on the GitHub Wiki.
This open-source project is maintained by students and PhD candidates of the Faculty of Informatics and Information Technologies at the Slovak University of Technology. The software is utilized by the university, aligning with its educational and research activities. We appreciate the faculty's support of our work and their contribution to the open-source community.