How to run folio backend modules with IntelliJ Idea and interact with Vagrant box environment

Can be used for running folio backend modules with IntelliJ Idea and further interaction with other modules running inside Vagrant box.

Step-by-step guide

1 Set IPv4 Address as on the picture below.

Open Host Network Manager in Oracle VM VirtualBox Manager (File → Host Network Manager or CTRL + H)

Add follolwing line to the vagrant file

config.vm.network "private_network", ip: "10.0.2.15", auto_config: false

Note: The 10.0.2.15 is Guest OS IP address, so you are able to make a call to the guest OS (where is running the FOLIO).

2. Build the module

mvn clean package

3. Create new Run Application configuration in IntelliJ Idea.

Fill in Main class and Program arguments (for RMB-based modules) filed as on the picture below (you can specify any http.port you want to run you module on).

The http.port value for certain module could be found via:

vagrant ssh
docker container ls | grep {module_name}

4. If your module requires database, put postgres-conf.json

(file with database address and credentials) under src/main/resources folder.

Example of postgres-conf.json:

{
  "host" : "localhost",
  "port" : 5432,
  "database" : "okapi_modules",
  "username" : "folio_admin",
  "password" : "folio_admin"
}

5. Run an application configured in a step 3

6. Add your ModuleDescriptor. POST /_/proxy/modules.

Copy ModuleDescriptor.json from target folder as is. No headers needed.

7. Add your DeploymentDescriptor. POST /_/discovery/modules.

Deployment descriptor example

{
  "srvcId": "mod-users-bl-5.1.0-SNAPSHOT",
  "instId": "5382d723-def7-4eeb-a301-48ec15f9bebe",
  "url": "http://10.0.2.2:8080"
}

srvcId could be found in ModuleDescriptor.json from step 6 (id field)

instId use any generated UUID

url with your module address instead of launch descriptor. Use port specified in the step 3 instead of 8080 and following host http://10.0.2.2

Notes:

The field "nodeId" in the json body is not needed as we have specified the url where the module is located

The 10.0.2.2 is Host IP address, so you are able to make a call to your module that is run on your machine (out your vagrant box)

8. Enable your module for a tenant with install

The purpose of this step is to replace old module id with new one.

Example

POST {HOST}:{PORT}/_/proxy/tenants/diku/install
[ {
  "id": "mod-users-bl-5.1.0-SNAPSHOT", "action":"enable"
} ]

Strictly speaking this is a downgrade of mod-users-bl, because existing SNAPSHOT.number is higher version than just SNAPSHOT.