Skip to main content
Version: 2.x

Quick Start

To start a new task locally, in development mode follow these steps:

1. Start your new task from our template repository​

The simplest way to get started is creating a new repository using Honeycomb as a template.

Go to https://github.com/brown-ccv/honeycomb and click on Use this template on the top right. Then select the organization and the name of your repository and click on create repository from template

Alternatively, you can use GitHub CLI to create a new project based on the Honeycomb template repository. First, install GitHub CLI (https://cli.github.com/), then simply run on your terminal:

gh repo create your-new-task-name --template brown-ccv/honeycomb

You can now move into the directory that was just created

cd your-new-task-name

2. Change name and description​

Update the package.json fields to reflect your app name and description, e.g. name, author, repository

3. Install the dependencies.​

Electron Dependencies Honeycomb relies on Electron to package the cross-platform desktop applications. Before starting, you will need to install Electron's pre-requisites below. You can find the full instructions on the electron documentation for your specific OS.

Windows​

  • Visual Studio: Install the latest version of Visual Studio with the Desktop Development for C++ Workflow. To add the workflow, follow these instructions.

  • Node.js: Install Node.js

  • Git bash (Git 2.20.0 or later with support for "--show-current"): Install git bash

Note: restart computer after all installs are complete​

MacOS​

  • Command Line Tools: Type in the terminal
xcode-select --install

Linux​

  • Node.js: Dowload Node.js source code and compile it:

  • Git 2.20.0 or later (with support for "--show-current"): Install git

  • Python 3.7 or later (with support for TLS 1.2): Install Python

  • Clang: Install Clang or follow installation instructions on the electron docs

  • Development headers of GTK 3 and libnotify: Follow installation instructions on the electron docs

Honeycomb npm packages Once Node.js is installed you will able to use npm commands in the terminal. To install the dependencies for HoneyComb run the following command at the terminal (remember you need cd your-new-task-name before)

npm install

4. Run the task in dev mode​

To launch an electron window with the task with the inspector open to the console and will hot-reload when changes are made to the app

  • For Mac and Linux:

    npm run dev

  • For Windows: You will need to open 2 terminals. In the first -and make sure you are in the task-<TASK NAME> repo directory- run the command:

    npm start

    In the second terminal - make sure you are in the task-<TASK NAME> repo directory-, run:

    npm run electron-dev

5. Run the task with preset environment variables​

We have provided various .env files and npm scripts to run the task in common settings like home or clinic. Here are the possible commands:

npm run dev:home
npm run dev:home:video
npm run dev:clinic
npm run dev:clinic:video
npm run dev:firebase

6. Check out the data​

The data is saved throughout the task to the users's app directory. This is logged at the beginning of the task wherever you ran npm run dev (for windows, instead in two different terminals ran npm start and npm run electron-dev). It is also stored in a folder that is generated by the app, which should be found on the desktop.

7. Quit The Task​

If you want to quit in the middle of the task, you can use these keyboard shortcuts:

Ctrl+W (for PC/Windows)
Cmd+Q (for Mac)

Partial data will be saved.

7. Merge updates from honeycomb template repo​

Honeycomb is an active project, and will be updated with new features over time. To merge the honeycomb template repository updates with your task, follow the following steps: First time only:

git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

Every time:

git fetch --all
git merge honeycomb/main --allow-unrelated histories

If there are any conflicts:

git stash

To merge:

git commit -a -m "merge honeycomb latest"

8. Run automated tests​

When getting started, merging updates, or making custom changes, it's a good idea to run automated tests. These can tell you if things are working or if recent changes broke something that previously worked.

To run the tests interactively:

npm test

Or non-interactively:

CI=true npm test

Linux​

When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runer creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

This is a "known issue" with some test runners on Linux, as in discussions here and here.

One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

  • Command that initially fails with ENOSPC: npm test
  • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
  • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
  • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
  • Save, exit, and reload the config file: sudo sysctl -p
  • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
  • Retry the initial command, which should now succeed: npm test