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/docker-compose.yml b/docker-compose.yml index 6b577b88617dec1cc6803bd3fc312c4c48c80905..058e1212dc08cbd1ecd75ff19a63086474b7c01e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,47 +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 index ed092311c883ef799e81aad2b3eb7f788cc3afa6..1e35c82c7de15683a4d590954749941f25599e19 100644 --- a/documentation/Dockerfile +++ b/documentation/Dockerfile @@ -1,3 +1,7 @@ -# 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 + +# 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 :  @@ -11,4 +13,4 @@ Vue plus précise :    - \ No newline at end of file + 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 @@ -