In this section, you will be guided step by step to run the application locally.
-------
# Instructions
## 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.
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, but we would recommand to use environment variables for this purpose.
Now let's go through the different parts of the `backend/.env.sample` file.
### 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
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.
#### 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
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
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
```
> The default port for postgresql 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_PORT` to 5433 when you want to run the backend out of the docker environment.
### Other variables
Name | description
---- | -----------
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
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
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).
Once identify, you can log to the container:
```bash
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
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.
However, most of the commands should not work because the database is accessible through the port localhost:5433 on the local network and not postgresql:5432 as defined in your `.env`. So you need to update these environment variable in your local environment. For instance, if you are using [Visual Studio Code](https://code.visualstudio.com/), you can customize your `.vscode/settings.json` file and add:
```json
"terminal.integrated.env.osx": {
"DATABASE_HOST": "localhost",
"DATABASE_PORT": "5433",
}
```
> 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.
### 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
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>`.
