Running OpenBoxes Locally

Installation Instructions

The following instructions describe the minimum steps required to build and run the application on your local machine.

If you're system administrator looking to deploy the application to a production server, you'll want to read through the installation documentation instead.

1. Install Dependencies

Each of the following will need to be installed on your local machine:

Dependency	Version
MariaDB	10.11.4 (MySQL 8.0 is a supported alternative)
NPM	6.14.6
Node.js	14+
Java	8.0
Grails	3.3.18

Installing Java and Grails

We recommend using SDK Man to easily install and manage your SDK versions. With it, you can install Java and Grails on the command line using:

sdk install java 8.0.452-zulu
sdk install grails 3.3.18

Installing MariaDB (or MySQL)

Linux

You can install the SQL server via Advanced Package Tool:

sudo apt install mariadb-server-10.11.4

Or for MySQL:

sudo apt install mysql-server-8.0

Mac

Installing NPM and Node

Linux

You can install the Node and NPM via Advanced Package Tool:

sudo apt install nodejs
sudo apt install npm=6.14.6

Mac

2. Configure the database instance

Create the openboxes database:

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

Create the "openboxes" user:

mysql -u root -p -e 'CREATE USER "openboxes"@"localhost" IDENTIFIED BY "openboxes";'
mysql -u root -p -e 'GRANT ALL PRIVILEGES ON openboxes.* TO "openboxes"@"localhost";'
mysql -u root -p -e 'FLUSH PRIVILEGES;'

3. Create Openboxes configuration file

Create the ~/.grails/openboxes.yml file with the following contents:

MariaDB

dataSource:
  url: jdbc:mariadb://localhost:3306/openboxes?serverTimezone=UTC&useSSL=false
  driverClassName: org.mariadb.jdbc.Driver

MySQL

4. Install NPM dependencies

If you haven't already, clone the repository, then cd to the main folder of the project and run:

npm config set engine-strict true
npm install

5. Start the application

grails run-app

This will start the application in development mode using an internal Tomcat instance. This will also build all the remaining dependencies for the project. You may need to run the grails compile command beforehand, or run grails run-app several times in order to download all dependencies.

6. Log into OpenBoxes

Navigate to http://localhost:8080/openboxes and log in as an admin using the default credentials (username: admin and password: password). From there, you can create further accounts as needed.

Tips and tricks

Disable Background Jobs

There are many different background jobs that are periodically executed while the application server is running. Some of the jobs are ran every minute. This is slow, and can be quite resource intensive, so unless you need a job to be running, we recommend that you disable them when running the app locally.

To disable the jobs, add the following to your openboxes.yml:

# This stops the background jobs from running on app startup,
# which is very resource intensive and slow.
openboxes:
  refreshAnalyticsDataOnStartup:
    enabled: false

  jobs:
    sendStockAlertsJob:
      enabled: false
    refreshInventorySnapshotJob:
      enabled: false
    refreshInventorySnapshotAfterTransactionJob:
      enabled: false
    refreshOrderSummaryJob:
      enabled: false
    refreshTransactionFactJob:
      enabled: false
    refreshStockoutDataJob:
      enabled: false
    refreshDemandDataJob:
      enabled: false
    assignIdentifierJob:
      enabled: false
    calculateHistoricalQuantityJob:
      enabled: false
    dataCleaningJob:
      enabled: false
    dataMigrationJob:
      enabled: false
    updateExchangeRatesJob:
      enabled: false

Enable React Hot-Reloading

If you're doing development on the React frontend, you'll likely find it useful to run the frontend in hot-swap mode.

In addition to running the regular application server (via the grails run-app command) run the following command in a separate command-line process:

npm run watch

This will cause the fronted to rebuild itself automatically after any code change that you make. All you need to do is refresh the browser window to see the changes take effect. Without this line, you'd need to restart your server to have any React changes take effect.

In addition to this, now that you're building the frontend NPM dependencies yourself, you can comment out any lines in the build.gradle file that contain dependsOn 'npm_run_bundle'. This allows the backend to start much faster since it prevents it from also rebuilding the NPM depedencies.