Take FOLIO for a spin: updates to the FOLIO demo systems

We’ve made a significant number of changes to the [FOLIO Vagrant demo systems (Try it out: FOLIO Demo System) in the last few months. Here’s a summary:

There are currently 3 demo systems available on Hashicorp Atlas:

• folio/folio-demo – a full-stack FOLIO system, with Okapi, mod-users, mod-metadata, Stripes, and the Stripes modules trivial, ui-okapi-console, ui-users, and ui-items.

• folio/folio-backend – a backend FOLIO system, with Okapi, mod-users, and the mod-metadata modules.

• folio/folio-backend-auth – a backend FOLIO system with the mod-auth authentication subsystem, with Okapi, mod-users, mod-metadata, and the mod-auth modules. The authorization subsystem includes three sample users, diku_admin (password “admin”), auth_test1 (password “diku”), and auth_test2 (password “diku”).

All Vagrant boxes come with sample user and inventory data. The modules are enabled for the sample tenant, “diku”.

To try out any of these boxes, create an empty directory, cd into it, and initialize a Vagrantfile, e.g.:

$ vagrant init --minimal folio/folio-demo

If you have downloaded a previous version of the box, you will also need to update it with vagrant box update. Then you can launch the Vagrant box with vagrant up. Okapi will be listening on localhost port 9130, and the Stripes development server will be on localhost port 3000 (on the demo box only).

FOLIO system setup on Vagrant boxes

The prebuilt Vagrant boxes have the FOLIO stack set up to mimic production. Okapi is installed using a Debian installation package, with its home directory in /usr/share/folio/okapi, configuration files in /etc/folio/okapi, and logs in /var/log/folio/okapi. The backend modules, users-module (from mod-users), inventory and inventory-storage (from mod-metadata), and login-module, permissions-module and authtoken-module (from mod-auth) are deployed through Okapi using its Docker deployment facility. systemd service units are used to manage starting and stopping backend modules and Stripes. Modules are installed following the convention of configuration in /etc/folio and static files in /usr/share/folio.

Data is persisted for all modules using a PostgreSQL server running on the Vagrant box. The Docker engine is also installed, and configured to listen on localhost:4243 of the Vagrant box so that Okapi can use it for module deployment.

Updating FOLIO components on Vagrant boxes

All FOLIO components on the prebuilt Vagrant box come from artifacts created by the FOLIO CI process. That means that whenever a commit to the master branch of the source repository passes unit tests, a new artifact is made available. This makes it very easy to update.

WARNING: just because it is easy to update does not mean it is necessarily a good idea. The versions of the various components on the prebuilt boxes are known to work together. Updating any of them may well introduce breaking changes that will cause your FOLIO system to stop working.

Updating Okapi

$ sudo apt-get update
$ sudo apt-get install okapi

Updating Docker-based modules

# for a list of images
$ sudo docker images

# to update mod-users
$ sudo docker pull folioci/mod-users

# to undeploy and redeploy using the new image
$ sudo systemctl restart mod-users

Updating Stripes

To update Stripes or any Stripes components, update the Stripes package.json file at /etc/folio/stripes/package.json, changing the version of the component in the dependencies. Then cd to /usr/share/folio/stripes and type the following commands:

$ sudo -u okapi yarn install
$ sudo systemctl restart stripes

mod-auth modules (authtoken-module, login-module, and permissions-module) have been migrated to the latest version in the folio-backend-auth box v0.5.0, so they can now be updated like the rest of the Docker-based backend modules. I updated the post above to reflect this change. Enjoy!