Skip to content

Latest commit

 

History

History
206 lines (143 loc) · 10.9 KB

README.md

File metadata and controls

206 lines (143 loc) · 10.9 KB
Raw

CircleCI BrowserStack Status Scrutinizer Code Quality

BIBREX

Bibrex is a simple system to manage and circulate things that are not well fit for bibliographic description and inclusion in the library catalogue, such as extension coords and other cables, computers, cameras, calculators and so on. Users can be created locally, but also imported from Alma. The system is created for use by librarians, not end users.

Functionality:

  • Two-level data model based on Things and Items, where the Thing is the generalization and the Item is a concrete physical item with a barcode/RFID tag.
  • Alma user integration
  • Loan time can be customized per thing and per loan.
  • Reminders sent in the user's preferred language (currently support for Bokmål, Nynorsk or English)
  • GDPR friendly. See section on privacy below.

Missing functionality:

  • Reservations
  • Discovery/search for end users. We have a very simple public status display.
  • No support for kits with multiple parts with their own barcode/RFID tag.

Setup for development

Requirements: Quite recent versions of PHP (see composer.json for required version), NodeJS and PostgresSQL.

The .env file

Settings are generally stored in an .env file. The repo comes with an example file that you can copy and modify to your setup.

Database setup

Bibrex mostly make use of the database-agnostic layer provided by Laravel, but has a few couplings to PostgresSQL through the use of Postgres-specific functionality like the CITEXT and JSONB data types, and the ILIKE operator. It shouldn't be too much effort to make it work with another databse if needed, but it's definitely easier to get started with Postgres.

For a local setup, start by creating a Postgres user, and a database:

$ createuser --pwprompt bibrex_dev
$ createdb --owner=bibrex_dev --encoding=utf8 bibrex_dev
$ psql -d bibrex_dev -c 'CREATE EXTENSION citext;'

Add the credentials to the .env file.

Alma integration

To setup Alma integration, you need to create (1) an API key in Alma Developers Network and (2) a webhook integration in Alma. Both are stored in the .env file.

The API key is used to search for users and optionally to check out items in Alma (while Bibrex is mostly used to check out items from its own database of things, it can also be used to check out items from Alma if so desired). The webhook integration is used to receive updates about users from Alma, so data in Bibrex always reflect the latest changes in Alma.

API key

  • Login to Ex Libris Developer Network using your institutional account.
  • Go to "Manage API Keys" under "Build / My APIs".
  • Add a new API key, give it a descriptive name and add the following permissions:
    • Bibs - Production - Read/write (necessary to administrate loans in Alma, optional)
    • Users - Production - Read-only
    • Configuration - Production - Read-only

Store the generated API key as ALMA_KEY in the .env file.

Webhook integration

  • In Alma, go to Configuration Menu > General > External Systems > Integration Profiles and select "Add Integration Profile".
  • Enter a Code and Name (both fields are purely descriptive), select "Webhooks" as Integration Type and press "Next"
  • Set "Webhook listener url" to https://your-domain.com/webhooks/alma where your-domain.com is the domain Bibrex is hosted at.
  • "Secret" should be a long, random string (preferably > 30 characters, something like a "fort knox password" from https://randomkeygen.com/)
  • Check the "Users" checkbox.
  • Click Activate to activate the profile and then Save to save it.

Store the secret you created as ALMA_WEBHOOK_SECRET in the .env file. This is used to verify that messages from Alma are indeed coming from Alma.

Pusher integration (optional, for live updates)

If you use Bibrex on more than one computer in the same library desk, Bibrex can use Pusher to communicate updates about loans between them, to avoid the situation where an item is checked in on computer A, but the change is not reflected on computer B before Bibrex is reloaded. No personal information is sent over Pusher, it's only used to communicate to other clients that they should update their state.

The free sandbox plan includes 100 clients and 200,000 messages per day, which should be more than enough for most Bibrex users. At the University of Oslo, we use < 10 clients and ~100 messages per day.

  • To activate the integration, sign up for Pusher, go to Channels and "Create app".
  • Give it a name and select the "eu" cluster. The other options are optional, but multiple environments can be handy if you wan to test Pusher on a test server separate from the production server.
  • Go to "App Keys"
  • Copy the app id, key, secret and cluster and paste the values into the .env file as PUSHER_APP_ID, MIX_PUSHER_APP_KEY, PUSHER_APP_SECRET and MIX_PUSHER_APP_CLUSTER, respectively.

Building the app

  1. composer install to fetch PHP dependencies.
  2. Add database setup etc. to the .env file.
  3. php artisan migrate to create the database tables
  4. Optional: php artisan db:seed to seed the database with an admin user ("[email protected]", password "admin") and a few demo things.
  5. Make sure app/storage is writable by the www user.
  6. npm install to fetch NodeJS dependencies.

PHP settings: You might want to increase upload_max_filesize to 10M or to taste to allow users to upload larger images. Bibrex will make thumbnails for you, so larger files pose no problem really.

Running a development server

  • Run php artisan serve to start a dev server on localhost:8000, or use Valet.

  • If you're working on frontend stuff (things in the resources/assets folder), run npm run watch to re-build the JS/CSS.

Update OpenAPI documentation for Swagger UI:

./vendor/bin/openapi app -o public/openapi.json

Refreshing the database

Disable logging to database when refreshing the database:

LOG_CHANNEL=single php artisan migrate:refresh

Production

A deploy.php file is included for deploying the app with Deployer. This contains all the information needed to deploy the app.

Tests

Start by routing bibrex.test to localhost by adding an entry to /etc/hosts:

127.0.0.1 bibrex.test

Then start a development server:

php artisan serve --host=bibrex.test --no-interaction

In a new terminal, install/update/start Selenium using webdriver-manager:

npm i -g webdriver-manager
webdriver-manager clean
webdriver-manager update
webdriver-manager start

In a third terminal, run the tests:

SELENIUM_BROWSER_NAME=chrome php artisan dusk

Unfortunately, testing with Firefox doesn't work at the moment due to an incompability between Selenium and php-webdriver. See php-webdriver/php-webdriver#469.

Continuous integration browser testing supported by
BrowserStack

Privacy

Bibrex includes a couple of Artisan commands to enhance users' privacy and support the data minimisation principle:

  • bibrex:anonymize anonymizes all returned loans, by re-linking the loans with a special system user, so that the link between loan and user is lost. By default, Bibrex will run this every night.

  • bibrex:purge-logs deletes log entries older than the limit specified in the config/logging.php config file. By default, Bibrex will keep logs for 7 days.

  • bibrex:purge-notifications deletes notifications older than the limit specified in the config/bibrex.php config file. By default, Bibrex will keep notifications for 3 months.

  • bibrex:purge-users deletes inactive users. By default, Bibrex will keep imported users for 3 months and local users for 3 years. Imported users can be re-imported at any time, so in principle they could be kept even shorter, but looking up a user and checking out an item will both be considerably faster when we have a local copy, so some storage time makes sense. For local users, the user information have to be manually entered again if a user comes back after having been deleted, so a longer storage time makes sense. It's advised to try to limit the number of local users.

Større endringer

  • 2019-07-10 Støtte for flere identifikatorer per bruker, f.eks. flere lånekort.
  • 2019-02-06 Lagt til et enkelt API.
  • 2019-01-14 Automatisk sletting av inaktive brukere og gamle varsler.
  • 2018-02-12 Påminnelser og Alma-import av brukerdata.
  • 2016-18-10 Anonymisering av utlån.
  • 2013-11-04 Institusjonsbasert pålogging, med mulighet for autopålogging fra bestemte IP-adresser.
  • 2013-10-19 Sync som Artisan-kommando for enkel kjøring fra cron.
  • 2013-09-09 Sync: Hvis LTID har blitt aktivert i BIBSYS blir lån gjort på midlertid kort automatisk overført til brukerens LTID.
  • 2013-09-09 Mulighet for å deaktivere ting for utlån
  • 2013-09-05 Mulighet for å slette ting, men bare hvis ikke utlånt enda