ICUBAM can be used by either installing it natively or using docker. To use docker see following section).


This explains how to run a local instance of icubam on a developer’s machine. We use conda, but you might choose virtualenv.


  • create a conda environment (e.g. conda create -n icubam python=3.8)
  • activate the environment (conda activate icubam)
  • install deps with pip install -r requirements.txt
  • install the package in edit mode by running pip install -e .

Note: in addition to the python dependencies described in requirements.txt, icubam requires SQLite >= 3.24.0 as it uses upsert statements.


Create a resources/icubam.env file containing the following keys:

GOOGLE_API_KEY=a google maps api key

N.B.: You can name and move this file as you want but you will have to add --dotenv_path=path/to/my_icubam.env to the scripts when launching them.

Pre-populate DB with test data

Create a fake database in order to be able to play with it: python scripts/ --config=resources/config.toml

The database will be named test.db, cf. resources/config.toml.

Running unit tests

To run unit tests, see the contributing section.

Running locally

User id

Get one user identifier: python scripts/

This very long identifier will be required to access the main server.

To get all identifiers: python scripts/ --all

Main server

Start the main server locally: python scripts/ --config=resources/config.toml

Will produce the following logs:

I0324 19:02:15.784908 139983874058048] UpdateHandler serving on /update
I0324 19:02:15.785018 139983874058048] HomeHandler serving on /
I0324 19:02:15.785090 139983874058048] Running WWWServer on port 8888
I0324 19:02:15.788751 139983874058048] http://localhost:8888/update?id=<A_VERY_LONG_ID>

Follow the proposed link http://localhost:8888/update?id=<A_VERY_LONG_ID>

Backoffice server

Start the backoffice server locally,

python scripts/ --server=backoffice

Then open backoffice at http://localhost:8890/bo/ (cf. root value in resources/config.toml) and login with user credentials created by the script,

  • user:
  • password: password