BioPocket Backend

The API for the BioPocket project, implemented with a Node.js Express server.

• Requirements
• Development
  • First-time setup
  • Run the server
  • Upgrade to the latest version
  • Contribute
• Configuration

Requirements

• Node.js 8.x
• PostgreSQL 9+
  • PostGIS 2.2+ extension
  • uuid-ossp extension

Optional development utilities:

• Knex (install with npm install -g knex)

Development

How to set up your machine to contribute to the project.

First-time setup

• Clone this repository:

  git clone https://github.com/MediaComem/biopocket-backend.git
  

• Install the application's dependencies:

  cd biopocket-backend
  npm ci
  

• Create a config/local.js configuration file to customize the database connection URL and other properties (see Configuration):

  cp config/local.sample.js config/local.js
  

• Create a PostgreSQL database consistent with your configuration (a biopocket database on localhost by default). If the user you connect as does not have the necessary privileges to create extensions, you should make sure that the postgis and uuid-ossp extensions are already created in the database:

  psql -c 'CREATE EXTENSION "postgis"; CREATE EXTENSION "uuid-ossp";' biopocket
  

• Migrate the database:

  npm run migrate
  

• Generate sample data:

  npm run sample-data
  

Run the server

• Run the dev npm script:

  npm run dev
  

Upgrade to the latest version

• Update your branch (and resolve any conflicts):

  git pull
  

• Install new application dependencies (if any):

  rm -fr node_modules
  npm ci
  

• Migrate the database (if new migrations were added):

  npm run migrate
  

• Run the server:

  npm run dev
  

Contribute

Read the development guide.

Configuration

The application can be configured through environment variables or a configuration file. Environment variables always take precedence over properties from the configuration file.

Environment variable	Config property	Default	Purpose
$BCRYPT_COST	bcryptCost	10	bcrypt cost parameter (should be at least 10; see bcrypt)
$CONFIG		config/local.js	Path to the local configuration file to load
$CORS	cors.enabled	false	Whether to enable Cross-Origin Request Sharing (CORS)
$CORS_ORIGIN	cors.origin		Comma-delimited whitelist of origins that are allowed to use CORS (setting this enables CORS by default)
$DATABASE_URL	db	postgres://localhost/biopocket	PostgreSQL database URL to connect to
$IMAGES_BASE_URL	imagesBaseUrl		Base URL where theme, action and task images are stored.
$INTERFACE_DATABASE_URL	interfaceDb		PostgreSQL database URL for the data collection interface database (see Synchronization)
$LOG_LEVEL	logLevel	INFO	Log level (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
$NODE_ENV	env	development	Application environment (development or production)
$PORT	port	3000	Port to run the Node.js Express server on
$SESSION_SECRET	sessionSecret		Session secret used to sign JWT tokens (a long random string, e.g. 100 chars)

If the database URL is not specified with $DATABASE_URL or db, you can use these environment variables instead:

Environment variable	Default	Purpose
$DATABASE_HOST	localhost	Host to connect to
$DATABASE_PORT	5432	Port to connect to on the host
$DATABASE_NAME	biopocket	Name of the database to connect to
$DATABASE_USERNAME	none	Name of the PostgreSQL user to connect as
$DATABASE_PASSWORD	none	Password to authenticate with

If the database URL for the data collection interface is not specified with $INTERFACE_DATABASE_URL or interfaceDb, you can use these environment variables instead:

Environment variable	Default	Purpose
$INTERFACE_DATABASE_HOST	localhost	Host to connect to
$INTERFACE_DATABASE_PORT	5432	Port to connect to on the host
$INTERFACE_DATABASE_NAME	biopocket	Name of the database to connect to
$INTERFACE_DATABASE_USERNAME	none	Name of the PostgreSQL user to connect as
$INTERFACE_DATABASE_PASSWORD	none	Password to authenticate with

The following properties can be used in development to customize how the project's documentation is served locally:

Environment variable	Config property	Default	Purpose
$DOCS_BROWSER	docs.browser		Browser to open
$DOCS_HOST	docs.host	127.0.0.1	Host to serve the documentation on
$DOCS_OPEN	docs.open	false	Whether to automatically open the browser with the documentation when running npm run dev or npm run dev:docs
$DOCS_PORT	docs.port		Port to serve the documentation on (a free random port will be found by default)