Backend

• All the backed modules contain a Vagrantfile
  • this is for convenience, but it's really important to note that you only ever run 1 vagrant image - and that will coordinate all the modules you want to run
  • so if you want to run mod-agreements and mod-licenses together, you will need to use only one of the Vagrantfile images - usually use the mod-agreements one
  • check the version of the folio/testing-backend being used by the Vagrantfile before running looking for uncommented lines like:

    • config.vm.box_version = "5.0.0-20190612.2294"

  • Comment out this line from the Vagrantfile if you want to just run the latest version
  • For vm.box_version above (approx) 5.0.0-20210204.5783, consider increasing v.memory and v.cpus in the file as follows:

    • v.memory = 12288

    • v.cpus = 4

• Once you have done a vagrant up you have a folio running with a base collection of modules
• We then need to start up our backend modules - mod-agreements and mod-licenses -
  • Both modules have a scripts directory with a run_external_reg.sh script which you probably want to use.
  • The process is usually cd <module>/service; grails war; ../scripts/run_external_reg.sh

    • NB instead of ../scripts/run_external_reg.sh you can use grails -Dgrails.env=vagrant-db run-app  which will give increased logging

  • NOTE: the run_external_reg.sh script uses a jar file in ../build/libs.   The script may need to be modified to use the correct version of the jar file.
  • This is enough to build the module and start it up.

• At this point you have a running folio and your running modules, but the running OKAPI does not know that it should route requests for the diku tenant to your running modules.
  • In order to do that we provide a register_and_enable.sh  script in the scripts directory
  • NOTE: This script uses the "jq" command, which may be installed on a MAC using "brew".
  • Running this script (one for each backend module you want to enable for the diku tenant) will connect the okapi running in the vagrant image to the running modules.
• This gets you a backend system.
  • Both modules have test scripts that you can use to exercise the backend as a whole by talking to the OKAPI on port 9130.
  • You will see a script called okapi-cmd in both scripts directory - you can use this to trigger a URL directly - for example ./okapi-cmd /licenses/licenses  will trigger the index action on the licenses controller in the licenses module.
• If you need to drop the database you can use a one-liners like (substituting the correct username/password):

  • vagrant ssh -c 'export SCHEMA=diku_mod_licenses;PGHOST=10.0.2.15 PGDATABASE=okapi_modules PGUSER=<username> PGPASSWORD=<password> psql -c "DROP SCHEMA IF EXISTS $SCHEMA CASCADE;"'

  • vagrant ssh -c 'export SCHEMA=diku_mod_agreements;PGHOST=10.0.2.15 PGDATABASE=okapi_modules PGUSER=<username> PGPASSWORD=<password> psql -c "DROP SCHEMA IF EXISTS $SCHEMA CASCADE;"'

  • then stop and restart the backend (re-run ../scripts/run_external_reg.sh )
  • then re-register the module (e.g. by re-running the ../scripts/register_and_enable.sh)

Backend troubleshooting

• If you need to update the version of the backend you are running with Vagrant, update the config.vm.box_version setting in the Vagrantfile to the appropriate version (or remove this restriction completely to get the latest version), then try:

vagrant halt
vagrant destroy
vagrant box update
vagrant up

• If you get errors such as "Access requires permission: <permission name>" check you are running the latest version of folio/testing-backend (see above)

• On macOS the default sed install recognize the -r option, which causes the okapi-cmd script to fail

  • Use "brew install gnu-sed" to install the Gnu version of sed as gsed

  • Update the okapi-cmd and okapi-login scripts to use gsed instead of sed

SQL Logging

If you want to see what SQL statements are being created in the application log you can make the following changes:

• In /service/grails-app/conf/application.yml uncomment the following lines

hibernate:
# format_sql: true

• In /service/grails-app/conf/application.yml uncomment the following lines

dataSource:
# logSql: true

• In /service/grails-app/conf/logback.groovy uncomment the following lines

//logger("org.hibernate.SQL", DEBUG)
//logger("org.hibernate.type.descriptor.sql.BasicBinder", TRACE)

Avoid GOKb harvesting

If you do not need/wish to harvest GOKb data in your test instance, before you run the register_and_enable.sh  script in Agreements, edit the file /service/src/main/okapi/tenant/sample_data/diku-data.groovy

Find the code block starting:

RemoteKB gokb_test = RemoteKB.findByName('GOKb_TEST') ?: new RemoteKB(

And change:

active:Boolean.true → active:Boolean.FALSE,

Trigger GOKb harvest (and clear database)

If you are in a position where you need to trigger a fresh harvest to check against your code changes, then you can run the following from within your mod-agreements directory while mod-agreements is running.

curl -H 'X-OKAPI-TENANT: diku' -XDELETE http://localhost:8080/_/tenant
curl -XPOST -H 'Content-Type: application/json' -H 'X-OKAPI-TENANT: diku' http://localhost:8080/_/tenant -d '{ "parameters": [{"key": "loadSample", "value": true}, {"key": "loadReference", "value": true}]}'

This will drop the currently initialised tenant, clearing the database and essentially acting as if you had started a fresh vagrant image and run the `register_and_enable` script. This will trigger a fresh GoKB harvest.

Setup eHoldings

To work with eHoldings requires a customer ID and API key for the EBSCO EKB Sandbox. These can be obtained from Khalilah Gambrell or Carole Godfrey  at EBSCO

Once obtained these can be entered via the UI via:

 Settings → eHoldings → Knowledge base

Frontend

• The front-end can easily be deployed by using the platform-erm Stripes platform.
• To use local copies of applications with checked-out repositories, following the instructions in the Developing and Contributing section
• The full Stripes CLI user guide is available at https://github.com/folio-org/stripes-cli/blob/master/doc/user-guide.md and is a comprehensive guide to the Stripes CLI

Frontend troubleshooting

Make sure you are using the appropriate branch of platform-erm

Check the folio registry that is configured using the command:

cat ~/.yarnrc

Make sure you are using the registry specified in the platform-erm README)