OpenLibrarian

Open Librarian is a website for tracking and sharing a love of books. It utilizes the Nostr protocol so that users can bring their friends and social connections with them, and take them elsewhere if they'd like to.

Goals

• To broaden the specific application base of the Nostr network and allow/encourage specialisation to take place
• Make a fun, easy to use book tracking app which includes (or will):
  • Library shelves
  • Personal reading challenges
  • Book reviews
  • Reading progress
  • Book-related social groups

If you'd like to take a look at my backlog you can find it on Craft.

Open Source Stack

Open Librarian is built on a range of Free and Open Source Software (FOSS) projects, the most prominent of which are:

• Open Library - A project working on making all the published works of humankind available to everyone
• rust-nostr - A Nostr development kit built in rust with a range of language bindings
• Django - A web-application framework written in python
• Bootstrap - A front-end toolkit

Nostr Objects

There are a range of Nostr objects underpinning this application which manage the data structures.

Note that any objects still to be implemented are to be considered a WIP and may be subject to substantial change prior to implementation.

User’s Shelves (Implemented)

{
  ‘kind’ : 30003,
  ‘tags’ : [
    ‘d’           : <SHA-1 of (pubkey + list ID)>,
    ‘title’       : <list Title>,
    ‘description’ : <list description>,
    ‘i’           : <‘isbn:’ + isbn of book>,
    …
  ],
  ‘content’ : <‘Books & Literature (OpenLibrarian)’ + ‘:’ + # of hidden books + ‘:’ + NIP04 encrypted ‘i’ tags for isbns of hidden books>   
}

List IDs include: CR, HR, TRW, TRS

Book Review - Individual Books (Implemented)

{
  ‘kind’ : 31025,
  ‘tags’ : [
    ‘d’      : <SHA-256 of ISBN value>
    ‘k’      : <NIP 73 external content k tag for books i.e., ‘isbn’>
    ‘rating’ : <normalised value between 0 and 1, optional mark>
    ‘raw’    : <optional raw rating value X/Y (e.g 5/10)>
    ...
    't'      : <optional hashtags for more additional categorization>
  ],
  ‘content’ : <optional additonal text for personal notes or more details>
}

Book Progress - Individual Books (Implemented)

{
  ‘kind’ : 30250,
  ‘tags’ : [
    ‘d’       : <SHA-256 of ISBN value>
    ‘k’       : <NIP 73 external content k tag for books i.e., ‘isbn’>
    ‘current’ : <numerator>
    ‘max’     : <denominator>
    ’unit’    : <units; “%” or “pages”>
    ‘started’ : <unix timestamp of start date OR ‘NA’>,
    ‘ended’   : <unix timestamp of end date OR ‘NA’>
  ],
  ‘content’ : ‘’
}

Notes:

• Reviews only available for completed books
• Progress only available for ‘Currently Reading’, if book is moved to ‘Have Read’ then progress automatically set to 100% (or equivalent)
• If book is moved onto ‘Currently Reading’ or ‘Want to Read’ shelves then progress is reset at 0% (or equivalent) along with start and end dates if already available

Installation and Development

Clone the repository into a suitable local location. Note that these instructions assume you're using UV for the package management, for more information see the UV Docs.

git clone ‘https://github.com/RydalWater/OpenLibrarian.git’

Create the virtual evn and install packages.

cd OpenLibrarian

uv sync

Rename/modify the .example_env file as follows:

• Remove ‘example_’ from the name
• Generate a new npub/nsec key pair for Nostr testing purposes
• Default relays list (if you want to change this)

Modify settings.py (in ‘openlibrarian_root/openlibrarian/‘)

• Comment out:
  • ALLOWED_HOSTS = os.getenv(…)
  • DEBUG = os.getenv(…)
  • SECRET_KEY = os.getenv(…)
• Uncomment the following:
  • ALLOWED_HOSTS = […]
  • DEBUG = True
  • SECRET_KEY = ‘SUPERsecretKEY123abc’

Note that these parameters are simply for testing/development purposes. Further updates will be required if you plan on deploying to a production environment.

Start the local server (from the openlibrarian_root folder)

uv run openlibarian_root/manage.py runserver

That is it, you should now see a message similar to the one below in the console. You may get a warning about migrations. Normally for a django project you would rerun the python manage.py makemigrations && python manage.py migrate commands, however this project does not use any backend database so this shouldn’t be necessary.

Django version 5.0.8, using settings ‘openlibrarian.settings’
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Running the Tests

If you would like to run the tests make sure you have first set up the relevant browser webdrivers Selenium.

Assuming you don't have a server running step into the root folder and run the server.

cd openlibrarian_root

uv run manage.py runserver

Then open a new terminal (leaving the other running) and run the tests using coverage.

cd openlibrarian_root

Run all tests

uv run coverage run manage.py test --verbosity=3

Run specific tests

uv run coverage run manage.py test almanac.tests.test_settings --verbosity=3

Review the report.

uv run coverage report