OpenBoxes is a supply chain management system designed to manage inventory and track stock movements for healthcare facilities.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
deploy upgraded to the latest version of the rendering plugin Jan 31, 2014
docs OBPIH-882 Add translation support (#651) Dec 17, 2018
grails-app Merge pull request #795 from openboxes/OBPIH-1473 Jan 23, 2019
lib Initial commit that fixes a few issues with the picklist (PIMS-2592, … Jul 19, 2013
liquibase Adding plugin descriptors for spock and liquibase inline plugins Apr 15, 2016
scripts OBPIH-1062 Fixed unit tests - previous commit was made in error Sep 7, 2018
spec Fixed compilation and test failures May 8, 2013
spock Adding plugin descriptors for spock and liquibase inline plugins Apr 15, 2016
src OBPIH-1567 Populate receiving bin for added line on partial receiving Jan 23, 2019
test Fixed failing unit tests Jan 18, 2019
web-app Fixed a few minor UI issues with the show dialog mechanism (including… Jan 12, 2019
wrapper Added grails wrapper for use with continuous integration Oct 20, 2014
.babelrc Add Jest as Testing Framework for React May 8, 2018
.eslintrc OBPIH-824: Add eslint to project Apr 26, 2018
.gitignore Merge branch 'master' into develop Dec 7, 2018
.travis.yml Run eslint on CI, with `npm run bundle`. Jul 27, 2018 updated changelog to remove future versions and fix a minor bug Mar 31, 2017 Fixed badges on README to point to develop instead of master Dec 16, 2018 OBPIH-829 Added a simple no-auth version of the stock movement API th… Jun 15, 2018
epl-v10.html PIMS-940 Add a copy of the EPL 1.0 text to the root folder Oct 1, 2012
grailsw Added grails wrapper for use with continuous integration Oct 20, 2014
grailsw.bat Added grails wrapper for use with continuous integration Oct 20, 2014 swith javascript test to use phantom jasmine Nov 13, 2012
mkdocs.yml OBPIH-882 Add translation support (#651) Dec 17, 2018
package-lock.json OBPIH-511: Sorting picklist by bin name improvements (#712) Dec 18, 2018
package.json OBPIH-882 Add translation support (#651) Dec 17, 2018 insert test data in bootstrap only Oct 23, 2012 add loadtest env; usage:'load=10000 grails -Dgrails.env=loadtest run-… Dec 6, 2012 insert test data in bootstrap only Oct 23, 2012
styleguide.config.js React documentation Aug 31, 2018
webpack.config.js OBPIH-1419: Page placeholder for stock list management feature (#625) Nov 15, 2018

Stories in Ready Build Status Documentation Status Slack Signup



OpenBoxes is an Open Source Inventory and Supply Chain Management System. The initial implementation of OpenBoxes will occur at Partners In Health-supported facilities in Haiti.


Copyright (c) 2012 Partners In Health. All rights reserved. The use and distribution terms for this software are covered by the Eclipse Public License 1.0 ( which can be found in the file epl-v10.html at the root of this distribution. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software.

Setup development environment

Install Dependencies



Basic setup instructions for developers

These instructions are for developers only. If you are a user/implementer, please check out our Installation documentation.

1. Install Dependencies

Install dependencies above

2. Install Grails

Check that you have SDK Man installed properly (otherwise follow instructions on the skdman install page).

$ sdk version
SDKMAN 3.1.0

Install Grails 1.3.9

$ sdk install grails 1.3.9
3. Clone repository
git clone      

Otherwise, replace git url with the one of your forked repository

git clone<gitusername>/openboxes.git      
4. Create database

Create openboxes database

mysql -u root -p -e 'create database openboxes default charset utf8;'

Create openboxes user

mysql -u root -p -e 'grant all on openboxes.* to "openboxes"@"localhost" identified by "openboxes";'
5. Create Openboxes configuration file

Edit $HOME/.grails/

# Database connection settings
# You can use dataSource.url when you are using a non-dev/non-test database (test-app may not run properly).
# If you want to run $ grails test-app you should comment out the dataSource.url below and create a new 
# openboxes_test database.  Eventually, we will move to an in-memory H2 database for testing, but we're 
# currently stuck with MySQL because I'm using some MySQL-specific stuff in the Liquibase changesets.  My bad.
# MySQL 5.5 required a few extra parameters but these are no longer needed if using MySQL 5.7
# ?autoReconnect=true&zeroDateTimeBehavior=convertToNull&sessionVariables=storage_engine=InnoDB


# OpenBoxes mail settings (disabled by default)

# OpenBoxes > Inventory Browser > Quick categories
#openboxes.inventoryBrowser.quickCategories=ARVs,MEDICAL SUPPLIES,FOOD,EQUIPMENT,MEDICINE

# OpenBoxes > Choose Location > Required Activities
# The supported activities required in order for a location a location to show up on Choose Location page.
#openboxes.chooseLocation.requiredActivities = "MANAGE_INVENTORY"

# If you wish to not set up any test data, you can indicate this per the below 
# (eg. if you are running from a copy of a production db)
# openboxes.fixtures.enabled=false

# Google Product Search
#google.api.key=<Google API key>

# API (NDC Lookup)
#hipaaspace.api.key=<hipaaspace API key>

# RXNorm API
#rxnorm.api.key=<RxNorm API key>

# Google analytics = false = <Google Analytics Key>

NOTE: If you are running in development mode with a copy of an existing production database, you will need to instruct the application to not setup test fixtures automatically by uncommenting the above property:

6. Install NPM dependencies
npm install
7. Build React frontend

You can build React frontend with this command, but it will be automatically build when starting the application.

npm run bundle
8. React frontend Hot-Reload

When using this command React fronted will be rebuild automatically after any change, you just need to refresh the browser to see the effect.

npm run watch
9. Upgrade the project to the currently installed grails version

Either of the following actions (upgrade, compile, run-app) should generate the all important Spring configuration (/WEB-INF/applicationContext.xml) and start the dependency resolution process.

grails upgrade


grails compile

The grails compile step is not necessary since grails run-app will invoke the compilation step, but it doesn't hurt anything.

If you see any errors, run the command again.

IMPORTANT That last line is important. Because of some quirkiness with the way older versions of Grails resolve dependencies and generates config files, you may need to run either of these commands multiple times in order to resolve all dependencies and generate the config files.

Once the dependency resolution phase has completed, all dependencies will be stored in a local ivy cache (usually under $USER_HOME/.grails/ivy-cache). You do not have to worry about this, just know that the dependencies are now on your machine and Grails will attempt to find them there before it tries to resolve them in a remote repository.

10. Start application in development mode

The application can be run in development mode. This starts the application running in an instance of Tomcat within the Grails console. You may need to run 'grails run-app' several times in order to download all dependencies.

grails run-app
11. Open application in Google Chrome
12. Log into OpenBoxes

You can use the default accounts (manager:password OR admin:password). Once you are logged in as an admin, you can create own account. Or you can use the signup form to create a new account.

13. React tests

To run new frontend (React) tests type:

npm test
13. React documentation

Start a style guide dev server:

npm run styleguide

View your style guide in the browser:



How to Debug

  • Run Grails in debug mode
    grails-debug run-app
  • In Intellij navigate to Run > Edit Configurations
  • Create a new Remote Debug Configuration
    • Name: openboxes-debug
    • Transport: Socket
    • Debugger mode: Attach
    • Host: localhost
    • Port: 5005
  • Command line arguments should look something like this:


Caused by: Could not open ServletContext resource [/WEB-INF/applicationContext.xml]


Execute the grails upgrade command in order to generate the files nece

$ grails upgrade

See the following stackoverflow article: