A collection of tips to assist developers to configure their local workstation setup environment for FOLIO development.
Assume already doing other development, so know how to keep the operating system up-to-date, know its quirks, know how to use the various package managers. So this document will not go into detail about that.
FOLIO modules can be developed in any suitable programming language.
The FOLIO-Sample-Modules explains about module development. The various Stripes documentation explains user-interface development. Those also have more notes about setting up and managing the local development environment.
Note that some parts of the development environment could be handled using folio-ansible (virtual machines using Vagrant and Ansible).
Otherwise the development environment would need the following fundamental tools:
- Apache Maven (3.3+) and Java (8+) – For building and deploying Okapi and some server-side modules.
- Node.js (Active LTS version) – For Stripes and for some modules, and for UI testing.
- Docker – Recommended method for deployment.
- PostgreSQL (10) – For running an external database to support storage modules. This will enable faster startup and operations during development. Note that this is not required to be installed for running modules using the default “embed_postgres” option.
As each FOLIO component can utilise whatever suite of appropriate tools, refer to its requirements and notes to assist with setup.
Occasionally it becomes necessary to specify minimum versions of some tools:
- Java: 8u101 or higher.
- Postgres: 10.0 or higher, but below 11 because of reduced platform support of postgresql-embedded (postgresql-embedded supported versions, PostgreSQL Database Download).
curl – Many modules provide examples as curl requests. Alternatively those examples could be used with Postman via “import”.
To use a local development workstation together with a localhost FOLIO installation, will need 16+ GB of local memory.
Configuration for repository usage
FOLIO utilizes the Nexus OSS Repository Manager to host Maven artifacts and NPM packages for FOLIO projects. Docker images are the primary distribution model for FOLIO modules.
See Built artifacts for configuration details for accessing the released and snapshot FOLIO artifacts.
For developers needing to publish artifacts, an overview and usage configuration details are provided, see Build, test, and deployment infrastructure.
Style guidelines and configuration
Code analysis and linting
All code repositories have linter and code-style analysis facilities implemented as part of their continuous integration build process. The process is explained, along with usage notes and configuration for running those tools locally.
Use EditorConfig for consistent whitespace
Many FOLIO repositories have a
.editorconfig configuration file at their top level. This enables consistent whitespace handling.
Refer to EditorConfig.org which explains that some text editors have native support, whereas others need a plugin.
Consult its documentation for each plugin. Note that some do not handle all EditorConfig properties.
In such cases refer to the documentation for the particular text editor, as it might have its own facilities.
For example, the Java text editor in Eclipse has its own configuration for
No license header
As explained, we do not use a license header in the top of each source code file.
Please configure your IDE to use an empty license header. Some IDEs have a default template to remind developers to add one. We do not.
.gitignore file in each repository can be minimal if each developer handles their own.
One way is to configure your own user-specific global file (i.e. add
Then either use something like gitignore.io,
or just use a simple set such as the following.
Add other specific ones for your particular operating system, text editors, and IDEs.
## general *.log ## macos *.DS_Store ## maven target/ ## gradle .gradle/ build/ ## node node_modules/ ## vim *~ .*.sw? ## folio .vertx/
Update git submodules
Some FOLIO repositories utilize “git submodules” for sections of common code.
For example, each
mod-* module (and
raml-module-builder itself) include the “raml” repository as a git submodule as its
Note that when originally cloning a repository, use ‘
git clone --recursive ...’ which should automatically include any submodules.
Some git clients do not. If you then have an empty “raml-util” directory, then do ‘
git submodule update --init’
Thereafter upgrading that submodule (i.e. moving the git pointer of the referenced repository) is deliberately not automated, so that we can ensure a stable build when we git checkout in the future.
So when an upgrade is needed to be committed, do this:
cd ramls/raml-util git checkout master git pull cd ../.. git add ramls/raml-util mvn clean install git commit ...
Now when people update their local checkout, then some git clients do not automatically update the submodules. If that is the case for your client, then follow with ‘git submodule update’. If needed, then that could be automated with githooks.
For Maven-based modules, add to your POM file (copy the ‘git submodule update’ from mod-notes) to assist all git clients to update.
Note that when locally testing an upgrade of a git submodule, then do ‘
git add ramls/raml-util’ before running ‘mvn’.
Otherwise it will helpfully restore the referenced git pointer.