Deploying Chanjo2 using Docker

The Dockerfile provided in the chanjo2 repository can be built and runned to deploy the software. Alternatively an image containing chanjo2 and all its dependencies is hosted on Docker Hub.

Launching a demo using Docker

The file named Dockerfile is a generic Docker file to run the application. Whenever the app is launched with the ENV param DEMO (check the settings present in file docker-compose.yml) it will create a test SQLite database to work with.

To start the demo via docker, run:

docker run -d --rm  -p 8000:8000 --expose 8000 clinicalgenomics/chanjo2:latest

The endpoints of the app will be now reachable from any web browser: http://0.0.0.0:8000/docs or http://localhost:8000/docs

Launching the app connected to a MySQL database via docker-compose

An example of this setup is provided in the docker-compose-mysql.yml file. Here we connect the app to a MySQL (MariaDB) and provide the connection settings to use it.

Note that a file containing environmnent variables is required to run this setup. The template.env file offers an example of the required variables and can be customised according to your local settings.

To check the configuration (env variables passed to the docker-compose file) run:

docker-compose -f docker-compose-mysql.yml --env-file template.env config

The docker-compose file contains 2 services: - MariaDB database, runned from a Docker file that includes the script to create an empty testdb database - The chanjo2 web app, a REST API

To start the demo, run:

docker-compose -f docker-compose-mysql.yml --env-file template.env up

The endpoints of the app will be now reachable from any web browser: http://0.0.0.0:8000/docs or http://localhost:8000/docs

Production settings and .env file

Keep in mind that Chanjo2 reads the variables necessary for connecting to the database from a default .env file. If you run a dockerized version of Chanjo2 and want to connect to a real database, you'll need to replace the default .env file with a custom environment file containing the correct settings to connect to your MySQL database. The last line present on the .env file (DEMO=Y) should be removed or commented out.

Given a local database running on localhost and port 3306, a custom .env file like this:

MYSQL_USER=dbUser
MYSQL_PASSWORD=dbPassword
MYSQL_DATABASE_NAME=chanjo2_test
MYSQL_HOST_NAME=host.docker.internal
MYSQL_PORT=3306

Should suffice to override the parameters present in the default .env file of Chanjo2:

docker run -d --rm -v $(pwd)/.env:/home/worker/app/.env  -p 8000:8000 --expose 8000 clinicalgenomics/chanjo2:latest

Customising the coverage levels used to create coverage reports and genes overview reports

When generating coverage and genes overview reports, the metrics showcased in these documents are calculated across various coverage levels, such as 10x, 20x, and 50x. These specific coverage levels can be directly specified in queries to the /report and /overview endpoints using the completeness_thresholds parameter, which accepts a list of integers. For detailed instructions, please refer to the coverage-reports documentation. Alternatively, you can define these coverage levels in the .env file by adding the following line:

REPORT_COVERAGE_LEVELS=[100,150,,..]

If the REPORT_COVERAGE_LEVELS parameter is not present in the .env file and a request does not include a completeness_thresholds value, the report metrics will default to the following coverage level values: [10, 15, 20, 50, 100].

It's important to note that if coverage level values are provided through multiple methods as described above, the application will prioritize them in the following order:

1. Values specified in the user's request
2. Values included in the .env file
3. Default coverage level values

Furthermore, it's worth considering that the more coverage levels provided, the longer it will take for the report pages to load.