Cette documentation est technique. Pour plus d'informations sur le simulateur d'aides pour les jeunes, regardez notre wiki.

L'interface utilisateur (et le serveur principal) du simulateur d'aides et de prestations sociales pour les jeunes. Il est basé sur simulateur socio-fiscal libre Openfisca.

Setup

Stack

• VueJS
• NodeJS
• MongoDB
• OpenFisca (Python, numpy)
• NetlifyCMS (config)
  • website
• Fabric (fabfile)

3rd parties

• Github Actions (config)
  • Continuous integration and deployment
• Netlify
  • Deloy previews
• SendInBlue
• Matomo (stats.data.gouv.fr)
  • [Dedicated site for usage data and impac][https://betagouv.github.io/mes-aides-analytics/] source
• Sentry
  • backend
  • frontend

Front only install

If you want to play with the UI, you can be set up very quickly:

npm ci
npm run front

Cf. package.json for more on the underlying commands.

The application should be accessible at localhost:8080.

Full install

System dependencies

Ubuntu

Make sure build-essential, mongodb and node 16.x are installed on your machine:

sudo apt-get install build-essential
sudo apt-get install mongodb

For all platforms

The runtime is Node 16.x for the web application, and Python 3.7 for Openfisca.

You can for example use nvm to install this specific version.

You will need pip to install Openfisca.

Application

Run the following from the root of the project to install the dependencies

npm ci

Openfisca

There are 2 ways to run Openfisca:

• either by installing its dependencies in a Python virual environment locally on your machine
• or by using Docker to pull and build an image with the required dependencies

Note that if you are using a Mac with a M1/M2 processor it is advised to use Docker since not all packages used by Openfisca can be installed locally.

Install Openfisca in a virtual environment

⚠️ As of now, python3.9 is not yet compatible with all python packages used in Openfisca. It is recommend to use a lower version such as 3.8.13.

You should install Python 3 in a virtual environment to prevent yourself from messing with your main python installation. The instructions below rely on the built-in venv module so that there are no additional external dependencies:

python3 -m venv .venv   # create the virtual environment in the .venv folder
source .venv/bin/activate  # activate the virtual environment
pip install pip --upgrade  # make sure we're using the latest pip version
npm run install-openfisca  # install dependencies

Then, to start the OpenFisca server, simply run source .venv/bin/activate followed by npm run openfisca.

OpenFisca dependencies are specified in openfisca/requirements.txt, a basic Python requirements file. It is possible to refer to non-production commit hashs but is prefered to use main-merged commits.

Install and run Openfisca in a docker container

If you want to run Openfisca without having to install a specific version of Python or create a virtual environment you can use the docker file provided to run Openfisca in a container. From the root of the project run the following command to build the docker image:

docker build -f openfisca/Dockerfile ./openfisca -t openfisca

Development mode

If you are working on openfisca-france and want to use your local version:

cd (...)/openfisca-france
pip install --editable .

Test in production mode

If you want to test locally the app in production mode:

npm run build
npm run start

Usage

First, start a Mongo server:

npm run db

Then, in another shell you will need to start openfisca. If you installed it locally activate the virtual environment (run source .venv/bin/activate) and start the Openfisca server:

OPENFISCA_WORKERS=1 npm run openfisca

If instead you want to run Openfisca in a docker container run:

docker run -d -p 2000:2000 openfisca

(note that in that case Openfisca will run in the background and you will have to run docker ps and docker stop XXXXX where XXXXX is the container ID to stop Openfisca)

Finally, in a third shell, start the server:

npm run serve

Testing

There are several levels of tests:

• Unit tests are executed by Jest and run with npm test.
• End-to-end test are executed with Cypress with npm run cypress

You can safely use npm test && npm run cypress to drive your developments.

Email

We use the framework MJML to design and integrate the templates. Sendinblue is our service to send emails.

The development server for emails can be easily start with: npm run tools:serve-mail

If you want to verify the email sending, the variable SEND_IN_BLUE_PRIVATE_KEY=API_SECRET should be configured in your .env file. You can create a free account here or request one on the mattermost channel.

Linting and format

We use ESLint as a linter and Prettier to format the codebase. We also utilize some ESLint plugins, such as vue-eslint and eslint-plugin-cypress, to provide a support for tests and framework.

Continuous deployment

SSHs keys were generated to run scripts on the production server.

With the deploy key at hand, linked to the deploment script it is possible kick of a now deployment thanks to:

ssh [email protected] -i deploy

For more, a normal/manual root connection is required.

ssh [email protected]

Other tools scripts & tips

In order to use those tools you need to build the server at least once using the command npm run build:server.

• npm run husky installs git hooks used to facilitate development and reduce the CI running time.

• npm run tools:check-links-validity validates links to 3rd parties in benefits files.

• npm run tools:cleaner cleans simulations data older than 31 days.

• npm run tools:evaluate-benefits <simulationId> evaluates benefits linked to a simulation id.

• npm run tools:generate-missing-institutions-aides-velo generates missing institutions for the package aides-velo.

• npm run tools:geographical-benefits-details gets the relevant benefits for each commune.

• npm run tools:get-all-steps gets all the steps and substeps of a simulation.

• npm run tools:serve-mail generates emails which contain the result of a simulation or a survey.

• npm run tools:test-benefits-geographical-constraint-consistency validates geographical constraint consistency of benefits.

• npm run tools:test-definition-periodsvalidates the periods of openfisca requested variables.

• Locally or on production, it is possible to visualize all the available benefits of the simulator. It is done by adding debug as a parameter. It is also possible to set debug=ppa,rsa to choose which benefits are listed.

• Adding debug=parcours as a parameter, show a debug version of all the steps in the simulator, locally and production.

• OpenFisca tracer allows you to debug OpenFisca computations. (source)

Export simulations data from database

Mongo export to csv.

How to use: mongo --quiet db_aides_jeunes --eval "var headers='month,depcom100kp,departement';" tools/mongo-query.js > export.csv

The headersparameter must contains desired headers.

Possible variables:

• activite
• age
• avecRessources
• departement
• depcom
• depcom100kp
• epci
• region
• logement
• month
• + possible fieldName values in the answers

NetlifyCMS development

It is possible to locally debug changes in NetlifyCMS configuration.

• First, contribuer/public/admin/config.yml#L19 (local_backend: true) must be uncommented;
• npx netlify-cms-proxy-server should be ran from . and
• npm ci and npm run dev should be ran from contribuer.
• Netlify CMS should now be accessible at http://localhost:3000/admin/index.html

Changes made will be reflected locally instead of generating pull requests in production.