Aidants Connect est une application web qui propose à des aidants les fonctionnalités suivantes :
- créer un mandat de connexion via FranceConnect avec un ou plusieurs usagers sur un périmètre et une durée définis ;
- connecter via FranceConnect un usager dans les conditions des mandats créés ;
- accéder à des ressources sur l'accompagnement des usagers ;
- accéder à un suivi de ses mandats.
Aidants Connect est construit sur les éléments suivants :
- Python 3.11
- Django 4.2
- PostgreSQL
Lancement rapide si vous avez déjà installé la base de données et les dépendances de test :
git clone [email protected]:betagouv/Aidants_Connect.git
cd Aidants_Connect
cp .env.example .env
virtualenv venv
source venv/bin/activate
pip install --user pipenv
pipenv install --dev
python manage.py collectstatic
pre-commit install
Ensuite, vous devriez pouvoir faire tourner les tests :
python manage.py test
Et lancer le serveur :
python manage.py runserver 3000
Utilisez votre gestionnaire de paquets préféré pour installer la base.
L'exemple qui suit emploie le gestionnaire Homebrew via la commande brew
.
Dans un terminal, installez PostgreSQL :
brew install postgresql
Démarrez le service postgresql :
brew services start postgresql
Ceci démarre le serveur de la base de données et active sa réexécution au login.
Dans le cas où ce serait votre première utilisation de PostgreSQL, créez une base d'essai à votre nom :
createdb `whoami`
Puis, démarrez l'invite de commande PostgreSQL :
psql
Vous pouvez dès à présent visualiser :
- la liste des bases de données existantes avec cette commande PostgreSQL
\list
- la liste des rôles existants avec
\du
Ajoutez une base aidants_connect
appartenant au nouvel utilisateur aidants_connect_team
en poursuivant dans l'invite de commmande PostgreSQL :
CREATE USER aidants_connect_team;
CREATE DATABASE aidants_connect OWNER aidants_connect_team;
ALTER USER aidants_connect_team CREATEDB;
🎉 La base de donnée aidants_connect
est installée. Vous pouvez la voir et quitter l'invite de commande avec :
\list
\q
Dans votre répertoire de travail, créez et activez un environnement virtuel :
virtualenv venv
source venv/bin/activate
Installez pipenv :
brew install pipenv # Sur Mac
# Ou
pip install pipenv
Installez les dépendances :
pipenv install --dev
Si vous avez un Mac M1, ou si la commande précédente déclenche le message d'erreur ld: library not found for -lssl
, référez-vous à la section Troubleshooting.
Dupliquez le fichier .env.example
à la racine du projet en tant que .env
:
cp .env.example .env
En test en local, vous ne devriez pas avoir à modifier ce .env
.
Créez un répertoire staticfiles
à la racine du projet :
mkdir staticfiles
Appliquez les migrations de la base de données :
python manage.py migrate
Il existe plusieurs moyens de peupler la base de données.
Des données de test qui créent un environnement complet :
python manage.py loaddata admin.json
python manage.py loaddata usager_autorisation.json
python manage.py loaddata faq.json
Ce process crée automatiquement un superuser [email protected]
. Plus d'information sur comment se connecter avec ce compte sont disponible dans la section Se connecter à l'application
Créez un profil administrateur avec une organisation par défaut :
python manage.py createsuperuser --username <insert_admin_email> --organisation-name <insert_organisation_name>
Une organisation avec l'email que vous avez spécifié sera automatiquement créée pour ce profil. Si vous avez déjà créé une organisation vous pouvez passer son numéro dans la base de donnée à la création du profil admin :
python manage.py createsuperuser --username <insert_admin_email> --organisation <insert_organisation_pk>
Pour pouvoir vous connecter à votre instance locale, il faut apparier à votre superuser
un dispositif TOTP (TOTP device
).
Pour cela, commencez par lui adjoindre un jeton OTP statique :
python manage.py addstatictoken <insert_admin_email> -t <insert_6_numbers>
Notez ce code, il vous permettra de vous connecter la première fois à l'interface d'administration.
Si vous ne les avez pas, installez les éléments suivants :
- Navigateur Firefox en téléchargement
- Gecko driver
Installation de Gecko Driver :
- Mac OS :
brew install geckodriver
- Linux : vous pouvez télécharger ici la dernière
version du driver et déposer le fichier
geckodriver
dansVOTRE_VENV/bin
(ou dans/usr/local/bin
si vous voulez donner un accès global au driver).
Puis lancez les commandes suivantes pour vérifier le style du code source et exécuter les tests de l'application :
flake8
black --check .
python manage.py test
Les tests fonctionnels (Selenium) sont lancés sur http://localhost:3000
.
Il faut s'assurer que rien d'autre n'occupe ce port pendant leur exécution.
Par défaut, les tests Selenium sont lancés en mode headless, c'est-à-dire sans ouverture de fenêtre de navigateur. Pour modifier ce comportement, inversez la valeur de la variable d'environnement HEADLESS_FUNCTIONAL_TESTS
dans votre fichier .env
.
Astuce : la plupart des cas de tests portent une directive @tag
pour leur associer des tags décrivant des fonctionnalités ou des caractéristiques des tests. Par exemple, functional
pour les tests fonctionnels, create_mandat
pour ce qui implique une création de mandat, etc.
Cela vous permet de lancer seulement certains tests, grâce à l'option --tag
. Par exemple, pour lancer les tests portant le tag parrot
:
python manage.py test --tag parrot
Pour lancer l'application sur le port 3000
:
python manage.py runserver 3000
L'application sera disponible à l'URL http://localhost:3000/
.
Votre superuser est créé et a un login, un mot de passe et un static token c'est-à-dire un code à 6 chiffres utilisable une seule fois. Il faut maintenant obtenir le QR code qui vous permettra de vous connecter de manière pérenne.
La page d'admin se trouve sur /[Variable d'environnement ADMIN_URL]
. En local, /adm
.
Attention, /admin
n'est pas un vrai site d'admin… c'est un pot de miel.
- ⏩ Si vous avez utilisé les fixtures pour peupler votre base de données,
- identifiant :
[email protected]
; - mot de passe :
admin
; - Static OTP :
111111
- identifiant :
- Sinon, utilisez le login, mot de passe et static token créés dans la section Installation sur un serveur : Créer un superuser
Une fois connecté à l'admin, cliquez sur TOTP devices
- ⏩ Si vous avez utilisé les fixtures :
- Cliquez sur le lien
qr code
à droite de l'entrée pour Admin - Scannez le QRcode dans une application TOTP telle que Authy ou Google Authenticator
- Cliquez sur le lien
Si vous avez créé votre propre superuser :
- Cliquez sur le bouton
Ajouter TOTP device +
- Choisissez votre superuser grâce à l'icône "loupe" située à côté du champ User
- Saisissez un nom pour votre dispositif TOTP (par exemple : Mon téléphone) dans le champ
Name
- Cliquez ensuite sur Enregistrer et continuer les modifications tout en bas du formulaire
- Une fois l'enregistrement effectué, l'écran devrait se rafraîchir et vous proposer un lien vers un QR Code
- Vous pouvez à présent scanner celui-ci dans une application TOTP telle que Authy ou Google Authenticator pour utiliser l'authentification à double facteur dans votre environnement local.
Il faut d'abord avoir correctement installé l'application.
Installez les git hooks :
pre-commit install
La CSP (content security policy) de Aidants Connect fonctionne en liste blanche : elle nécessite de lister tous les scripts inline (dans des balises <script>
).
Si vous devez modifier ou ajouter un bout de JavaScript inline, vous pouvez utiliser la propriété csp_nonce
de l'objet HttpRequest
générée par django-csp
:
<script nonce="{{request.csp_nonce}}">
var hello="world";
</script>
Pour compiler les fichiers SCSS en CSS, vous devez avoir installé sass sur votre poste, la commande sass
doit être disponible dans votre $PATH
.
Ensuite, utilisez une des deux commandes suivantes :
python manage.py scss # compilation one-shot
# ou bien :
python manage.py scss --watch # compilation automatique à chaque modification de SCSS
Sur un serveur, vous voudrez ajouter vos informations dans le fichier .env ou dans les variables d'environnement de votre hébergeur :
- Les champs obligatoires sont indiqués par le préfixe
<insert_
. - Les informations de production
FC_AS_FS
etFC_AS_FI
sont à récupérer via des habilitations FranceConnect. - Vous allez devoir calculer la valeur
HASH_FC_AS_FI_SECRET
à partir de la valeur deFC_AS_FI_SECRET
: pour cela voir dans les annexes la procédure. - Les valeurs de sécurité sont issues de la section "sécurité" de la documentation Django et de la conférence Django and Web Security Headers.
Il existe deux solutions.
- déployer la branche de la PR 473 avant de déployer main (utilisé pour notre environnement sandbox).
- avant de déployer le code, insérer les variables d'environnement
INIT_*
mentionnées dans la PR ; - installer l'application à partir de la branche de la PR 473 ;
- déployer ensuite l'application à partir de la branche
main
.
- avant de déployer le code, insérer les variables d'environnement
- insérer directement les données dans la base de données après l'installation de l'application.
Pour simplifier le lancement de certaines commandes, un Makefile est disponible. Exemples de commandes :
make destroy-rebuild-dev-db
Sur Windows, la commande make
n'est pas disponible ;
Il faut passer chaque commande du Makefile
(fichier présent à la racine du projet) les unes après les autres.
Si vous avez des données existantes, vous pouvez d'abord les sauvegarder :
python manage.py dumpdata --exclude auth.permission --exclude contenttypes > db.json
Puis il vous faudra recréer la base de donnée PostgreSQL :
-
Dans le shell :
psql
-
Puis, dans l'invite de commande
psql
:DROP DATABASE aidants_connect; CREATE DATABASE aidants_connect OWNER aidants_connect_team; ALTER USER aidants_connect_team CREATEDB; \q
Ensuite, de retour dans le shell, pour lancer les migrations :
python manage.py migrate
Enfin, chargez les données :
-
Soit des données sauvegardées précédement :
python manage.py loaddata db.json
-
Soit repartir de zéro en recréant un superuser (plus de détails dans la section Installer l'application) :
python manage.py createsuperuser
Les objets Django de type Connection
repésentent une forme de cache pendant l'établissement de la connexion FranceConnect.
À ce titre, ils contiennent des données personnelles et doivent donc être purgés régulièrement pour respecter nos engagements en la matière.
Pour ce faire, il suffit d'exécuter ou de planifier la commande suivante :
python manage.py delete_expired_connections
Il faut utiliser generate_sha256_hash
.
from aidants_connect_web.utilities import generate_sha256_hash
generate_sha256_hash("VALUE_FC_AS_FI_SECRET".encode("utf-8"))
Si la commande précédente déclenche le message d'erreur suivant ld: library not found for -lssl
, essayez :
export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/opt/openssl/lib/
- Si, lors de l'installation de
psycopg2-binary
, vous avez le message d'erreur suivant :
ld: warning: directory not found for option '-L/usr/bin/openssl/lib/'
ld: library not found for -lssl
clang: error: linker command failed with exit code 1 (use -v to see invocation)
error: command 'clang' failed with exit status 1
- Si vous avez installé
openssl
viabrew
, vous pouvez essayer la commande suivante :
env LDFLAGS='-L/opt/homebrew/opt/[email protected]/lib -L/opt/homebrew/opt/readline/lib' pip install -r requirements.txt
- Si, lors de l'installation de
pillow
vous avez le message d'erreur suivant :
The headers or library files could not be found for zlib,
a required dependency when compiling Pillow from source.
Vous pouvez essayer :
brew install libjpeg
Dans de rares cas (comportement observé à ce jour sur une seule machine de dev), les tests d'intégration échouent car la première connexion à une URL via l'API Selenium plante de manière inexpliquée.
Un contournement empirique a été mis en place ; si vous rencontrez ce problème vous pouvez l'activer en passant à True
la variable d'environnement BYPASS_FIRST_LIVESERVER_CONNECTION
dans votre fichier .env
.