Stripes CLI offers many commands for interacting with Okapi to manage back-end modules for a tenant on a Vagrant VM. This guide steps through the process of standing up a back-end to support a unique front-end platform.
- Prerequisites
- Set up back-end modules for your platform
- Set up back-end modules for your platform (multi-step)
- Connect a local back-end module to an existing platform
This guide requires folio/snapshot-backend-core, folio/snapshot-core, folio/minimal, or equivalent Vagrant box. The "core" VMs come pre-loaded with modules to run platform-core modules.
$ mkdir snapshot-backend-core
$ cd snapshot-backend-core
$ vagrant init folio/snapshot-backend-core
$ vagrant up
See the Stripes development setup guide for information to update an existing Vagrant box.
Start by cloning your desired platform, such as platform-erm.
$ git clone https://github.com/folio-org/platform-erm
$ cd platform-erm
$ yarn install
Optionally, create a .stripesclirc configuration file to store an Okapi URL and tenant ID. Place your CLI configuration in your platform directory or above.
{
"okapi": "http://localhost:9130",
"tenant": "diku"
}
Tip: Alternatively, environment variables can be used.
This step is not required. It is only a convenience so we don't have to include --okapi and --tenant options with every command. For simplicity, the commands in this guide will assume these values are present in a config.
Note: When using a command that reads from a stripes tenant config containing
okapi.urlandokapi.tenant, supplying--okapiand--tenantoptions (via command-line or.stripesclirc) is not necessary. The CLI will useokapi.urlandokapi.tenantvalues found in the stripes config to populate--okapiand--tenantautomatically. If they are provided anyway,--okapiand--tenantwill take precedence.
The CLI attempts to simplify the back-end setup process by automating many steps with one command. This command assumes your platform's front-end (folio_*) and back-end modules have published descriptors available to pull from the remote registry. If your front-end ui-module descriptors have not yet been published, you can add add them to your VM with the CLI's mod add.
$ stripes mod add --strict
The following command, run from within your platform directory, will prepare and deploy modules and their dependencies for your tenant via Okapi's /_/proxy/tenants/{tenant_id}/install endpoint.
$ stripes platform backend stripes.config.js --user diku_admin --remote http://folio-registry.aws.indexdata.com
When running this command, the following operations are performed by the CLI and Okapi:
- Given a
--remote <url>(optional), Okapi's module descriptors are first updated with the latest from the remote registry. - Generate module descriptor ids with the tenant config
stripes.config.jsand the yarn installed front-end modules - Append those ids with additional known dependencies. For example,
mod-codex-inventoryis included if the platform includesfolio_searchandfolio_inventory. - Perform a dry-run install and reports a summary
- Deploy and enable the back-end modules
- Post the front-end modules descriptors
- Given a
--user <username>, assign missing module permissions to the user
Bypass updating module descriptors from a remote registry by omitting --remote.
$ stripes platform backend stripes.config.js
Conclude the operation with the dry-run simulation by adding, --simulate. Optionally add --detail to view the Okapi response.
$ stripes platform backend stripes.config.js --simulate --detail
Include additional modules with --inlcude and supply a space-separated list of module ids.
$ stripes platform backend stripes.config.js --include mod-x mod-y
For more granular control or to better observe the intermediate operations above, the following individual commands can be performed to achieve the same result.
Your Vagrant box will only have module descriptors available for the modules that it came pre-built with. The mod pull command will instruct Okapi to download the latest module descriptor ids from a remote registry.
$ stripes mod pull --remote http://folio-registry.aws.indexdata.com
This will take the tenant config, stripes.config.js and convert the selected modules into module descriptor ids. Additional front-end stripes-* modules will be included like stripes-core.
$ stripes mod descriptor stripes.config.js > my-module-ids
While stripes platform backend offers some logic to dynamically append a few module ids that are not otherwise required by a front-end platform, the CLI doesn't currently offer a stand-alone command to do the same. Manually add any module ids that you know you need, but are not pulled as a dependency of other modules. Simply edit the prior output file to append the desired ids.
$ cat >> my-module-ids << 'EOF'
mod-codex-inventory
mod-x
mod-y
EOF
Using the my-module-ids file from the prior command as input, pipe the list to stripes mod install with the --simulate option set. This will call Okapi to generate a list of the necessary dependencies and their actions, such as enabling or upgrading, needed. Save this output to a file as it will be used in the next steps.
$ cat my-module-ids | stripes mod install --simulate > my-module-actions
Using the output from the --simulate dry run, filter the results for back-end modules. For this you can pipe your output through the stripes mod filter command. Then pass the filtered results onto stripes mod install with the --deploy option.
$ cat my-module-actions | stripes mod filter --back | stripes mod install --deploy
Using the same output from the dry run, this time filter the results for front-end modules only. Pass the results to stripes mod install (without --deploy) enable them for the tenant.
$ cat my-module-actions | stripes mod filter --front | stripes mod install
In order to make use of the newly installed modules for development, assign module permissions to a user. This can be done by chaining a few stripes commands together. The following will gather permissions for all of the tenant's modules, filter permissions to those the user doesn't have, and attempt to assign them to the user.
$ stripes mod list | stripes mod perms | stripes perm filter --unassigned diku_admin | stripes perm assign --user diku_admin
The following describes how to incorporate a local development instance of a backend module with an existing Okapi using stripes CLI commands.
- Create and run the folio/snapshot-core vagrant box
- Build and host your local back-end module following its instructions (example).
Commands below assume --okapi and --tenant values have been set via configuration. Please include these options with your commands if not previously set.
From your back-end module's directory, post its module descriptor with the mod add command. It is important to run this command after an install/build since the module descriptor found within the /target directory will be used.
$ stripes mod add
From the back-end module's directory, use the mod discover command register your locally running module instance. Provide the port where it is hosted locally.
$ stripes mod discover --port 8080
Variations of this command can be useful. For example, to see existing instances, run the command with no options. To clear out all existing instances, use the --forget option. See mod discover in the command reference for more information.
For the commands below, mod descriptor simply returns the module descriptor id so that we can pipe this into the mod install command.
Optionally, review what changes will take place beforehand with --simulate.
$ stripes mod descriptor | stripes mod install --simulate
Enable this module for your tenant with mod install.
$ stripes mod descriptor | stripes mod install