If you are a beginner, you might want to read this page first.

Here, you will learn how to set up the project and how to learn the workflow we try to keep here. First, clone this repository locally:

git clone https://github.com/Mines-Paristech-Students/Portail-des-eleves.git

You then need to set up:

• The database: a Postgres server running locally.
• The backend: an up to date python environment with Django 2.0.x, and all necessary pip dependencies.
• The frontend.

Create and populate the Postgres database

If you're using a Mac and want an easy app for using Postgres, you can check out https://postgresapp.com/.

Postgres does not come with an integrated database navigator such as PhpMyAdmin for MySQL. You'll have to install your own database browser such as DataGrip (paid but free for students) or the PyCharm database tools.

First of all install Postgres from this link : https://www.postgresql.org/download/.

On Ubuntu, the easiest solution may be to sudo apt install postgresql postgresql-contrib

Then, create a simple database and an user for it.

On Windows, you first need to add the psql CLI tool to the PATH.
Type path into the Start Menu (press the Windows button and type path), and click on Edit the system environment variables.
Click on Environment Variables.
From the System Variables box select PATH, Edit, and add C:\Program Files\PostgreSQL\9.2\bin and C:\Program Files\PostgreSQL\9.2\lib (replace 9.2 with your version).

To do so, go to a Postgres terminal using psql from the command line and run the following commands. On Windows, you'll need to type psql -U postgres -h localhost. You'll be prompted a password, enter the one you entered during Postgres installation.

Then, once in the psql invite (there will be a postgres=# at the start of each line, or something like that):

CREATE USER root WITH PASSWORD 'password';
CREATE DATABASE portail OWNER root;
CREATE DATABASE portail_message OWNER root;
ALTER USER root WITH SUPERUSER; # Grants all rights to root so as to run tests

(Note: maybe it's not necessary to grant super user rights, if anybody finds something less brutal it's great).

And that's it, the database has been created. You can exit from the Postgres CLI using \q.

If you want to reset the database completely (for instance after failed migrations), use DROP DATABASE portail; and CREATE DATABASE portail OWNER root;.

But an empty database is of no use of course, so you'll want to populate it: just run ./create_and_populate_database.bash in the cli directory in your command line, from the root of the repository. That command is for Linux. If you're using Windows, just type create_and_populate_database.bat and hit Enter.

You might see a few lines of red text about missing fixtures: don't worry about them!

You're now all set!

Installing and running the backend

An up to date python environment

Download and install the most recent version of Python from https://www.python.org (3.7 or newer). In Windows, agree when the Python installer asks you to add Python to the PATH. After installation, if you type python from the command line, this should run the version you have just installed.

We'll use venv to create a virtual environment. Set it up:

cd path/to/project/Portail-des-eleves/backend
python -m venv venv

Then, activate the virtual environment: use source venv/bin/activate on Mac or Linux, venv\Scripts\activate.bat on Windows. There should be a (venv) at the beginning of each line in your command prompt.

Finally, install the dependencies with pip install -r requirements.txt.

Copy the .env file

Go to path/to/project/Portail-des-eleves/backend/backend. There should be a .env.dist file. Copy it in the same folder with the name .env.

Run Django

Inside the virtual environment, you should now be able to get the backend running with python manage.py runserver.

The last command probably showed warnings about migrations to apply. Run cd .. (the working directory should now be Portail-des-eleves; this is very important) then cli/create_and_populate_database.bash on Unix systems, cli\create_and_populate_database.bat on Windows.

Wait. Pray.

To check that everything went OK, use your favorite browser to visit this link. It gives you a cookie that authenticates your use of the API (a token).

Then visit localhost:8000/api/v1. You should see an ugly Django debugging page entitled API root.

Frontend: React

On the frontend side, you need to install all the required dependencies (specified in package.json).

cd path/to/project/Portail-des-eleves/frontend
npm install

You can then run the app with npm run start

In the end

You should be able to access the Django API through localhost:8000 (useful to test the API) and the React server through localhost:3000, (and not 127.0.0.1:3000, it won't work).

Fix errors

If you chose another database, user or password for Postgres, you will need to update your backend/backend/.env file accordingly. Also check the port number on which your database is running.

Using code formatters

Your code will never make it to master if it isn't properly formatted because of continuous integration checks. Fortunately there are tools so you don't have to worry too much. You should rely on the 3 following

Black

Black is a Python code formatter that we use on this project. Please read here how to use it and make it work with your favorite IDE. It can be configured to be run every time you save a file.

Prettier

Prettier is to Javascript/Typescript what Black is to Python. See https://prettier.io/docs/en/install.html for installation instructions (use the npm version). Like Black, it integrates very well with most major IDEs.

Pre-commit hooks

Pre-commit hooks are local check that will run before you can commit anything and alert you if files are not properly formatted. To install pre commit hooks, see https://pre-commit.com/#install.

Then run pre-commit install and you are good to go!

Next

Congrats, the code is now running on your computer, you can now actively contribute to the code.