Skip to content
Snippets Groups Projects
Commit fce01755 authored by Kenzo-Hugo Hillion's avatar Kenzo-Hugo Hillion :recycle:
Browse files

empty README and move to wiki pages

parent bd2b1c01
No related branches found
No related tags found
1 merge request!65Dev documentation to run metageneDB locally
Pipeline #33133 passed
...@@ -3,135 +3,15 @@ ...@@ -3,135 +3,15 @@
[![pipeline status](https://gitlab.pasteur.fr/metagenomics/metagenedb/badges/dev/pipeline.svg)](https://gitlab.pasteur.fr/metagenomics/metagenedb/commits/dev) [![pipeline status](https://gitlab.pasteur.fr/metagenomics/metagenedb/badges/dev/pipeline.svg)](https://gitlab.pasteur.fr/metagenomics/metagenedb/commits/dev)
[![coverage report](https://gitlab.pasteur.fr/metagenomics/metagenedb/badges/dev/coverage.svg)](https://gitlab.pasteur.fr/metagenomics/metagenedb/commits/dev) [![coverage report](https://gitlab.pasteur.fr/metagenomics/metagenedb/badges/dev/coverage.svg)](https://gitlab.pasteur.fr/metagenomics/metagenedb/commits/dev)
## The project
The main motivation behind MetageneDB is to provide a support for all the analysis that are based on gene catalogs. The main motivation behind MetageneDB is to provide a support for all the analysis that are based on gene catalogs.
It is composed of both an API and a client side for visualization and interaction with the DB. It is composed of both an API and a client side for visualization and interaction with the DB.
---- * Graphical interface to browse through the catalog
* REST API to programmatically query and retrieve information from the database
## Setup the services on your local machine * (not implemented) Interface to perform analysis from gene counts present on the catalog
### Dependencies
The application depends on different services that run independently on docker images and all of this is
orchestrated by `docker-compose` locally.
Therefore to run the application you need:
* `Docker` : [Install instructions](https://docs.docker.com/install/)
* `Docker Compose` : [Install instructions](https://docs.docker.com/compose/install/)
### Configuration
For `docker-compose`, you need to create a `.env` file: `touch .env`. An example is available: `.env.sample`.
The settings of the Django server is based on the `backend/.env` file. You can copy the sample file
(`cp backend/.env.sample backend/.env`) and fill in the variables.
You can of course customize more of the Django server settings in the `settings` module of metagenedb.
Now we will go through the different parts.
#### Secret key
This is the Django `SECRET_KEY` and you need to specify your own. For instance you can use the command
`openssl rand -base64 32` to generate one by command line.
#### Create your own DB on postgresql
The following variables have the default values:
```bash
DATABASE_HOST=postgresql
DATABASE_USER=postgres
DATABASE_NAME=postgres
DATABASE_PASSWORD=""
DATABASE_PORT=5432
```
It will work if you leave it as it is but you might face security issues having a by default database
without credentials.
What we recommand is to create your own database. Here is described one way to do it. To do that you need to
first run the db image and identify its running ID:
```bash
khillion:~/metagenedb $ docker-compose up postgresql -d # This runs only the postgresql service of your docker-compose in detached mode. You can also detached from you running screen using Ctrl+Z
Creating postgresql ... done
khillion:~/metagenedb $ docker ps # List your running docker images
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
5002f210f9d8 postgres:11.4-alpine "docker-entrypoint.s…" 1 minute ago Up 1 minute 0.0.0.0:5433->5432/tcp postgresql
```
Now that you have the `CONTAINER ID`, here `5002f210f9d8` you can run a `bash` terminal in this container and
create your own database:
```bash
khillion:~/metagenedb $ docker exec -it 5002f210f9d8 bash
bash-5.0# psql --user=postgres
````
This will open the `SQL` console where you can do what you need:
```psql
CREATE ROLE metagenedb WITH PASSWORD 'yourawesomepassword';
ALTER ROLE metagenedb WITH CREATEDB;
CREATE DATABASE metagenedb WITH OWNER metagenedb;
exit
```
Now you have you own database, protected by a password and you need to update your `.env`:
```bash
DATABASE_HOST=postgresql
DATABASE_USER=metagenedb
DATABASE_NAME=metagenedb
DATABASE_PASSWORD=yourawesomepassword
DATABASE_PORT=5432
```
> **Note**: The by default port for postgres is `5432`. In the `docker-compose.yaml` you will notice that this
port is redirected to `5433` on the `localhost`. This is done in order to not interfere with your local
postgres if you have one. This means you need to change `DATABASE_HOST` to `localhost` and `DATABASE_POS
### Pre-computed statistics
Some statistics about genes are pre-computed and can be accessed through the `/api/catalog/v1/statistics` endpoint.
The ID is constructed with the following format: `<statisctics-type>-<gene_source>-<method>-<options>`.
----
## Run the application
For the moment, only the `docker-compose.dev.yaml` is used. To run the application simply run the command:
```bash
docker-compose up --build
```
The `--build` option is only necessary during the first usage or when you make changes that need the docker
container to be built again.
Since directories with source codes are mounted in the containers, changes you make locally should be
directly reflected on the application.
### Populate the database
You have a set of scripts available that you can list via `manage.py --help`.
-----
## Dev tips
#### Profiling code
```python
from metagenedb.common.utils.profiling import profile
@profile("/my/file/path") ## Wiki & Documentation
def my_function(a, b, c):
...
```
```bash For more information, please have a look at our [Wiki](https://gitlab.pasteur.fr/metagenomics/metagenedb/-/wikis/MetageneDB)
snakeviz /my/file/path
```
...@@ -6,3 +6,4 @@ DATABASE_NAME=postgres ...@@ -6,3 +6,4 @@ DATABASE_NAME=postgres
DATABASE_PASSWORD="" DATABASE_PASSWORD=""
DATABASE_PORT=5432 DATABASE_PORT=5432
SECRET_KEY=YOUR_KEY SECRET_KEY=YOUR_KEY
DB_LOG_LEVEL=INFO
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment