Skip to content

ThePalaceProject/circulation-lcp-test

Repository files navigation

circulation-lcp-test

Testbed for testing Readium LCP integration in Circulation Manager.

Architecture

Project consists of the following modules:

Usage

Preparing the local environment

  1. Update all the submodules:
git submodule init
git submodule update --remote --recursive
  1. Update the following host names in .env file:
  • READIUM_LSDSERVER_HOSTNAME
  • READIUM_FRONTEND_HOSTNAME
  • MINIO_HOSTNAME
  • CM_HOSTNAME
  1. Replace all the host names with 127.0.0.1 in etc/hosts file:
127.0.0.1     lsdserver.lcp.hilbertteam.net
127.0.0.1     testfrontend.lcp.hilbertteam.net
127.0.0.1     minio.lcp.hilbertteam.net
127.0.0.1     cm.lcp.hilbertteam.net
  1. Run lcp-conf first to generate configuration required by lcpserver, lsdserver, and testfrontend:
docker-compose run lcp-conf
  1. Build the images:
docker-compose build

⚠️ Please note that this testbed uses development version of nypl/circ-webapp and custom version of circ-exec Docker images.

  1. Run all the containers:
docker-compose up -d
  1. Use docker-compose ps to confirm that all the containers started successfully. It may take some time for mariadb to start which can negatively affect lcpserver, lsdserver, and testfrontend. In this case wait until mariadb finishes the initialization process (you can check the logs using docker-compose logs mariadb) and then start all the remaining containers:
docker-compose up -d
  1. Make sure that Elasticsearch started correctly. Sometimes when the disk capacity is low, Elasticsearch marks shards as read-only which doesn't allow to use it properly. Check the logs using docker-compose logs es and if you see something suspicious execute the following requests to fix it:
docker-compose exec es bash
curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_cluster/settings -d '{ "transient": { "cluster.routing.allocation.disk.threshold_enabled": false } }'
curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_all/_settings -d '{"index.blocks.read_only_allow_delete": null}'

Also, sometimes Elasticsearch keeps failing because of OOM even though there is enough RAM. In this case please try to increase vm.max_map_count:

sysctl -w vm.max_map_count=262144

Setting up a MinIO instance

  1. Log into MinIO's administrative interface located at MINIO_HOSTNAME using AWS_S3_KEY and AWS_S3_SECRET defined in .env file as credentials:

  2. Create the following buckets as it's shown on the picture below:

  • covers - public access bucket containig book covers
  • encrypted-books (READIUM_S3_BUCKET) - public access bucket containing encrypted books Creating buckets in MinIO
  1. Grant public access to the buckets created before:
# Start the MinIO's command line client
docker run -it --entrypoint=/bin/sh --network container:circulation-lcp-test_minio_1 minio/mc

# Authenticate against the running MinIO instance
mc alias set local http://minio:9000 minioadmin minioadmin # Please use the credentials set in .env file

# Grant public access to covers bucket
mc policy set public local/covers

# Grant public access to covers encrypted-books
mc policy set public local/encrypted-books

Setting up Circulation Manager

  1. Open Circulation Manager's administrative interface located at CM_HOSTNAME

  2. Set up a new administrative account

  3. Create a new library using LCP as its short name as it's shown on the picture below:

LCP is used in LCP configuration and shouldn't be changed

Creating a new library

  1. Set up a search service using http://es:9200 as Elasticsearch's URL: Creating a search service

  2. Set up a new MinIO storage as it's shown on the pictures below and using AWS_S3_KEY and AWS_S3_SECRET as credentials: Creating a MinIO storage service

Creating a MinIO storage service

  1. Set up a new LCP storage service: Creating an LCP storage service

Creating an LCP storage service

  1. Set up a new LCP collection:
  • LCP License Server's input directory has to be /opt/readium/files because it's defined in Dockerfile
  • lcpencrypt's output directory has to be a value of CM_REPOSITORY, it points to the intermediate_repository

Creating an LCP collection

Creating an LCP collection

  1. Set up a patron authentication provider (for example, a basic authentication): Creating a basic authentication provider

Import the LCP collection

  1. Run the import script via in nypl/circ-exec Docker image:
docker-compose -f docker-compose.yml -f docker-compose.import.yml run import

Test

  1. Go to the Circulation Manager dashboard, select A Dictionary in Hindi and English and borrow it: Borrowing an LCP book

  2. Authenticate using the test patron credentials: Authenticating

  3. Download the book: Downloading an LCP book

  4. Find the downloaded file.

Please note that this file must have .lcpl extension (this should be fixed in this PR). Until it's fixed please change its extension manually Accessing the downloaded LCP book

  1. Open the .lcpl file in Thorium Reader: Opening the LCP book in Thorium Reader

  2. Get generated passphrase from Circulation Manager: Getting a passphrase from Circulation Manager

  3. Enjoy the book in Thorium Reader: LCP book opened in Thorium Reader

Troubleshooting

If a list of the books you see in Circulation Manager is outdated or simply wrong you may have to truncate cached feeds in CM's database. To do that please execute the following steps:

docker exec -it circulation-lcp-test_postgres_1 bash
psql -U simplified simplified_circulation_dev  # Please use the credentials from .env file
truncate cachedfeeds;