Merge branch 'documentation' into 'master'

Documentation update

See merge request rex-dri/rex-dri!47

.gitlab-ci.yml

@@ -7,6 +7,8 @@ stages:
 variables:
   ENV: DEV
   SECRET_KEY: stupid_key_for_CI
+  DJANGO_ADMIN_USERNAME: admin
+  DJANGO_ADMIN_PASSWORD: admin
   POSTGRES_DB: postgres
   POSTGRES_USER: postgres
   POSTGRES_PASSWORD: postgres

Makefile

@@ -25,10 +25,13 @@ build_frontend:
 	docker-compose exec frontend sh -c "cd frontend && npm run build"
 
 shell_backend:
-	docker-compose exec backend sh
+	docker-compose exec backend sh -c "cd backend && bash"
 
 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:
 	cd documentation && $(MAKE) all

README.md

-1. It's still a work in progress
-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.
+# Rex-DRI
+
+*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/).**

backend/Dockerfile

-# 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)
-# 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
 
 # set work directory
 WORKDIR /usr/src/app
 
-# runtime dependencies
-# libpq-dev and gcc  is for psycopg2-binary
+# server dependencies
+# python3-dev, libpq-dev and gcc  is for psycopg2-binary
 RUN apt-get update && apt-get install -y --no-install-recommends \
 		libpq-dev \
 		python3-dev \
@@ -16,7 +17,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 	&& rm -rf /var/lib/apt/lists/*
 
 
-# install dependencies
+# python dependencies
 RUN pip install --upgrade pip
 COPY requirements.txt /usr/src/app/requirements.txt
 RUN pip install -r requirements.txt

backend/backend_app/load_data/loading_scripts/loadAdminUser.py

 from django.contrib.auth.models import User
+import os
 
 
 class LoadAdminUser(object):
@@ -13,9 +14,13 @@ class LoadAdminUser(object):
             self.admin = user[0]
         else:
             User.objects.create_superuser(
-                username="admin", email="null@null.fr", password="admin"
+                username=os.environ["DJANGO_ADMIN_USERNAME"],
+                email="null@null.fr",
+                password=os.environ["DJANGO_ADMIN_PASSWORD"],
             )
-            self.admin = User.objects.filter(username="admin")[0]
+            self.admin = User.objects.filter(
+                username=os.environ["DJANGO_ADMIN_USERNAME"]
+            )[0]
 
     def get(self):
         return self.admin

backend/requirements.txt

@@ -18,3 +18,4 @@ django-extensions==2.1.5
 uwsgi
 dotmap
 django-webpack-loader==0.6.0
+ipython  # For a better Django shell

docker-compose.yml

+# 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'
 
 services:
+  # Service for the backend app.
   backend:
+    # Get the image from the registry
     image: registry.gitlab.utc.fr/rex-dri/rex-dri/backend:latest
+    # To use a locally build one, comment above, uncomment bellow.
     # build: ./backend
     volumes:
+      # "Copy" the repo to the workdir.
       - .:/usr/src/app/
     ports:
-      - 8000:8000  # Replicate the python server port
+      # Replicate the python server port
+      - 8000:8000
     environment:
+      # Add environment variables
       - 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_PASSWORD=admin
+      # DB parameters
       - DB_HOST=database
       - DB_PORT=5432
       - POSTGRES_DB=postgres
       - POSTGRES_USER=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"
     depends_on:
+      # Required that the `database` service is up and running.
       - database
+  # Service for the postgres database
   database:
+    # Use of classic image
     image: postgres:10.5-alpine
     environment:
+      # Set up the postgres ID
       - POSTGRES_DB=postgres
       - POSTGRES_USER=postgres
       - POSTGRES_PASSWORD=postgres
     volumes:
+      # Add a volume to store the DB data.
       - postgres_data:/var/lib/postgresql/data/
+  # Service to handle frontend live developpments and building
   frontend:
+    # Build image from Dockerfile
     build: ./frontend
+    # On startup, start the developpement server
     command: /bin/sh -c "cd frontend && npm i --verbose && npm run dev"
     volumes:
+      # "Copy" the repo to the workdir.
       - .:/usr/src/app/
     ports:
-      - 3000:3000  # Replicate the node server port
+      # Replicate the node server port. More info in ./frontend/server.js
+      - 3000:3000
+  documentation:
+    build: ./documentation
+    volumes:
+      - ./documentation:/usr/src/app
+    # Start a simple python folder
+    command: /bin/sh -c "python -m http.server 5000"
+    ports:
+      # replicate the server port
+      - "5000:5000"
 
 volumes:
+  # Create some local volume (should be stored in some directory on your computer)
   postgres_data:

documentation/API.md

 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.
-
-Dans les deux cas, les réponses de l'API dépendront des droits associés à l'utilisateur.
+Two authentication protocol are currently available and both lead to API response according to the rights of the corresponding user.
 
 
 ### Session
 
-Il s'agit du mode d'authentification automatiquement utilisé lorsque vous naviguez sur le site.
-Il faut s'être connecté au CAS avant : `/user/login`.
+This is the default mode used once you are connected with the `CAS` by going to the URI `/user/login`.
 
 
 ### 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
-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`.

documentation/Dockerfile

+# 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

documentation/README.md

-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...*

documentation/_sidebar.md

 <!-- docs/_sidebar.md -->
 
-* [Présentation](/)
-* [Installation](installation.md)
-* [Chargement des données](load.md)
+* [Introduction](/)
+* [Set-up](set-up.md)
+* [Use of `Docker`](docker.md)
+* [Initializing data](init_data.md)
 * [Architecture](architecture.md)
-* [Tags](tafs.md)
+* [Tags](tags.md)
 * [API](API.md)
-* [À propos de cette documentation](this_doc.md)
-* [Contributions](contributions.md)
\ No newline at end of file
+* [About this documentation](this_doc.md)
+* [Contributions](contributions.md)

documentation/architecture.md

 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 :
 ![Architecture](generated/architecture.svg)
@@ -11,4 +13,4 @@ Vue plus précise :
 ![other_core](generated/core.svg)
 ![AbstractModules](generated/university.svg)
 ![Architecture](generated/location.svg)
-![Architecture](generated/user.svg)
\ No newline at end of file
+![Architecture](generated/user.svg)

documentation/contributions.md

-Contributeurs et contributrices :thumbsup:
+Contributors :thumbsup:
 =========
 
 - Florent Chehab

documentation/docker.md

+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
+```

documentation/index.html

@@ -7,7 +7,7 @@
     <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <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>
 
 <body>
@@ -17,10 +17,10 @@
             loadSidebar: true,
             maxLevel: 4,
             subMaxLevel: 4,
-            name: 'Outgoing',
+            name: 'Rex-DRI',
             search: {
-                placeholder: 'Recherche...',
-                noData: 'Pas de résultat :(',
+                placeholder: 'Search for...',
+                noData: 'No result :(',
                 paths: ['/installation']
             },
         }
@@ -33,4 +33,4 @@
     <script src="//unpkg.com/prismjs/components/prism-sql.min.js"></script>
 </body>
 
-</html>
\ No newline at end of file
+</html>

documentation/init_data.md

+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.

documentation/installation.md

-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

documentation/load.md

-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

documentation/set-up.md

+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)*.
+
+
+```bash
+make check_backend
+```
+
+
+*(Run `Python` tests)*
+
+
+```bash
+make test_backend
+```
+
+
+### Frontend
+
+
+Run the commands bellow to check that the frontend is setup correctly:
+
+
+*(Build the `React` app)*
+
+
+```bash
+make build_frontend
+```
+
+
+*NB: At the time of the writing of the documentation there is no test for the frontend...*
+
+
+
+## You are done
+
+
+Once the `Docker` images are up (command `make up`), the app is available on [http://localhost:8000](http://localhost:8000).
+
+
+**Don't miss the other pages of the documentation, in particular [the one about loading 'init' data in the app](init_data).**

documentation/tags.md

 Tags