git clone [email protected]:betagouv/ma-cantine.git
Si git dit que vous avez des nouveaux fichiers juste après cloner le dépôt, vérifier vos paramètres de git. Sur mon ordinateur, j'ai du faire :
git config core.precomposeunicode falsegit reset --hard origin/staging(attention, vos changements en locale seront perdus)git pull
D'autres conseils que j'ai lu c'est de faire git config core.precomposeunicode true et/ou git config core.quotepath false. Vous pourriez vérifier vos config avec git config -l. Si ça ne marche pas, essayer de tirer des cartes de tarot ou faire une offrande à la lune (ou bien soumettre un issu). Bon courage.
Please note that the staging and main branches are protected and all commits must come through a pull request.
- Python3 (de préference 3.11)
- pip (souvent installé avec Python)
- vitrualenv (optionnel)
- Node et npm
- Postgres
- Redis
- pre-commit
Pour commencer, c'est recommandé de créer un environnement virtuel avec Python3.
python -m venv venv
source ./venv/bin/activate
virtualenv -p python3 venv
source ./venv/bin/activate
Les dépendances du backend se trouvent dans requirements.txt. Pour les installer :
pip install -r requirements.txt
Si vous rencontrez un problème avec psycopg2, installez psycopg2-binary à la place.
On utilise les dernières versions LTS de node et npm.
L'application frontend se trouve sous /frontend. Pour installer les dépendances :
cd frontend
npm install
Pour créer une base de données nommée macantine_egalim :
createdb macantine-egalim
Pour créer une base de données nommée macantine_egalim avec un utilisateur dédié macantine_egalim_team, et définir le mot de passe :
psql -c "CREATE USER macantine_egalim_team WITH PASSWORD 'password'"
psql -c "CREATE DATABASE macantine_egalim OWNER macantine_egalim_team"
psql -c "GRANT ALL PRIVILEGES ON DATABASE macantine_egalim to macantine_egalim_team"
psql -c "ALTER USER macantine_egalim_team CREATEROLE CREATEDB"
L'application utilise python-dotenv, vous pouvez donc créer un fichier .env à la racine du projet avec ces variables définies :
SECRET= Le secret pour Django (vous pouvez le [générer ici](https://djecrety.ir/))
DEBUG= `True` pour le développement local ou `False` autrement
DEBUG_FRONT= `True` pour le développement local du 2024-front ou `False` autrement
DB_USER= L'utilisateur de la base de données. Doit avoir les droits de creation de db pour les tests (par ex. 'macantine_egalim_team')
DB_PASSWORD= Le mot de passe pour accéder à la base de données
DB_HOST= Le host de la base de données (par ex. '127.0.0.1')
DB_PORT= Le port de la base de données (par ex. '3306')
DB_NAME= Le nom de la base de données (par ex. 'macantine_egalim')
HOSTNAME= Le hostname dans lequel l'application se trouve (par ex. 127.0.0.1:8000)
ALLOWED_HOSTS= Des noms de domaine/d’hôte que ce site peut servir (par ex. 'localhost, \*')
ENFORCE_HOST= Optionnel - Si présent, les requêtes seront redirigées à ce host
STATICFILES_STORAGE= Le système utilisé pour les fichiers statiques (par ex. 'django.contrib.staticfiles.storage.StaticFilesStorage')
DEFAULT_FILE_STORAGE= Le système de stockage de fichiers (par ex 'django.core.files.storage.FileSystemStorage')
FORCE_HTTPS= 'False' si on développe en local, 'True' autrement
SECURE= 'False' si on développe en local, 'True' autrement
EMAIL_BACKEND= par ex. 'django.core.mail.backends.console.EmailBackend'. Pour utiliser SendInBlue : 'anymail.backends.sendinblue.EmailBackend'
DEFAULT_FROM_EMAIL= par ex. '[email protected]'
CONTACT_EMAIL= par ex. '[email protected]'
SENDINBLUE_API_KEY= La clé API de SendInBlue
NEWSLETTER_SENDINBLUE_LIST_ID= L'ID de la newsletter de SendInBlue
MATOMO_ID= 162 pour la prod (peut-être laissé vide)
CELLAR_HOST= Optionnel - le host du service S3
CELLAR_KEY= Optionnel - la clé du service S3
CELLAR_SECRET= Optionnel - le secret du service S3
CELLAR_BUCKET_NAME= Optionnel - le nom du bucket S3 à utiliser
DATA_WARE_HOUSE_USER= Optionnel - l'utilisateur de la base postgres utilisée pour les analsyes stats
DATA_WARE_HOUSE_PASSWORD= Optionnel - le mot de passe de la base de postgres utilisée pour les analsyes stats
DATA_WARE_HOUSE_HOST=Optionnel - le host de la base postgres utilisée pour les analsyes stats
DATA_WARE_HOUSE_PORT= Optionnel - le port de la base postgres utilisée pour les analsyes stats
DATA_WARE_HOUSE_DB= Optionnel - le nom de la db de la base postgres utilisée pour les analsyes stats
DEBUG_PERFORMANCE= Optionnel - à utiliser avec "DEBUG" pour montrer la [Django Debug Toolbar](https://django-debug-toolbar.readthedocs.io/en/latest/)
ENVIRONMENT= Optionnel - si cette variable est remplie un badge sera visible dans l'application et l'admin changera. Les options sont : `dev` | `staging` | `demo` | `prod`
REDIS_URL= L'instance redis à utiliser pour les tâches asynchrones et le cache des clés API. Par exemple : 'redis://localhost:6379/0'
REDIS_PREPEND_KEY= Optionnel - Ajout ce string au début de chaque clé Redis. Utile pour partager la même DB Redis sur plusieurs environnements
OVERRIDE_TEST_SEED= Optionnel - `seed` utilisé par les tests pour les éléments aléatoires. Utile lors qu'un test échoue et qu'on veut reproduire exactement ce qu'il s'est passé.
SIRET_API_KEY= Optionnel - pour utiliser l'API INSEE Sirene. Pour générer : accèder votre compte https://api.insee.fr/catalogue/ > My applications > Add application
SIRET_API_SECRET= Optionnel - pour utiliser l'API INSEE Sirene
MONCOMPTEPRO_CLIENT_ID= Optionnel - Client ID utilisé pour l'authentification via [MonComptePro](https://github.com/betagouv/moncomptepro).
MONCOMPTEPRO_SECRET= Optionnel - Secret utilisé pour l'authentification via [MonComptePro](https://github.com/betagouv/moncomptepro).
MONCOMPTEPRO_CONFIG= Optionnel - Url de configuration utilisé pour l'authentification via [MonComptePro](https://github.com/betagouv/moncomptepro). Par exemple : `https://app-test.moncomptepro.beta.gouv.fr/.well-known/openid-configuration`
MAX_DAYS_HISTORICAL_RECORDS= Optionnel - Flag pour indiquer le nombre de jours pendant lequels on garde l'historique des modèles. Utilisé lors d'une tâche Celery.
CSV_PURCHASE_CHUNK_LINES= Optionnel - Définit le nombre de lignes dans chaque chunk pour l'import des achats. Le choix par défaut est de 81920 ce qui représente en moyenne des chunks de 3Mb.
ENABLE_XP_RESERVATION= Optionnel - `True` pour activer la feature de l'expérimentation des systèmes de réservation.
ENABLE_XP_VEGE= Optionnel - `True` pour activer la feature de l'expérimentation de l'offre quotidien de repas végétariens.
ENABLE_TELEDECLARATION= Optionnel - `True` pour permettre les utilisateurs de télédéclarer leur diagnostic.
TELEDECLARATION_CORRECTION_CAMPAIGN= Optionnel - `True` pour pour distinguer la campagne de TD de la campagne de corrections. Ça fait pas grande chose sans ENABLE_TELEDECLARATION.
TELEDECLARATION_END_DATE= Optionnel - Celle-ci n'est pas exactement une feature flag mais fonctionne avec le flag précedent. Il faut indiquer une date pour la fin de la campagne de la télédéclaration (par exemple, `2024-03-15`)
ENABLE_DASHBOARD= Optionnel - `True` pour montrer la nouvelle page d'accueil des gestionnaires.
PUBLISH_BY_DEFAULT= Optionnel - `True` pour publier les cantines sauf celles qui sont identifiées autrement.
ENABLE_VUE3= Optionnel - `True` pour rendre les nouvelles vues disponibles.
ENABLE_WASTE_MEASUREMENTS= Optionnel - `True` pour rendre l'outil évaluation gaspillage alimentaire disponible
TEMPLATE_ID_NO_CANTEEN_FIRST= Optionnel - ID du template SendInBlue pour le premier email envoyé aux utilisateurs n'ayant pas encore créé une cantine. En cas d'absence la relance n'aura pas lieu.
TEMPLATE_ID_NO_CANTEEN_SECOND= Optionnel - ID du template SendInBlue pour le deuzième email envoyé aux utilisateurs n'ayant pas encore créé une cantine. En cas d'absence la relance n'aura pas lieu.
TEMPLATE_ID_NO_DIAGNOSTIC_FIRST= Optionnel - ID du template SendInBlue pour le premier email envoyé aux utilisateurs ayant une cantine mais pas un diagnostic. En cas d'absence la relance n'aura pas lieu.
Pour créer les tables nécessaires :
python manage.py migrate
Notez que cette commande est à effectuer à chaque changement de schema de la base de données.
Pour créer les fichiers compilés de traduction :
python manage.py compilemessages
Notez que cette commande est à effectuer à chaque changement de fichier de traduction *po.
Certaines fonctionnalités ont besoin de fichiers statics. La première fois que vous lancez le projet, d'abord lancez python manage.py collectstatic.
Deux options :
-
Le script
./local-build.shlance les trois commandes en parallel (Django, Vue2, Vue3). Faut pas avoir besoin de faire des migrations pour utiliser ça. -
Ouvrir trois terminales : une pour l'application Django, une pour l'application Vue2, et une pour l'application Vue3.
Il suffit de lancer la commande Django "runserver" à la racine du projet pour avoir le serveur de développement (avec hot-reload) :
python manage.py runserver
Pour faire l'équivalent côté frontend, allez sur ./frontend et lancez le serveur npm :
cd frontend
npm run serve
cd 2024-frontend
npm run dev
Une fois la compilation finie des trois côtés, l'application se trouvera sous 127.0.0.1:8000 (le port Django, non pas celui de npm).
On utilise l'outil pre-commit pour effectuer des vérifications automatiques
avant chaque commit. Cela permet par exemple de linter les code Python, Javascript et HTML.
Pour pouvoir l'utiliser, il faut installer pre-commit (en général plutôt de manière globable que dans
l'environnement virtuel) : pip install pre-commit.
Puis l'activer : pre-commit install.
Note : commande pour lancer les règles du pre-commit sur tous les fichiers : pre-commit run --all-files
Les vérifications seront ensuite effectuées avant chaque commit. Attention, lorsqu'une vérification fail,
le commit est annulé. Il faut donc que toutes les vérifications passent pour que le commit soit pris en
compte. Si exceptionnellement vous voulez commiter malgré qu'une vérification ne passe pas, c'est possible
avec git commit -m 'my message' --no-verify.
La commande pour lancer les tests Django est :
python manage.py test
Sur VSCode, ces tests peuvent être debuggés avec la configuration "Python: Tests", présente sur le menu "Run".
Il faut d'abord se placer sur "/frontend", ensuite la commande pour lancer les tests VueJS est :
cd frontend
npm run test
Afin de pouvoir s'identifier dans le backoffice (sous /admin), il est nécessaire de créer un utilisateur admin avec tous les droits. Pour ce faire, vous pouvez lancer :
python manage.py createsuperuser
Il y a deux options pour recevoir les emails envoyés depuis l'application en local :
Django permet d'imprimer en console les emails envoyés avec le django.core.mail.backends.console.EmailBackend. Pour l'utiliser il suffit de mettre la variable d'environnement EMAIL_BACKEND à cette valeur. Cette option est rapide à mettre en place et ne nécessite pas d'autres outils.
Il faut néanmoins tenir en compte que la mise en page ne sera pas visible et que certaines configurations qui marchent avec la console ne marchent pas avec d'autres services email. Nous conseillons plutôt d'utiliser la solution suivante :
Maildev est un outil ouvert qui exécute un serveur SMTP en local et qui permet de visualiser tous les emails traités. En l'installant de façon globale on peut mettre django.core.mail.backends.smtp.EmailBackend comme variable d'environnement EMAIL_BACKEND pour l'utiliser.
Celery est un gestionnaire de tâches asynchrone utilisé par exemple pour l'envoi périodique de courriels de rappel et pour le remplissage des donn
Pour staging/demo/prod, le chemin du fichier d'instantiation de Celery doit être spéficié dans la console CleverCloud sous la variable CC_PYTHON_CELERY_MODULE=macantine.celery. La fonctionnalité Celery Beat doit aussi être activée : CC_PYTHON_CELERY_USE_BEAT=true, ainsi que le timezone souhaité : CELERY_TIMEZONE='Europe/Paris'
- Démarrer le beat (gère les tâches régulières) celery
celery -A macantine beat --loglevel=INFO - Démarrer le worker celery
celery -A macantine worker --loglevel=INFO.
Des extensions utiles :
- Django
- EJS Beautify
- EJS langauge support
- ESLint
- Prettier - Code formatter
- Vue Language Features
- Vetur
- vuetify-vscode
- Spell Right
Les commandes lancées sur CleverCloud sont listées dans clevercloud/python.json.
.env :
DEBUG=False
DEBUG_FRONT=False
Dans le dossier principal, lancez :
bash ./clevercloud/test-build-with-vue3.sh
python manage.py runserver --insecure
En prod, faut ajouter CC_PRE_BUILD_HOOK=./clevercloud/pre-build-hook.sh
Vérification pre-déploiment
- est-ce que les tests passent sur staging ?
- est-ce que tout va bien côté Clever Cloud ?
- est-ce qu'il y a des cherry-picks sur main qui n'existent pas sur staging ?
Étapes :
- https://github.com/betagouv/ma-cantine/releases > "Draft a new release"
- "Choose a tag" > taper la date d'aujourd'hui en format YYYY-MM-DD > "Create a new tag on publish"
- "Generate release notes"
- Modifier les notes générés (indications ci-dessous)
- "Publish release"
- Si il y a des variables d'environnement à ajouter, ajoutez-les sur prod et demo côté Clever Cloud
- avec staging :
git pull - preparer la branche main en locale :
git checkout maingit rebase staging git push(peut-êtregit push -f)- Le déploiement va commencer automatiquement. Ça prend un moment pour déployer côté Clever Cloud, suivez la progression là-bas.
- Une fois que le déploiement est fait, envoyer un message sur mattermost canal produit pour tenir l'équipe au courant.
Vous pourrez modifier les notes dans un éditeur pour être plus rapide.
- supprimer toutes les lignes dependabot et les remplacer avec une ligne "MAJ dépendances"
- supprimer la partie "by @username in https://..."
- faire n'importe quel autre changement pour rendre la liste facilement comprensible par tout le monde
Si jamais vous doutez/si il y a un problème, parlez avec un.e autre dév.
C'est aussi possible de lancer le site avec Docker.
docker compose build
docker compose up
Dans un nouveau terminal, accèder au container du back pour migrer la BDD et créer la première utilisatrice.
docker compose run server bash
python manage.py migrate
python manage.py createsuperuser
Pour le formattage automatique de fichiers (prettier), faut avoir quelques dependences npm installé en locale.
Allez dans le dossier /frontend et /2024-frontend
sudo npm install --include=dev
J'ai du utiliser sudo car le dossier node_modules a été créé par l'image docker.