Run docker-compose (and all services of BioMAJ with it):

docker-compose up -d

Do not forget to install BioMAJ client:

pip install biomaj-cli

Create an .env file:

You will need to create an .env file in the biomaj-docker directory (where the docker-compose.yml is located):

echo "BIOMAJ_DIR=/<path to>/biomaj-docker/" > .env
echo "BIOMAJ_DATA_DIR=/<path to>/<data>/" >> .env #path to biomaj directories (db, log, cache, conf)
echo "BIOMAJ_USER_PASSWORD=biomaj_user_default_password  >> .env
echo "DOCKER_URL=tcp://x.y.z:2375" >> .env  # if you wish to execute processes in Docker containers, give the IP of the host where docker is running (or swarm)

It is possible to override environment variables (and to override variables in the same way), for example to send mails with the microservice version of BioMAJ:

echo "BIOMAJ_MAIL_SMTP_HOST=<xx>" >> .env
echo "BIOMAJ_MAIL_ADMIN=<xx>" >>.env
echo "BIOMAJ_MAIL_FROM=<xx>" >> .env


 When you execute a container, you will find all directories under : /var/lib/biomaj/
 Do not forget to place all your new files in the BIOMAJ_DATA_DIR/conf


How to modify and use your own with docker ?


You can check the contents of the file used directly in a container: cat /etc/biomaj/



Create a user for BioMAJ:

Run the user container in interactive mode:

docker exec -it <name of the biomaj-user-web container> /bin/bash

 How to know the name of every container?

docker ps


In the user container, create a user:

 python3 biomaj-user/bin/ -A create -U biomaj -P biomajmdp

It will give you an apikey for your user:

| User   | Password   | API Key    |
| biomaj | biomajmdp  | M1A15AAER5 |


Run an update --proxy http://biomaj-public-proxy --api-key XYZ --update --bank alu

For microservices deploiement, you have to use the IP of your host machine and the biomaj-public-proxy port, example:




How to get the status of a bank? --proxy --api-key M1A15AAER5 --status --bank alu 
| Name   | Type(s)         | Last update status   | Published release   |
| alu    | nucleic_protein | 2017-06-12 14:22:17  | 2003-11-26          |
| Session             | Remote release   | Release    | Directory                                                 | Freeze   |
| 2017-06-12 14:22:17 | 2003-11-26       | 2003-11-26 | /var/lib/biomaj/data/db/ncbi/blast/alu_ori/alu_2003-11-26 | no       |


How to create a specific process instance?

To preinstall software for process handlers, or mount local system dir containing some tools, one can extend/replace the existing Docker container.

FROM osallou/biomaj-docker
RUN apt-get install …
#docker build -t my/biomaj-process .

Create a new Dockerfile, installing biomaj-process python package and files/directories as specified here.

More information here.


How to simplify tools installation with Conda?

Conda is a package management and work environment management system. It makes it easier to install tools/software, especially in bioinformatics. Many tools are available on bioconda (

Conda is installed directly with biomaj-docker.

A python script (available here with its wrapper) allows the installation of your package(s) of interest via the biomaj post process. You just have to :

  • Add a special block (in your file: example here) to install your package(s) of interest
  • Download the conda wrapper in biomaj/process
  • Download the python script in biomaj/process
  • Give them the execution permissions chmod 755 biomaj/process/*
### Post Process ###
####################  The files should be located in the projectfiles/process directory.

META0=conda +
conda.args=blast $processdir/packageblast.txt $processdir
makeblastdb.desc=Index blast
makeblastdb.args="flat/swissprot" "blast/" "-dbtype prot" "swissprot"


How to specify the packages to install?

Create the <list>.txt with all the conda packages you want to install (version number are available on bioconda for example here), and place it in your biomaj/process directory:


Then complete the conda.args line of your file with your environment name and the name of your <list>.txt file.

conda.args=<environment name> $processdir/<liste of packages>.txt $processdir


How to use your conda environment?

In your post process script, do not forget to activate your environment (in our example, the file):

source activate blast

Do not forget to disable your environment at the end of your script:


To delete your environment:

rm -r <path to processes>/process/blast


Advanced configuration (metrics, monitoring, administration …)