This document explains the necessary steps to run a complete FOLIO system, including using the Okapi Console to start modules on the server. We will use the Users module as our exemplar.
NOTE: This document is out-of-date. Much of it is still useful. However the section about adding the users modules and sample users data is out-of-date. It would be better at this stage to use the Pre-built Vagrant boxes.
Two sets of software are involved here: on the server side, Okapi with its modules (including the Users module); and on the client side, Stripes with its modules (including the Okapi Console and the Users module).
To exercise the Users module from a Stripes UI, you need to run both sets of software. Developers may wish to install, build and run it all locally, but there are alternatives:
-
You can use the FOLIO Ansible Playbook to bring up a virtual machine running Okapi with modules including Users already running. This exposes its Okapi service on the same port (9130) as a local Okapi, so no configuration changes are needed in the UI.
-
You can configure your local UI to connect to a remote Okapi service, perhaps running as part of the continuous integration scheme. Do this by changing the Okapi URL in the
okapi.urlsetting in thestripes.config.jsfile (url must be absolute path) . -
Alternatively, you can use an existing UI and Okapi in a CI installation on an AWS cluster by pointing a browser to
http://redux-okapi-test-aws.indexdata.com/(But module deployment must be done differently in this context, as the JAR files are typically not available.)
If you are using any of these alternative approaches, you can skip the server-side instructions and go straight to the client side.
We will assume that all the software is checked out in the same parent
directory, which we will designate as $FOLIO_ROOT.
Full instructions are found in the Okapi documentation but the brief version is:
$ cd $FOLIO_ROOT
$ git clone --recursive https://github.com/folio-org/okapi.git
$ cd okapi
$ mvn install
$ mvn exec:exec
Stopping and re-running Okapi in this way (mvn exec:exec) gives a
new instance of Okapi with no state left over from earlier runs. This
allows the Okapi Console to run against a known state.
These tools auto-generate the server-side interface glue code from RAML specifications, and are needed to build the Users module. Leaving Okapi running its own shell, fetch and build in another shell:
$ cd $FOLIO_ROOT
$ git clone --recursive https://github.com/folio-org/raml-module-builder.git
$ cd raml-module-builder
$ mvn install
We need to build the Users module, but we don't need to run it: Okapi will do that for us when needed.
$ cd $FOLIO_ROOT
$ git clone --recursive https://github.com/folio-org/mod-users.git
$ cd mod-users
$ git submodule init
$ git submodule update
$ mvn install
The most important output is mod-users/target/users-fat.jar, which
we will later be asking Okapi to run for us.
If you wish, you can test that it works OK by running it manually:
$ java -jar target/mod-users-fat.jar
starting rest verticle service..........
[etc.]
... INFO Succeeded in deploying verticle
The output can be voluminous and rather opaque, but if it contains the line "Succeeded in deploying verticle" then all is well. Now kill the running module, so that Okapi can start it as needed.
The steps to configure Stripes are explained in the Quick Start document. The UI Users module ui-users is enabled by default.
As explained there, to use local development versions of any module, follow the 'yarn link' instructions. Otherwise, Yarn will use the published packages from the "npm-folio" repository.
Add the ui-okapi-console module to the Stripes configuration:
$ cd $MY_DEV/stripes-sample-platform
Edit the file stripes.config.js to add @folio/okapi-console.
Note that this module is not yet published, so use a local git checkout
and follow those 'yarn link' instructions.
By default, the Stripes UI requires you to log in before you can access any of the UI modules. But making that work entails building and installing several authentication-related server-side modules, so it is simpler to modify the configuration of Stripes so that authentication is not required. (Don't do this for production systems!)
Edit the file stripes.config.js, and in the config section change
disableAuth: false to disableAuth: true.
NOTE. This
disableAuthoption is deprecated, since many facilities will no longer work without a logged-in user who has the relevant permissions. Instead, it is now necessary to set up authentication services and populate them with suitable users, credentials and permissions. To be documented.
Now you can run the UI server in your stripes-sample-platform directory, and it
will pull in the specified modules and make the complete set of HTML,
CSS and JavaScript assets available:
$ cd $MY_DEV/stripes-sample-platform
$ yarn start
Point your browser to http://localhost:3000
to see the Stripes application's home page. From there, you can
navigate to the Okapi Console.
You can also go to the Users UI module, but unless you are using a virtual machine (e.g. folio-backend) or some other method of deploying the modules and test data as explained above, then it will not work yet because the server-side module has not been set up. So continue with the following steps using the Okapi Console.
NOTE: This document is out-of-date. Much of it is still useful. However the section about adding the users modules and sample users data is out-of-date. It would be better at this stage to use the Pre-built Vagrant boxes.
From within the running Stripes UI, follow these steps.
First, fill in the module proxy section:
- Click the Okapi Console menu item in the bar at the top of the page.
- Click the Modules menu item below the top bar.
- Click Add module.
- Fill in the Name textbox with
Users(or any name). - Click the +Add provision button next to the Provides heading.
- Type
_tenantinto the Module ID box. - Type
1.0.0into the Version box. (i.e. as specified in mod-users/ModuleDescriptor.json) - You can ignore the +Add requirement entry for our present purposes.
- Click the +Add route button next to the Routing heading.
- Click the new +Add HTTP method button that has appeared to the right of the new Methods caption.
- Type
GETinto the Methods box. - Click the + button to the right of this box. Another empty Methods box appears below the one you filled in.
- Type
POSTinto the new HTTP method box and click the + button. Another empty Methods box appears below the one you filled in. - Type
PUTinto the new HTTP method box and click the + button. Another empty Methods box appears below the one you filled in. - Type
DELETEinto the new HTTP method box and click the + button. (Another empty Methods box appears below the one you filled in. Ignore it.) - Fill in the three elements of the routing entry as follows:
- Request path to module:
/users - Priority level:
30 - Request type:
request-response
- Request path to module:
- Click the + button to the right of the routing entry. (Another empty routing entry appears below the one you filled in. Ignore it.)
- Click the Add module proxy button below the routing entries.
Now deploy the module locally to the running Okapi node:
- Pull down the Node dropdown (below the Service ID and Inst ID read-only textboxes), and select the only value that is
presented,
http://localhost:9130/. - Fill in the Exec entry with the following command-line, which
Okapi will use to start the Users module:
java -jar ../mod-users/target/mod-users-fat.jar -Dhttp.port=%p embed_postgres=true - You can ignore the Start command and Stop command entries in this scenario.
- Press the Submit button at bottom right. (Another empty deployment entry appears below the one you filled in. Ignore it.)
Presently, the Users module is locked to a specific tenant, with the
ID diku. This will be fixed in the future, but we live with it for
now. To create the tenant, go back to the Okapi Console part of the
Stripes UI, and follow these steps:
- Click the Tenants link.
- Click the Add tenant link at the bottom.
- Fill in the ID field with the value
diku. - Fill in the Name and Description fields however you wish.
- Click the Add Tenant button at the bottom.
You will be returned to the tenant list, with the new Diku tenant listed.
- Click the Edit link next to the Diku tenant.
- At the bottom of the edit page is a list of modules available to the tenant. One of them (possible the only one) is Users. Click the Enable link next to it.
The Users module is now inserted into Okapi, deployed and enabled for the Diku tenant.
We may introduce a bulk-ingest facility into the Okapi Console or the Users module later; but for now, the sample users must be added from the command line.
For historical reasons, the JSON files describing the sample users are
maintained as part of the FOLIO Ansible module, folio-ansible. So we need
to clone this repository and use it to add the users.
$ cd $FOLIO_ROOT
$ git clone https://github.com/folio-org/folio-ansible.git
$ cd folio-ansible/roles/mod-users-data/files
$ for f in *; do
curl -w '\n' -X POST -D - \
-H "Content-type: application/json" \
-H "X-Okapi-Tenant: diku" \
-d @$f http://localhost:9130/users
done
Finally, back in the Stripes UI, you can click on the top-level Users heading and see the displayed list of users.