Skip to content

Changes

Page history
add markdown extension to _sidebar authored by Kenzo-Hugo Hillion's avatar Kenzo-Hugo Hillion
Hide whitespace changes
Inline Side-by-side
Run-the-project-on-your-local-machine.md
View page @ 529a5f76
......@@ -4,9 +4,7 @@ In this section, you will be guided step by step to run the application locally.
-------
# Instructions
## Dependencies
# Dependencies
The application depends on different services that run independently on docker images. All of this is
orchestrated by `docker-compose` on your local machine and Kubernetes on the [development](https://metagenedb-dev.pasteur.cloud) and [production](https://metagenedd.pasteur.cloud) environments.
......@@ -16,7 +14,7 @@ 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/)
## Environment variables
# Environment variables
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.
......@@ -25,12 +23,12 @@ The settings of the Django server is based on the `backend/.env` file. You can c
Now let's go through the different parts of the `backend/.env.sample` file.
### Secret key
## 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.
### Postgresql
## Postgresql
The following variables have the default values:
......@@ -48,7 +46,7 @@ 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.
#### Create your own DB on postgresql
### Create your own DB on postgresql
```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
......@@ -89,7 +87,7 @@ DATABASE_PORT=5432
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_PORT` to 5433 when you want to run the backend out of the docker environment.
### Other variables
## Other variables
Name | description
---- | -----------
......@@ -97,11 +95,41 @@ DEBUG | Set Django in DEBUG Mode or not (`True` or `False`)
PORT | Django port to expose
DB_LOG_LEVEL | Log level for the DB (`ERROR`, `WARNING`, `INFO` or `DEBUG`). Use `DEBUG` to display all queries to the DB
## Run `manage.py` from Django
# Run the whole application
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. You can also use directly `docker-compose build your_service_name` to rebuild an image.
Since directories with source codes are mounted in the containers, changes you make locally should be
directly reflected on the application.
> You can always run the backend independently of docker using the `manage.py` command as described above. It is particularly useful when you use a debugger.
## Populate the database
At start, the database is empty and most of the frontend feature won't work and have nothing to display. Therefore you need to populate your database and you have several options.
### Populate the database with real data
You have a set of scripts available (`catalog` category) that you can list via `manage.py --help`. You can find more information below on how to use `manage.py` and also a description of available scripts on the [wiki page for custom scripts](django-scripts)
### Use a light Test database
One of the script available (`name-to-be-defined`) allow to create a full light database with few genes, functions and taxonomy items. You can run it to rapidly discover the different feature of the app in term of both the backend API, visualization on the frontend and start working on some issues.
> We recommend the use of different database for different purposes since you can easily switch from a db to another using the `.env` file.
# Use `manage.py` from Django
Django comes with built-in scripts that allow different actions such as the creation of a superuser or the migrations of the database ([More information](https://docs.djangoproject.com/en/3.0/ref/django-admin/)). Custome scripts and commands can also be added ([More information](https://docs.djangoproject.com/en/3.0/howto/custom-management-commands/)) and accessible through the `manage.py` command.
### Run on the docker image
## Run on the docker image
You can connect to the running docker image by identifying its `CONTAINER ID` and exec a `bash` terminal in it. (See above to identify the `CONTAINER ID` in the database example).
......@@ -113,7 +141,7 @@ docker exec -it ${CONTAINER_ID} bash
Then from here, you can type `manage.py --help` to list the different available commands. You can start by using `manage.py createsuperuser` command to create an admin user.
### Run on a python virtual environment
## Run on a python virtual environment
Since the backend python environment is managed using [pipenv](https://github.com/pypa/pipenv), you can run a shell in that given environment using `pipenv shell` if you are in the `backend/` directory if you have `pipenv` install on your computer.
......@@ -128,39 +156,11 @@ However, most of the commands should not work because the database is accessible
> Note that you might have to configure other variables (like REDIS_HOST).
----
## Run the application
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. You can also use directly `docker-compose build your_service_name` to rebuild an image.
Since directories with source codes are mounted in the containers, changes you make locally should be
directly reflected on the application.
> You can always run the backend independently of docker using the `manage.py` command as described above. It is particularly useful when you use a debugger.
### Populate the database
At start, the database is empty and most of the frontend feature won't work and have nothing to display. Therefore you need to populate your database and you have several options.
#### Populate the database with real data
You have a set of scripts available (`catalog` category) that you can list via `manage.py --help` and also listed on this [wiki page](django-scripts)
#### Use a light Test database
One of the script available (`name-to-be-defined`) allow to create a full light database with few genes, functions and taxonomy items. You can run it to rapidly discover the different feature of the app in term of both the backend API, visualization on the frontend and start working on some issues.
> We recommend the use of different database for different purposes since you can easily switch from a db to another using the `.env` file.
## Pre-computed statistics
### Pre-computed statistics
> *@TODO this part needs to be moved*
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>`.
\ No newline at end of file