Commit 110bcc8c authored by Florent Chehab's avatar Florent Chehab

Updated the whole documentation

Added some comments accross specific files
parent 0635ec1c
Pipeline #34895 passed with stages
in 3 minutes and 8 seconds
...@@ -25,10 +25,13 @@ build_frontend: ...@@ -25,10 +25,13 @@ build_frontend:
docker-compose exec frontend sh -c "cd frontend && npm run build" docker-compose exec frontend sh -c "cd frontend && npm run build"
shell_backend: shell_backend:
docker-compose exec backend sh docker-compose exec backend sh -c "cd backend && bash"
shell_frontend: shell_frontend:
docker-compose exec frontend sh docker-compose exec frontend sh -c "cd frontend && sh"
django_shell:
docker-compose exec backend sh -c "cd backend && ./manage.py shell"
documentation: documentation:
cd documentation && $(MAKE) all cd documentation && $(MAKE) all
......
1. It's still a work in progress # Rex-DRI
1. Collaborations are welcomed
1. The documentation is not up-to-date for now, don't mind asking questions if you have issues running the project. *A revolution is on its way... :airplane: (it's still a work in progress).*
## Documentation
**The project documentation is available [here](https://rex-dri.gitlab.utc.fr/rex-dri/documentation/).**
## Notes
**Collaborators and PR are highly welcomed!**
Feel free to ask questions about the project using the issue system.
**Retrouvez la documentation [ici](https://rex-dri.gitlab.utc.fr/rex-dri/documentation/).**
# pull official base image # This image is based on a python image.
# Use of stretch instead of Alpine for faster install of python packages (especially pandas) # Use of stretch instead of Alpine for faster install of python packages (especially pandas)
# Overall performance might be slightly better (with bigger image size obviously) # Overall performance might be slightly better dut to the use of different lib (but with bigger image size obviously)
FROM python:3.7.2-slim-stretch FROM python:3.7.2-slim-stretch
# set work directory # set work directory
WORKDIR /usr/src/app WORKDIR /usr/src/app
# runtime dependencies # server dependencies
# libpq-dev and gcc is for psycopg2-binary # python3-dev, libpq-dev and gcc is for psycopg2-binary
RUN apt-get update && apt-get install -y --no-install-recommends \ RUN apt-get update && apt-get install -y --no-install-recommends \
libpq-dev \ libpq-dev \
python3-dev \ python3-dev \
...@@ -16,7 +17,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ ...@@ -16,7 +17,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
&& rm -rf /var/lib/apt/lists/* && rm -rf /var/lib/apt/lists/*
# install dependencies # python dependencies
RUN pip install --upgrade pip RUN pip install --upgrade pip
COPY requirements.txt /usr/src/app/requirements.txt COPY requirements.txt /usr/src/app/requirements.txt
RUN pip install -r requirements.txt RUN pip install -r requirements.txt
# Main docker-compose file for the project to coordinate all the docker related stuff.
# To build from local image, use the `build: ...` attibute and not the `image` attribute.
version: '3.7' version: '3.7'
services: services:
# Service for the backend app.
backend: backend:
# Get the image from the registry
image: registry.gitlab.utc.fr/rex-dri/rex-dri/backend:latest image: registry.gitlab.utc.fr/rex-dri/rex-dri/backend:latest
# To use a locally build one, comment above, uncomment bellow.
# build: ./backend # build: ./backend
volumes: volumes:
# "Copy" the repo to the workdir.
- .:/usr/src/app/ - .:/usr/src/app/
ports: ports:
- 8000:8000 # Replicate the python server port # Replicate the python server port
- 8000:8000
environment: environment:
# Add environment variables
- ENV=DEV - ENV=DEV
- SECRET_KEY=please_change_me - SECRET_KEY=please_change_me # Django secret key
# Django admin user param
- DJANGO_ADMIN_USERNAME=admin - DJANGO_ADMIN_USERNAME=admin
- DJANGO_ADMIN_PASSWORD=admin - DJANGO_ADMIN_PASSWORD=admin
# DB parameters
- DB_HOST=database - DB_HOST=database
- DB_PORT=5432 - DB_PORT=5432
- POSTGRES_DB=postgres - POSTGRES_DB=postgres
- POSTGRES_USER=postgres - POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres - POSTGRES_PASSWORD=postgres
# Run the django developpement server on image startup.
command: /bin/sh -c "cd backend && ./manage.py runserver 0.0.0.0:8000" command: /bin/sh -c "cd backend && ./manage.py runserver 0.0.0.0:8000"
depends_on: depends_on:
# Required that the `database` service is up and running.
- database - database
# Service for the postgres database
database: database:
# Use of classic image
image: postgres:10.5-alpine image: postgres:10.5-alpine
environment: environment:
# Set up the postgres ID
- POSTGRES_DB=postgres - POSTGRES_DB=postgres
- POSTGRES_USER=postgres - POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres - POSTGRES_PASSWORD=postgres
volumes: volumes:
# Add a volume to store the DB data.
- postgres_data:/var/lib/postgresql/data/ - postgres_data:/var/lib/postgresql/data/
# Service to handle frontend live developpments and building
frontend: frontend:
# Build image from Dockerfile
build: ./frontend build: ./frontend
# On startup, start the developpement server
command: /bin/sh -c "cd frontend && npm i --verbose && npm run dev" command: /bin/sh -c "cd frontend && npm i --verbose && npm run dev"
volumes: volumes:
# "Copy" the repo to the workdir.
- .:/usr/src/app/ - .:/usr/src/app/
ports: ports:
- 3000:3000 # Replicate the node server port # Replicate the node server port. More info in ./frontend/server.js
- 3000:3000
documentation: documentation:
build: ./documentation build: ./documentation
volumes: volumes:
- ./documentation:/usr/src/app - ./documentation:/usr/src/app
# Start a simple python folder
command: /bin/sh -c "python -m http.server 5000" command: /bin/sh -c "python -m http.server 5000"
ports: ports:
# replicate the server port
- "5000:5000" - "5000:5000"
volumes: volumes:
# Create some local volume (should be stored in some directory on your computer)
postgres_data: postgres_data:
API API
======== ========
## Accès ## Location
L'API du site est accessible à l'adresse `/api`. The backend `Django` app, with `Django Rest Framework` acts as an API. It is available at the URI `/api`.
La documentation de l'API est accessible à l'adresse `/api-docs`. An automated documentation is generated and available at the URI `/api-docs`.
## Authentification ## Authentication
Il existe deux modes d'authentification pour l'API. Two authentication protocol are currently available and both lead to API response according to the rights of the corresponding user.
Dans les deux cas, les réponses de l'API dépendront des droits associés à l'utilisateur.
### Session ### Session
Il s'agit du mode d'authentification automatiquement utilisé lorsque vous naviguez sur le site. This is the default mode used once you are connected with the `CAS` by going to the URI `/user/login`.
Il faut s'être connecté au CAS avant : `/user/login`.
### Token ### Token
Dans de rares cas, un token unique peut être associé à un utilisateur. Dans ce cas, la seule présence de ce token dans la requête est suffisant pour l'authentification. Exemple : A token may be associated with a user through the Django admin (`/admin`). To use it you could do:
```bash ```bash
curl -X GET http://127.0.0.1:8000/api/country/ -H 'Authorization: Token MonTokenRandomSuperLong' curl -X GET http://127.0.0.1:8000/api/country/ -H 'Authorization: Token MyTokenRandomSuperLong'
``` ```
La génération du token se fait dans l'administration du site pour l'instant : `/admin`.
# pull official base image # Very basic Dockerfile that simply pull a python image to run a pyton server.
# Pull official base image
FROM python:3.7.2-alpine3.9 FROM python:3.7.2-alpine3.9
# Set-up a workdir so that it can be mapped to a volume in docker-compose.
WORKDIR /usr/src/app WORKDIR /usr/src/app
Présentation Introduction
======= =======
Bienvenue sur la documentation du projet **`Outgoing`**. Il s'agit d'une plateforme de capitalisation concernant les départs à l'étranger à l'Université de Technologie de Compiègne. Welcome on the `Rex-DRI` documentation.
!> Ce service fonctionne avec `Python 3.6`, `Django 2.0` et `PostgreSQL`. `Rex-DRI` is a plateforme to capitalize on international exchange that outbound *Université de Technologie de Compiègne, France*.
!> This app makes use notably of `Docker`, `Python`, `Django`, `Js`, `React` and `PostgreSQL`.
If you are not familiar with these technologies, have no worries! 😊 You can find very good resources online. For instance:
- Django: [a good tutorial in French](https://tutorial.djangogirls.org/fr/django_start_project/);
- *More to come...*
<!-- docs/_sidebar.md --> <!-- docs/_sidebar.md -->
* [Présentation](/) * [Introduction](/)
* [Installation](installation.md) * [Set-up](set-up.md)
* [Chargement des données](load.md) * [Use of `Docker`](docker.md)
* [Initializing data](init_data.md)
* [Architecture](architecture.md) * [Architecture](architecture.md)
* [Tags](tafs.md) * [Tags](tags.md)
* [API](API.md) * [API](API.md)
* [À propos de cette documentation](this_doc.md) * [About this documentation](this_doc.md)
* [Contributions](contributions.md) * [Contributions](contributions.md)
\ No newline at end of file
Architecture Architecture
=============================== ===============================
Présentation de l'architecture du backend. Visualization of the `backend` app architecture.
!> TODO the visualization are currently broken: [https://gitlab.utc.fr/rex-dri/rex-dri/issues/16](https://gitlab.utc.fr/rex-dri/rex-dri/issues/16).
Vue complète : Vue complète :
![Architecture](generated/architecture.svg) ![Architecture](generated/architecture.svg)
...@@ -11,4 +13,4 @@ Vue plus précise : ...@@ -11,4 +13,4 @@ Vue plus précise :
![other_core](generated/core.svg) ![other_core](generated/core.svg)
![AbstractModules](generated/university.svg) ![AbstractModules](generated/university.svg)
![Architecture](generated/location.svg) ![Architecture](generated/location.svg)
![Architecture](generated/user.svg) ![Architecture](generated/user.svg)
\ No newline at end of file
Contributeurs et contributrices :thumbsup: Contributors :thumbsup:
========= =========
- Florent Chehab - Florent Chehab
Use of `Docker`
==============
## General comment
As said in the introduction, this project makes use of `docker` and `docker-compose`. Their are several `Dockerfile` spraid across the project that creates the required `docker` image.
Then the `docker-compose.yml` file coordinates everything: environment variables, ports, volumes, etc.
You can have a look at those files for more comments.
## Use in Gitlab
The `backend` image is also stored on [https://gitlab.utc.fr/rex-dri/rex-dri/container_registry](https://gitlab.utc.fr/rex-dri/rex-dri/container_registry) to be easily used in `Gitlab CI`.
As it seemed not possible to do the same for the `frontend` image due to the fact that the `node_modules` folder couldn't be kept during `CI`, the image is basically regenerated in `CI`.
When ran locally, the `npm i` command (installing the `Node` dependencies) is run everytime with `make up` to make sure your `node_modules` folder is up to date.
## Updating the image on Gitlab
If you are not connected to the registry yet, do it:
```bash
docker login registry.gitlab.utc.fr
```
To update the images stored on the Gitlab repository, run for instance:
```bash
docker build ./backend --compress --tag registry.gitlab.utc.fr/rex-dri/rex-dri/backend:latest
```
And push it:
```bash
docker push registry.gitlab.utc.fr/rex-dri/rex-dri/backend:latest
```
## Updating the images from Gitlab
To do so, run `make docker-pull`.
## Issues with `__pycache__`
If you have issues at some point with `__pycache__` files, you can delete them:
```bash
find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | sudo xargs rm -rf
```
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1"> <meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8"> <meta charset="UTF-8">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css"> <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
</head> </head>
<body> <body>
...@@ -17,10 +17,10 @@ ...@@ -17,10 +17,10 @@
loadSidebar: true, loadSidebar: true,
maxLevel: 4, maxLevel: 4,
subMaxLevel: 4, subMaxLevel: 4,
name: 'Outgoing', name: 'Rex-DRI',
search: { search: {
placeholder: 'Recherche...', placeholder: 'Search for...',
noData: 'Pas de résultat :(', noData: 'No result :(',
paths: ['/installation'] paths: ['/installation']
}, },
} }
...@@ -33,4 +33,4 @@ ...@@ -33,4 +33,4 @@
<script src="//unpkg.com/prismjs/components/prism-sql.min.js"></script> <script src="//unpkg.com/prismjs/components/prism-sql.min.js"></script>
</body> </body>
</html> </html>
\ No newline at end of file
Loading initial/example data into the app
=====
To load some basic data in the app, you can use the python classes: `loadCountries`, `loadUniversities`, etc. available in `backend/backend_app/load_data/loading_scripts`.
You can load everything in one command by connecting to the `Django` shell:
```bash
make django_shell
```
And running:
```python
from backend_app.load_data import load_all
load_all()
```
*NB: Those scripts are tested so they should work.*
By doing so, an admin user is created according to the environment variables `DJANGO_ADMIN_USERNAME` and `DJANGO_ADMIN_PASSWORD` that are set (in our case) in the `docker-compose` file.
Installation
=======
## Locale
Petit guide pour installer proprement cette application `django` et pouvoir contribuer.
### Base de données
L'application est « agnostique » au type de base de donnée employée. Alors qu'il fallait au départ forcément PostgreSQL pour tirer partie des fonctionnalités de stockage des documents JSON, ils sont
aujourd'hui stockés sous forme de texte car aucune requête n'aurait besoin de les parcourir ; ainsi, seul des champs par défaut de django sont employés.
#### SQlite
Pour utiliser SQlite comme SGBD, il suffit de commenter le bloc qui concerne Postgresql dans le fichier de configuration visible ici : `./backend/general_app/settings/development.py` :
```python
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'outgoing',
'USER': 'outgoing',
'PASSWORD': 'outgoing',
'HOST': '127.0.0.1',
'PORT': '5432',
}
}
```
et de décommenter celui-ci :
```python
## Sqlite
# PROJECT_DIR = os.path.abspath(os.path.dirname(__file__))
# DATABASES = {
# 'default': {
# 'ENGINE': 'django.db.backends.sqlite3',
# 'NAME': os.path.join(PROJECT_DIR, '../database.db'),
# }
# }
```
La base de donnée sera alors stockée à la racine du projet dans le fichier `database.db`.
Si vous avez choisi cette option, vous pouvez sauter la partie sur postgreSQL.
#### postgreSQL
##### Installation
L'installation de `postgreSQL` est un plus gros challenge. Pour ce faire, utiliser ~~Google~~ DuckDuckGo.
Vous devez faire en sorte que `postgreSQL` soit accessible en local, c'est suffisant :
- Dans le fichier `postgresql.conf` (disponible en standard sous linux dans le dossier `/var/lib/pgsql/data/` après installation), décommentez/modifiez les lignes :
```conf
listen_addresses = 'localhost'
port = 5432
```
- Dans le fichier `pg_hba.conf` (disponible en standard sous linux dans le dossier `/var/lib/pgsql/data/` après installation), ajoutée la ligne :
```conf
host all all 127.0.0.1/32 trust
```
**Penser à relancer `postgreSQL` après ces changements _- et profitez-en pour activer le lancement automatique au démarrage si vous le souhaitez_.**
**Les contributions sont les bienvenues pour compléter cette partie d'installation/configuration de base.**
##### Initialisation
Pour un fonctionnement simplifié avec ce projet il faut procéder aux changement suivants.
```bash
su - postgres
```
_(Si vous avez un problème de mot de passe, contourner le problème : `sudo su - postgres`)_
Puis ouvrez l'interface en ligne de commande postgres :
```bash
psql
```
Si vous ne voyez pas `postgres=#` c'est qu'il y a un problème, vérifier votre installation.
Créer un utilisateur correspondant à votre utilisateur/login classique dans postgre :
```sql
CREATE USER outgoing;
ALTER USER outgoing WITH PASSWORD 'outgoing';
```
Donner lui le droit de créer des bases de données (utile lors des tests en local) :
```sql
ALTER USER outgoing CREATEDB;
```
Créer une base de données qui lui sera associée :
```sql
CREATE DATABASE outgoing;
GRANT ALL on DATABASE outgoing to outgoing;
```
Sortez de `psql` (`\q`) et retrouver votre utilisateur normal (`CRTL` + `D`).
À ce stade, si vous tappez dans votre console :
```bash
psql -d <login>
```
Vous devez accéder à votre base de données sans soucis.
_Si vous êtes arrivés jusque là, c'est tout bon !_
### virtualenv
Afin d'avoir des environnements reproductibles il est **fortement** suggéré d'utiliser un environnement virtuel pour ce projet.
(Ce projet est développé sur `python-3.6`)
```bash
python3.6 -m venv ./env
```
Cet environnement virtuel doit être **systématiquement** activé lorsque vous travaillez sur ce projet :
```bash
source ./env/bin/activate
```
Les lignes de votre console doivent alors commencez par `(<nom-du-venv>)`.
_Pour le désactiver, faîtes : `deactivate`_.
### git
Il ne vous reste plus qu'à cloner le projet :
```bash
git clone git@gitlab.utc.fr:chehabfl/outgoing_rex.git
cd outgoing_rex
```
(Il va de soit qu'il faut savoir installer/utiliser `git` pour ce projet...)
### C'est parti
Activer votre environnement virtuel (voir plus haut). Puis installer les dépendances :
```bash
pip install -r requirements.txt
```
Téléchargez les dépendances `npm` nécessaires :
```bash
npm i
```
_Migrez_ la base de donnée :
```bash
./manage.py migrate
```
_Initialisez_ les révisions:
```bash
./manage.py createinitialrevisions
```
_NB: cette opération (en plus de `./manage.py makemigrations` et de la précédente) est à faire à chaque fois que vous rajoutez/modifier un model._
_Collectez_ les éléments statistiques :
```bash
./manage.py collectstatic
```
_Checkez_ le système :
```nash
make check_backend
```
```bash
make test_backend
```
Tout ce qu'il y a jusqu'ici **doit** fonctionner. :smile:
_Il ne vous reste plus qu'à lancer le serveur et à contribuer :_
```bash
./manage.py runserver
```
## Django
Si vous n'avez jamais travailler avec Django, un tutoriel [s'impose](https://tutorial.djangogirls.org/fr/django_start_project/) !
## Déploiement _externe_
À ce jour, le déploiement est réalisé sur un petit vps [outgoing-utc.floflo.ch](outgoing-utc.floflo.ch)
\ No newline at end of file
Chargement des données initiales pour l'application
=====
Pour charger des données de base dans l'application, il suffit d'utiliser les classes `loadCountries`, `loadUniversities`, etc... disponibles dans `./backend/backend_app/load_data/loading_scripts`.
Autrement, pour tout charger d'un coup (et créer un administrateur avec pour identifiant "admin" et pour mot de passe "admin" **PENSER À LE CHANGER EN PRODUCTION...**), il suffit de passer par le shell de Django :
```bash
./manage.py shell
```
puis
```python
from backend.load_data import load_all
load_all()
```
Ces scripts sont _unit-testés_ donc ils devraient fonctionner.
\ No newline at end of file
Set-up
=======
## `Git`
*If you don't have `git` install on your computer, look online and install it 😜.
Then, you can simply clone the project repository:
```bash
git clone git@gitlab.utc.fr:rex-dri/rex-dri.git && cd rex-dri
```
## `docker` and `docker-compose`
This projects takes advantage of `docker` and `docker-compose` to ease the install process, continuous integration, deployments, etc.
!> If you don't have those tools on your computer, you first need to install them. You can do so by following those guides:
- [`docker`](https://docs.docker.com/install/)
- [`docker-compose`](https://docs.docker.com/compose/install/)
Once this is done, don't forget that you need to have docker running before using `docker-compose`. For example, on `Fedora 29` you need to run the following command:
```bash
sudo service docker start
```
Finally you can start-up all `docker` related *stuff* using the command:
```bash
make up--build
```
You can look at the `Makefile` to have more information on that last command and the other ones that are available.
To start all the `docker` images you will then only need to use the `make up` command.
## Initialization
To initialize the database associated with the project, you need to connect to the `backend` image:
```bash
make shell_bakend
```
Then:
- Migrate the `Django` models:
```bash
./manage.py migrate
```
- Create the initial revisions:
```bash
./manage.py createinitialrevisions
```
_NB: this last command should be run everytime you migrate (modify/add) some models._
- _Collectez_ les éléments statiques:
```bash
./manage.py collectstatic
```
When this is done you can exit the `docker` image shell (`CTRL + D`).
## Checking setup
### Backend
Run the commands bellow to check that the backend is setup correctly:
*(Simple check of the setup)*.