diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 0ccf222710466f3b6b05bc4e232aee0ce464a6da..1f6755c3c22e0925225c346d70fdc579097d3dae 100644 --- a/.gitlab-ci.yml +++ b/.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 diff --git a/Makefile b/Makefile index c82b2f222f765263cf94cb96d690f96fea238c79..0ebf3545ae37a706364ad4a7447a167d357e5dea 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 0d66ecdc11effd35fc1eefe24e53069e9cd08537..73d0dbeda8d564a00753d2a6b1512017bd60f9ee 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,15 @@ -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/).** diff --git a/backend/Dockerfile b/backend/Dockerfile index 8af8dc76756e61661623f4815bf7cb2e80705a1f..07485601d88b44d51593c38d523e15b08d79cf27 100644 --- a/backend/Dockerfile +++ b/backend/Dockerfile @@ -1,13 +1,14 @@ -# 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 diff --git a/backend/backend_app/load_data/loading_scripts/loadAdminUser.py b/backend/backend_app/load_data/loading_scripts/loadAdminUser.py index 72d696742f3982ff0611a0e7e0af4a6573d5aa99..0c898dffa872d461152ba72734b72a1da948e99e 100644 --- a/backend/backend_app/load_data/loading_scripts/loadAdminUser.py +++ b/backend/backend_app/load_data/loading_scripts/loadAdminUser.py @@ -1,4 +1,5 @@ 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 diff --git a/backend/requirements.txt b/backend/requirements.txt index bab3cdfc938590530ab383ffbbed4855a9ef62cd..12182d2d23dfc03c5a1c88808cfedabca8b6ee7d 100644 --- a/backend/requirements.txt +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml index 30aee32ab5e6365a09264d2040b1527bcf6efb24..058e1212dc08cbd1ecd75ff19a63086474b7c01e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,39 +1,73 @@ +# 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: diff --git a/documentation/API.md b/documentation/API.md index a5101b8fd4c3154cf852587ad0b4c2c672158f04..6445e57ed7cc80975e5e80a0df706e037e625a61 100644 --- a/documentation/API.md +++ b/documentation/API.md @@ -1,32 +1,27 @@ 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`. diff --git a/documentation/Dockerfile b/documentation/Dockerfile new file mode 100644 index 0000000000000000000000000000000000000000..1e35c82c7de15683a4d590954749941f25599e19 --- /dev/null +++ b/documentation/Dockerfile @@ -0,0 +1,7 @@ +# 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 diff --git a/documentation/README.md b/documentation/README.md index b9aba0ec73300b1e6223e238aea1aae790124c1d..59673e6de01ea9147e7c0c27d09e47ae1db2d0e8 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,7 +1,14 @@ -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...* diff --git a/documentation/_sidebar.md b/documentation/_sidebar.md index e100adb9bfced92980c05ad36703a33e78c8a07f..476562b5033c3b14364cc910a0aeef681a49e240 100644 --- a/documentation/_sidebar.md +++ b/documentation/_sidebar.md @@ -1,10 +1,11 @@ -* [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) diff --git a/documentation/architecture.md b/documentation/architecture.md index d399fc012a97b19f7c41f8407551d40656eb111a..77b95d551e9839504ff68e5ca289c4aecee0e553 100644 --- a/documentation/architecture.md +++ b/documentation/architecture.md @@ -1,7 +1,9 @@ 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) diff --git a/documentation/contributions.md b/documentation/contributions.md index d9010fd31f30e8621797fc3cae7dd41e1c3e521d..791ffdc9e6942d72f6bcaee2386c7a391691d0d2 100644 --- a/documentation/contributions.md +++ b/documentation/contributions.md @@ -1,4 +1,4 @@ -Contributeurs et contributrices :thumbsup: +Contributors :thumbsup: ========= - Florent Chehab diff --git a/documentation/docker.md b/documentation/docker.md new file mode 100644 index 0000000000000000000000000000000000000000..48145cdf3408470a878b9a73a200e1becb805d7c --- /dev/null +++ b/documentation/docker.md @@ -0,0 +1,50 @@ +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 +``` diff --git a/documentation/index.html b/documentation/index.html index ff6dbe05785854263b8118bc2951c7e3430c7364..961fadf26ea9d7a4772f3f42aa0be0199c75f57b 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -7,7 +7,7 @@ - + @@ -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 @@ - \ No newline at end of file + diff --git a/documentation/init_data.md b/documentation/init_data.md new file mode 100644 index 0000000000000000000000000000000000000000..2125d3ec155373fa25d898c9595275712a29caca --- /dev/null +++ b/documentation/init_data.md @@ -0,0 +1,22 @@ +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. diff --git a/documentation/installation.md b/documentation/installation.md deleted file mode 100644 index 64bf932e09849cbf1b12cdc571715f45f8e263fa..0000000000000000000000000000000000000000 --- a/documentation/installation.md +++ /dev/null @@ -1,194 +0,0 @@ -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 -``` -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 `()`. - - -_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 diff --git a/documentation/load.md b/documentation/load.md deleted file mode 100644 index 22acec0682f8794bc2fbe06ec6668d794adfb66a..0000000000000000000000000000000000000000 --- a/documentation/load.md +++ /dev/null @@ -1,18 +0,0 @@ -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 diff --git a/documentation/set-up.md b/documentation/set-up.md new file mode 100644 index 0000000000000000000000000000000000000000..a4db9eea8c9518d67cfc11ab7cd9ae4d45af1559 --- /dev/null +++ b/documentation/set-up.md @@ -0,0 +1,151 @@ +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).** diff --git a/documentation/tags.md b/documentation/tags.md index 54aa888a46a55ea60e2d484e90150373cf01d98e..616583de0d6e8bd88b789aba1f64402204835ed9 100644 --- a/documentation/tags.md +++ b/documentation/tags.md @@ -1,17 +1,18 @@ Tags ===== -Afin de simplifier l'architecture générale du backend est d'offrir de nombreuses possibilités d'évolutions, un système de tag a été mis en place. +To simplify the general `backend` architecture and allow for some generality, a *tagging* system has been put in place. -Un `Tag` est une sorte de module Django abstrait qui contient la définition de ses champs (et des contraintes associées) dans son attribut `config`. Les informations saises par les utilisateurs sont alors stockées sous forme de `JSON`. +A *Tag* is kind of Django model that contains the definition of its field (and the associated constraints) in its `config` attribute. +All information provided by the user is then stored in `JSON` format. -Les éléments `City`, `University`, `Campus` et `Country` peuvent être associé à n'importe quel tag : cela se passe dans les classes `*****TaggedItem`. +At this point, all `City`, `University`, `Campus` and `Country` models can be associated with any tag through `XXXXXTaggedItem` class. -Le tag se configure via un fichier `JSON` qui prend la forme suivante : +A `tag` is configured with a `JSON` that looks like this: ```json { - "nom du champ":{ + "name of the field":{ "type": "????", "required": bool, "validators" : { @@ -19,9 +20,10 @@ Le tag se configure via un fichier `JSON` qui prend la forme suivante : } } ``` -À ce jour, `type` et `validators` peuvent-être : + +At this point, `type` and `validators` may be: - 'text' : - - `max_length` pour contraindre la longueur maximale de la chaine de caractère. + - `max_length` to constrain the length of the text. - 'url' : - - `extension` : pour contraindre l'url (il doit se terminer par une extension de la liste) -- `list` : dans ce cas, TODO \ No newline at end of file + - `extension` : The constrain the extension (right `.` part) of the url. +- `list` : TODO diff --git a/documentation/this_doc.md b/documentation/this_doc.md index 9349db7fdfa8b0422df588467bfd10f806e7708f..a804dc5b7b9d035d6b46e18a7643951fd8ff62c8 100644 --- a/documentation/this_doc.md +++ b/documentation/this_doc.md @@ -1,29 +1,21 @@ -À propos de cette documentation +About this documentation ======== -## docsify.js +## `docsify.js` -Cette documentation (dans sa version _non markdown brut_) est générée avec l'aide de [`docsify`](https://docsify.js.org/). +This markdown based documentation is made available in a nice way using [`docsify`](https://docsify.js.org/). -## Rendu en _local_ +## Source -Pour un rendu en local de la documentation, il suffit de lancer un petit serveur permettant de distribuer les fichiers : +The source of the documentation is available in the `documentation` folder from the root of the repository. -```bash -#!/bin/bash -cd docs -python -m http.server 3000 -``` -La documentation sera alors disponible à l'adresse : -[http://0.0.0.0:3000/](http://0.0.0.0:3000/). +## Rendering -## Résolution de problèmes +The documentation is automatically rendered locally when you run the `make up` command. It is then available on [http://localhost:5000](http://localhost:5000). -### Fonction recherche +## Issues ? -!> Si la fonction `recherche` ne semble pas fonctionner après que vous ayez mis à jour la documentation, pensez à vider (`F12`, puis farfouillez) la variable `localStorage` associée à cette documentation dans votre navigateur. - -_Par défaut, les données contenues dans le `localStorage` ont une durée de vie d'une journée._ \ No newline at end of file +!> If the `search` functionality is not working after you have updated the documentation, it might be because the `localStorage` is not up to to data. You can empty it from your browser developer settings (`F12`). diff --git a/frontend/Dockerfile b/frontend/Dockerfile index 7a794b5abf5eb012b5d47954e17e0713e021efb0..bfa410344e5e2f65cc18acfa53bf7df13d60d003 100644 --- a/frontend/Dockerfile +++ b/frontend/Dockerfile @@ -1,3 +1,5 @@ -# pull official base image +# pull official base image of node FROM node:10.15.1-alpine + +# set up the workdir. WORKDIR /usr/src/app diff --git a/frontend/server.js b/frontend/server.js index 8e297f03a4be060b479100a17febefc81fc45ca9..376c9d510c13050b071e91784815c982dfd1fc30 100644 --- a/frontend/server.js +++ b/frontend/server.js @@ -1,3 +1,18 @@ +/* This file is use to start a webpack development server + * That supports hot module replacement. + * The compiled files are made available on 0.0.0.0:3000 + * + * The link with Django is made using webpack-bundle-tracker on the js side. + * It generates the `webpack-stat.json` file with the url of each compiled file. + * + * On Django side, the "dynamic" link is made using django-webpack-loader package. + * + * [OUT OF THE SCOPE OF THIS FILE] + * Note that if you run `npm run build`, then the file are generated and stored in the `dist` folder. + * `webpack-stat.json` will be updated accordingly; so there is nothing to worry with Django. + * + */ + var webpack = require("webpack"); var WebpackDevServer = require("webpack-dev-server"); var config = require("./webpack.config.dev");