Commit 909dae0d authored by Florent Chehab's avatar Florent Chehab

Merge branch 'documentation' into 'master'

Documentation update

See merge request !47
parents 04a1d55d 110bcc8c
Pipeline #34896 passed with stages
in 3 minutes and 11 seconds
...@@ -7,6 +7,8 @@ stages: ...@@ -7,6 +7,8 @@ stages:
variables: variables:
SECRET_KEY: stupid_key_for_CI SECRET_KEY: stupid_key_for_CI
POSTGRES_DB: postgres POSTGRES_DB: postgres
...@@ -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"
docker-compose exec backend sh -c "cd backend && ./ 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](**
## Notes
**Collaborators and PR are highly welcomed!**
Feel free to ask questions about the project using the issue system.
**Retrouvez la documentation [ici](**
# 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
from django.contrib.auth.models import User from django.contrib.auth.models import User
import os
class LoadAdminUser(object): class LoadAdminUser(object):
...@@ -13,9 +14,13 @@ class LoadAdminUser(object): ...@@ -13,9 +14,13 @@ class LoadAdminUser(object):
self.admin = user[0] self.admin = user[0]
else: else:
User.objects.create_superuser( User.objects.create_superuser(
username="admin", email="", password="admin" username=os.environ["DJANGO_ADMIN_USERNAME"],
) )
self.admin = User.objects.filter(username="admin")[0] self.admin = User.objects.filter(
def get(self): def get(self):
return self.admin return self.admin
...@@ -18,3 +18,4 @@ django-extensions==2.1.5 ...@@ -18,3 +18,4 @@ django-extensions==2.1.5
uwsgi uwsgi
dotmap dotmap
django-webpack-loader==0.6.0 django-webpack-loader==0.6.0
ipython # For a better Django shell
# 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: image:
# 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
- SECRET_KEY=please_change_me - SECRET_KEY=please_change_me # Django secret key
# Django admin user param
# 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
# Run the django developpement server on image startup.
command: /bin/sh -c "cd backend && ./ runserver" command: /bin/sh -c "cd backend && ./ runserver"
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
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
build: ./documentation
- ./documentation:/usr/src/app
# Start a simple python folder
command: /bin/sh -c "python -m http.server 5000"
# replicate the server port
- "5000:5000"
volumes: volumes:
# Create some local volume (should be stored in some directory on your computer)
postgres_data: postgres_data:
======== ========
## 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 -H 'Authorization: Token MonTokenRandomSuperLong' curl -X GET -H 'Authorization: Token MyTokenRandomSuperLong'
``` ```
La génération du token se fait dans l'administration du site pour l'instant : `/admin`.
# 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
# Set-up a workdir so that it can be mapped to a volume in docker-compose.
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](;
- *More to come...*
<!-- docs/ --> <!-- docs/ -->
* [Présentation](/) * [Introduction](/)
* [Installation]( * [Set-up](
* [Chargement des données]( * [Use of `Docker`](
* [Initializing data](
* [Architecture]( * [Architecture](
* [Tags]( * [Tags](
* [API]( * [API](
* [À propos de cette documentation]( * [About this documentation](
* [Contributions]( * [Contributions](
\ 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: [](
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 []( 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:
docker login
To update the images stored on the Gitlab repository, run for instance:
docker build ./backend --compress --tag
And push it:
docker push
## 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:
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="//"> <link rel="stylesheet" href="//">
</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="//"></script> <script src="//"></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:
make django_shell
And running:
from backend_app.load_data import 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.
## 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/` :
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'outgoing',
'USER': 'outgoing',
'PASSWORD': 'outgoing',
'HOST': '',
'PORT': '5432',
et de décommenter celui-ci :
## Sqlite
# PROJECT_DIR = os.path.abspath(os.path.dirname(__file__))
# '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 :
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 :
host all all 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.
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 :
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 :
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) :
Créer une base de données qui lui sera associée :
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 :
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`)
python3.6 -m venv ./env
Cet environnement virtuel doit être **systématiquement** activé lorsque vous travaillez sur ce projet :
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 :
git clone
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 :
pip install -r requirements.txt
Téléchargez les dépendances `npm` nécessaires :
npm i
_Migrez_ la base de donnée :
./ migrate
_Initialisez_ les révisions:
./ createinitialrevisions
_NB: cette opération (en plus de `./ makemigrations` et de la précédente) est à faire à chaque fois que vous rajoutez/modifier un model._
_Collectez_ les éléments statistiques :
./ collectstatic