Skip to main content
Version: v3

OIBus developer handbook

If you want to contribute on OIBus, it's the right place to start ! We use a GitHub repo. You may want to take a look at the known issues to start working on OIBus by fixing small items.

If you want to improve OIBus with a new feature, please contact us first to discuss how to best implement it. You can start with a new feature issue.

But first, you may want to download OIBus and start it on your machine from its sources.


  • Install Node.js and NPM. Check the .nvm file to check on which version of Node.js OIBus run. Of course, you can directly use the nvm tool
  • OIBus configuration is stored on a local SQLite database. You may need a SQL explorer tool such as DBeaver
  • OIBus can run on x64 or arm64 architectures (on Windows, Linux and Mac).
  • Frontend is build with Angular. No need to install it globally, since it is embedded in the dev dependencies.
  • The documentation uses Docusaurus, based on React

Steps to try out the application

Fork the repository

If you want to contribute into the project, first fork the repository, and clone it from your fork with:

git clone<your-fork>/OIBus.git.

You will be able to make contributions through Pull Requests

Otherwise, if you just want to try OIBus from source, simply run:

git clone

Init shared folder

Shared folder contains model and some tools shared between frontend and backend. At first startup, you must beforehand go into the shared folder and run npm install.

Start the frontend

Open a terminal in the frontend folder (cd frontend)

  • npm install
  • npm build: build the frontend that will be served by the backend
  • npm start: build the frontend and rebuild it on file changes. Useful when working on the frontend.

The frontend is served from the backend, even with npm start. That means it won't reload automatically the web page when files change. Just reload your page manually.

To test your code: npm test To check your files' linting: npm run lint

Start the backend

Open a terminal in the backend folder (cd backend)

  • npm install
  • npm start
  • Open up in the browser the following url: http://localhost:2223

The folder data-folder is used to store the cache, logs and configuration files.

The project is up and running, but currently there are no South or North connectors. A simple way to try out OIBus is to create a FolderScanner South connector and a Console North connector.

Start the documentation

Open a terminal in the documentation folder (cd documentation)

  • npm install
  • npm start
  • Access the documentation on the following url: http://localhost:3000

Submit your improvements

The default branch is main, every new branches must be created from this one. When you are satisfied with your changes, you can create a Pull Request from your Fork repository to the Main repository on GitHub.

Naming convention

Branch naming convention: descriptive-name-of-the-issue#<issue-number>, for example: fix-folder-scanner-path#1564.

Commits and PR name convention must follow the conventional commits standard.


All changes must be tested (with jest on the backend, with jasmine on the frontend) for three reasons:

  • To be sure to properly understand your changes.
  • To be sure that your changes are properly integrated in the project.
  • To be sure we won't break your changes in futures modifications (if so, your tests will probably fail).