This document will outline steps to enable a development environment with a smaller resource footprint than the standard FOLIO Vagrant box. The environment will be suitable enough to run Karate tests.
Requirements
Docker Engine & Docker Compose is available on the host machine.
This guide is written with Rancher Desktop in mind. Other flavors can work but there may be new issues not already triaged.
- If Rancher Desktop is used on Windows, It is required to enable network tunneling via Preferences > WSL > Network
- Access to BusyBee source code at https://github.com/Olamshin/busybee or similar.
Base Services
Every FOLIO cluster needs services like Postgres and Kafka to function. The docker-compose file below will instantiate the services. It is a decent starting point with default credentials that will be used through out this document.
Copy the file below into a directory somewhere. Make sure it is named docker-compose.yml
Linux
If the operating system is Linux, at the time of writing, host.docker.internal
is not a domain name that is automatically configured. One workaround is to replace every instance of host.docker.internal
with 172.17.0.1 or your IP address in the docker-compose.yml file. This thread provides some insight on how to enable host.docker.internal for Linux.
Execute the following in the same directory as the docker-compose.yml file above
docker-compose up -d
The following script will wipe the database created by the docker-compose.yml script above. This is good for starting from scratch.
docker-compose stop postgres docker-compose rm postgres -f docker-compose create postgres docker-compose start postgres
OR just run the below to wipe everything
docker-compose down
Ensure that base services are accessible before continuing! Typically, if one of the services are accessible, most likely others are as well.
- postgres: Verify that you connect to the postgres container at port 5432 via PgAdmin or other similar tool
- OKAPI: Confirm that the service at port 9130 returns a response.
The only container that should disabled is the "createbuckets" container used to create a bucket in minio.
BusyBee
BusyBee is a tool that helps to streamline HTTP calls to okapi to manage the development environment. Get the source code at https://github.com/Olamshin/busybee
Python 3.11 is the latest version required for BusyBee. Any version higher than 3.11 should not be used.
Run the following to install required dependencies for busybee. Run the following commands in the directory where BusyBee is located.
pip install -r requirements.txt
The first invocation of BusyBee should fail and create a config file at a location that needs to be updated. The location should be in the BusyBee response. The config should be in a .busybee
folder in your home directory.
python -m busybee
After the BusyBee config is updated, invoke BusyBee once more. You will be launched into another terminal where special commands are supported.
To start creating the dev environment, run the following:
start
Working With Custom Versions Of Modules
FOLIO modules that are initialized by BusyBee are at the same version of the install.json provided. During development, it is necessary to make code changes to a branch and test. This section will describe how to accomplish this with mod-inventory as an example.
Run the command below in BusyBee terminal. It will remove the docker container created by OKAPI that would represent mod-inventory.
undeploy -m mod-inventory
Start a custom version of mod-inventory and note the port on your local machine where it will be available. In our example, custom mod-inventory is started on port 7000. Run the command below in a BusyBee terminal to redirect mod-inventory requests from OKAPI to custom mod-inventory
redirect -m mod-inventory -l http://host.docker.internal:7000
Now OKAPI will forward requests to the custom mod-inventory at port 7000.
To remove the redirect, run the command below in the BusyBee terminal
redirect -m mod-inventory -rm
To enable the original docker container for the mod-inventory version in the install.json, run the command below
deploy -m mod-inventory
These steps can be executed for any module initialized with BusyBee
There are more tips here: BusyBee Tips & Tricks
FOLIO UI
The FOLIO UI can be built by git cloning the platform-complete repository. The "snaphot" branch of platform-complete is a better starting point that the "master" branch. At the time of writing platform-complete requires a Node v18 runtime and yarn installed as a node module. After NodeJS has been installed, Yarn can be installed globally with:
npm i -g yarn
The command above needs to be run only once.
With the platform-complete repository as the current working directory, required node modules can be installed with:
yarn install
The command above should only the executed once unless the current branch of the platform-complete repo is updated. Or if install.json is modified to include/exclude modules and module versions updated.
FOLIO UI can then be started with:
yarn start