FOLIO Developer Curriculum

Getting Started with FOLIO for Developers

00: Introduction
01: Clone, Build, and Explore Okapi
02: Initialize Okapi from the command line
03: Enable Okapi Authentication
04: Deploy test Stripes module
05: Set up the Okapi Users app

FOLIO Developer Curriculum Outline

This is an outline of a tutorial that can be given to a group in a workshop or followed by an individual developer in a self-paced fashion.


System Requirements

There are two choices: either running the Stripes Development UI Server and the Okapi Gateway directly on a developer’s machine (“on-machine”) or running Stripes and Okapi in a VirtualBox guest. An Ansible playbook with appropriate roles is used to create the VirtualBox guest, and can also be used to automatically build a developer’s environment (making the playbook target localhost).


Before attending the workshop, participants must meet these requirements. When in doubt, using the VirtualBox guest machine is recommended.


(Note that on MacOS these prerequisites can be installed using Homebrew.)

VirtualBox guest

To download the VirtualBox guest:

  1. Make a clean directory and change into it: mkdir folio-curriculum && cd folio-curriculum
  2. Set up the Vagrantfile: vagrant init --minimal folio/curriculum
  3. Launch the VirtualBox guest: vagrant up
  4. Connect to the VirtualBox guest: vagrant ssh

In subsequent lessons, the command lines are executed within the VirtualBox guest. Be sure you are connected to the VirtualBox guest (from the host computer: vagrant ssh) before running the commands.

Other instructions and commands that are specific to the VirtualBox guest mode of using the tutorial are noted using this style of information box.

If launching Vagrant from a Windows Command Prompt, be sure to use Run As Administrator… when opening the Command Prompt itself (cmd.exe). If you are seeing the error “EPROTO: protocol error, symlink”, the likely cause is that Vagrant was not launched with administrator privileges. See issue STRIPES-344 for details.

Set FOLIO_ROOT Variable for Lessons

Each lesson assumes the existence of a $FOLIO_ROOT shell variable. This variable holds the path to a directory where the components of the Okapi Server and the Stripes Development UI Server are located.

If using the VirtualBox guest setup, it is recommended to first cd /vagrant before creating the empty directory. Doing so makes the Okapi and Stripes files available from the host operating system in the same directory the Vagrantfile file is located.

The first command below connects from the VirtualBox host to the VirtualBox guest. The second command changes the working directory to the shared vagrant directory.

$ vagrant ssh
$ cd /vagrant

Create the directory, enter the directory, and save the directory location using these commands:

$ mkdir folio-tutorial-working-files
$ cd folio-tutorial-working-files
$ export FOLIO_ROOT=`pwd`


  1. Clone, build and explore Okapi
  2. Initialize Okapi Gateway from the command line
  3. Enable Okapi Authentication
  4. Deploy test Stripes package
  5. Real-world application: set up the FOLIO Users app
  6. Build a skeletal RAML-module-builder module (coming soon)

Run Jekyll Locally

To view the documentation locally:

Additional information

See project FOLIO at the FOLIO issue tracker.

Other FOLIO Developer documentation is at