Note: these are the instructions for installing the BHIMA development environment. If you wish to deploy BHIMA in production, check out our deployment instructions for Digital Ocean.
The BHIMA software can be complex to install. We only officially support Linux, so the following guide assumes you are setting up BHIMA on Debian-based Linux environment.
This guide will get you up and running with bhima locally. Please note that bhima is under active development and tends to move fast and break things. If you are interested in development progress, shoot us a line at email@example.com.
Before you begin the installation process, please make sure you have all the bhima dependencies installed locally. We only test on Linux, so your best bet is to use a Linux flavor you are familiar with. Please make sure you have recent version of:
#Run the following command to update the package lists: sudo apt-get update #Install MySQL with the following command: sudo apt-get install mysql-server #Run the following commands to install Redis: sudo apt-get install redis-server #Run the following commands to install curl: sudo apt-get install curl #Install node version manager locally curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash #Set up the environmental variables for node version manager export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \."$NVM_DIR\nvm.sh" # This loads nvm #Download NodeJS latest long-term version nvm install lts/* #Installs yarn without re-installing NodeJS curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list sudo apt-get update && sudo apt-get install yarn --no-install-recommends #Run the following command to install git: sudo apt-get install git
By default, your OS might not have all dependencies for running puppeteer, the PDF renderer based based on Chromium. These vary by OS. For Ubuntu/Debian, you can run the following to prepare your environment:
# Install puppeteer dependencies on Ubuntu sudo apt-get install ca-certificates fonts-liberation gconf-service \ libappindicator1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 \ libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libgconf-2-4 \ libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 \ libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \ libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 \ libxss1 libxtst6 lsb-release libxshmfence1 wget -y
For more information on other operating systems, see the puppeteer troubleshooting documentation.
Clone the source using git from the github repository using the following commands:
git clone https://github.com/IMA-WorldHealth/bhima.git bhima cd bhima
All our build scripts are found the
package.json file. We use gulpjs internally, but you shouldn’t ever need to call gulp explicitly.
To execute the build scripts, you can use either
npm. We’ll use
yarn for the remainder of this guide. Note that using
npm may require you to use
npm run where it says
# Inside the bhima/ directory # install all node modules yarn install #If this command gives you an error (I.E. if you’re running Parallels), try running the following command: git config -global url."https://".insteadOf git://
The dependencies should now be set!
BHIMA uses environmental variables to connect to the database and toggle features. These are found in the
.env.sample file included in the top level of the repository. You’ll need to set these in a
.env file to be read by the application at runtime.
Before building, create your
.env file based on the sample template to set up your MySQL database connection parameters. Their variables should be self-explanatory.
Use the following command to edit the .env file if desired (make your changes and then type ctrl + x to exit and save):
cp .env.sample .env nano .env
#Run the following commands to create the bhima user in MySQL, so that it can build the database (make sure the user and #password both match what you set in the .env file): sudo mysql -u root -p CREATE USER 'bhima'@'localhost' IDENTIFIED WITH 'mysql_native_password' BY 'password'; GRANT ALL PRIVILEGES ON * . * TO 'bhima'@'localhost'; #Use ctrl + z to get back to the main terminal prompt
Then, build the app with
# build the application NODE_ENV="development" yarn build
NOTE: BHIMA runs in
sql_mode="STRICT_ALL_TABLES,NO_UNSIGNED_SUBTRACTION". While it is not necessary to have this set to build the database, the tests will not pass unless the correct SQL_MODE is set.
#To configure MySQL with this setting, run the following commands: sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf #Under the section [mysqld], add in the following text: sql-mode = "STRICT_ALL_TABLES,NO_UNSIGNED_SUBTRACTION" # save and quit, then restart mysql with the following command: sudo service mysql restart
To start a MySQL server using docker you can use:
# in this example, we use "mysql" as the tag name docker run --name mysql -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=MyPassword \ -e MYSQL_ROOT_HOST=% \ -d mysql/mysql-server:8.0 \ --sql-mode='STRICT_ALL_TABLES,NO_UNSIGNED_SUBTRACTION' \ --default-authentication-plugin=mysql_native_password # give it a few seconds, and MySQL will be started and listening on port 3306
This will start a MySQL server that listens on port 3306 (the default MySQL port) on your localhost. Additionally, you have to set
DB_HOST in the
.env file to
127.0.0.1, leaving it to
localhost will make the
mysql command trying to connect via socket, what is not possible when using docker.
If you have already a MySQL server running on port 3306 of your localhost, start docker without the port-forwarding (
-p 3306:3306), use
docker inspect mysql5.7 to find the IP of the container and use that IP in the
.env file as
The database structure is contained in the
server/models/*.sql files. You can execute these one by one in the order below, or simply run
This sets up the basic schema, routines, and triggers. The following scripts will build a basic dataset to begin playing around with:
You can run all this by using the following command:
yarn build:db Alternatively, you might use the
./sh/build-database.sh script, customized with your environmental variables as shown below:
# install the database DB_USER='me' DB_PASS='MyPassword' DB_NAME='bhima' ./sh/build-database.sh
Running the application is super easy! Just type
yarn dev in the application root directory.
If you changed the
$PORT variable in the
.env file, your application will be listening on that port. By default it is
Navigate to http://localhost:8080 in the browser to verify the installation. You should be greeted with a login page.
Our tests are broken into unit tests, end to end tests, and integration tests. There is more information on testing in the wiki.
webdriver-managerwhich is installed automatically as one of its dependencies. See their documentation for more information. To run the tests, first get the newest version of selenium, chrome and the chromedriver with
yarn webdriver-manager updateand then run the tests with
You can run all tests by simply typing
Enjoy using bhima!