From 68c1a76769a0a81f6b8f7bf5baa57f051bdec4b3 Mon Sep 17 00:00:00 2001 From: Vincent Jousse Date: Fri, 11 Apr 2025 09:15:36 +0200 Subject: [PATCH] docs: improve README and default config --- README.md | 86 ++++++++++++++++++++++++++++------------------------- env.example | 4 +-- 2 files changed, 47 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 5e36b7d..9aabc9c 100644 --- a/README.md +++ b/README.md @@ -4,78 +4,82 @@ L'agenda culturel est un projet django créé à partir de [Django Docker Quicks Une instance de démonstration est disponible à l'adresse https://pommesdelune.fr/. -Parmi les outils et ressources sur lesquelles s'appuie l'agenda culturel, on peut lister: +Parmi les outils et ressources sur lesquelles s'appuie l'agenda culturel, on peut lister : -* [Django](https://www.djangoproject.com/) -* [redis](https://redis.io/) -* [celery](https://docs.celeryq.dev/en/stable/) -* [Selenium](https://www.selenium.dev/) -* [Feather icons](https://feathericons.com/) -* [Pico CSS](https://picocss.com/) +- [Django](https://www.djangoproject.com/) +- [redis](https://redis.io/) +- [celery](https://docs.celeryq.dev/en/stable/) +- [Selenium](https://www.selenium.dev/) +- [Feather icons](https://feathericons.com/) +- [Pico CSS](https://picocss.com/) ## Installation -Pour installer une version de développement, reportez-vous à la documentation de [Django Docker Quickstard](https://github.com/godd0t/django-docker-quickstart/). En résumé: +Pour installer une version de développement, reportez-vous à la documentation de [Django Docker Quickstard](https://github.com/godd0t/django-docker-quickstart/). En résumé : -* ```git pull``` -* ```make build-dev``` +- `git pull` +- `cp env.example .env` +- `make build-dev` -On peut aussi peupler les catégories avec un choix de catégories élémentaires: +Vous devriez ensuite pouvoir accéder au site local via http://localhost:8000. -* ```make create-categories``` +On peut aussi peupler les catégories avec un choix de catégories élémentaires : -On peut aussi peupler les positions de référence qui serviront aux recherches géographiques avec la commande, après avoir éventuellement modifié le fichier [communes.json](./src/scripts/communes.json) qui contient pour l'exemple toutes les communes récupérées depuis [public.opendatasoft.com](https://public.opendatasoft.com/explore/dataset/georef-france-commune/export/?flg=fr-fr&disjunctive.reg_name&disjunctive.dep_name&disjunctive.arrdep_name&disjunctive.ze2020_name&disjunctive.bv2022_name&disjunctive.epci_name&disjunctive.ept_name&disjunctive.com_name&disjunctive.ze2010_name&disjunctive.com_is_mountain_area&sort=year&refine.dep_name=Puy-de-D%C3%B4me&location=9,45.51597,3.05969&basemap=jawg.light): +- `make create-categories` -* ```make create-reference-locations``` +On peut aussi peupler les positions de référence qui serviront aux recherches géographiques avec la commande, après avoir éventuellement modifié le fichier [communes.json](./src/scripts/communes.json) qui contient pour l'exemple toutes les communes récupérées depuis [public.opendatasoft.com](https://public.opendatasoft.com/explore/dataset/georef-france-commune/export/?flg=fr-fr&disjunctive.reg_name&disjunctive.dep_name&disjunctive.arrdep_name&disjunctive.ze2020_name&disjunctive.bv2022_name&disjunctive.epci_name&disjunctive.ept_name&disjunctive.com_name&disjunctive.ze2010_name&disjunctive.com_is_mountain_area&sort=year&refine.dep_name=Puy-de-D%C3%B4me&location=9,45.51597,3.05969&basemap=jawg.light) : -Une fois l'installation réussie, la configuration du site est possible en allant modifier l'objet "Configuration du site" (```siteconfiguration```) dans l'administration de django. Il est également nécessaire (pas encore d'unification des deux facettes) de configurer un site (```Site```) en choisissant un nom et une url (nécessaire notamment pour le sitemap). +- `make create-reference-locations` + +Une fois l'installation réussie, la configuration du site est possible en allant modifier l'objet "Configuration du site" (`siteconfiguration`) dans l'administration de django. Il est également nécessaire (pas encore d'unification des deux facettes) de configurer un site (`Site`) en choisissant un nom et une url (nécessaire notamment pour le sitemap). ## Utilisation d'un proxy socket On peut activer à la main (pour l'instant) un proxy type socket pour l'import d'événements. -* se connecter au docker du celery worker : ```docker exec -it agenda_culturel-celery-worker bash``` -* mettre à jour les dépôts ```apt update``` -* installer le client ssh ```apt install ssh-client``` -* créer un socket ssh ```ssh -D 12345 USER@HOST``` -* modifier le drapeau proxy dans le constructeur de [downloader.py](src/agenda_culturel/import_tasks/downloader.py). +- se connecter au docker du celery worker : `docker exec -it agenda_culturel-celery-worker bash` +- mettre à jour les dépôts `apt update` +- installer le client ssh `apt install ssh-client` +- créer un socket ssh `ssh -D 12345 USER@HOST` +- modifier le drapeau proxy dans le constructeur de [downloader.py](src/agenda_culturel/import_tasks/downloader.py). ## Notes aux développeurs -Pour bénéficier de la vérification du code avant commit, installer ```pre-commit``` avec la commande ```pre-commit install``` pour bénéficier du hook préparé dans ```.pre-commit-config.yaml```. +Pour bénéficier de la vérification du code avant commit, installer `pre-commit` avec la commande `pre-commit install` pour bénéficier du hook préparé dans `.pre-commit-config.yaml`. -### Ajout d'une nouvelle source *custom* +### Ajout d'une nouvelle source _custom_ -Pour ajouter une nouvelle source custom: -- ajouter un fichier dans ```src/agenda_culturel/import_tasks/custom_extractors``` (ou ```src/agenda_culturel/import_tasks/generic_extractors``` s'il s'agit d'un format de source qui est réutilisable) en s'inspirant des autres fichiers présents. Il existe de nombreuses facilités dans les classes mères correspondantes -- s'inspirer des scripts présents dans ```experimentations/``` pour créer son propre script de test -- quand l'import fonctionne de manière indépendante dans ces expérimentations, il est tant de l'ajouter au site internet: - - ajouter à la classe ```RecurrentImport.PROCESSOR``` présente dans le fichier ```src/agenda_culturel/models.py``` une entrée correspondant à cette source pour qu'elle soit proposée aux utilisateurs - - ajouter à la fonction ```run_recurrent_import``` présente dans le fichier ```src/agenda_culturel/celery.py``` le test correspondant à cet ajout, pour lancer le bon extracteur +Pour ajouter une nouvelle source custom : + +- ajouter un fichier dans `src/agenda_culturel/import_tasks/custom_extractors` (ou `src/agenda_culturel/import_tasks/generic_extractors` s'il s'agit d'un format de source qui est réutilisable) en s'inspirant des autres fichiers présents. Il existe de nombreuses facilités dans les classes mères correspondantes +- s'inspirer des scripts présents dans `experimentations/` pour créer son propre script de test +- quand l'import fonctionne de manière indépendante dans ces expérimentations, il est tant de l'ajouter au site internet : + - ajouter à la classe `RecurrentImport.PROCESSOR` présente dans le fichier `src/agenda_culturel/models.py` une entrée correspondant à cette source pour qu'elle soit proposée aux utilisateurs + - ajouter à la fonction `run_recurrent_import` présente dans le fichier `src/agenda_culturel/celery.py` le test correspondant à cet ajout, pour lancer le bon extracteur - se rendre sur le site, page administration, et ajouter un import récurrent correspondant à cette nouvelle source ### Récupérer un dump du prod sur un serveur dev -* sur le serveur de prod: - * ```docker exec -i agenda_culturel-backend python3 manage.py dumpdata --natural-foreign --natural-primary --format=json --exclude=admin.logentry --indent=2 > fixtures/postgres-backup-20241101.json``` (à noter qu'ici on oublie les comptes, qu'il faudra recréer) -* sur le serveur de dev: - * On récupère le dump json ```scp $SERVEUR:$PATH/fixtures/postgres-backup-20241101.json src/fixtures/``` - * ```scripts/reset-database.sh FIXTURE COMMIT``` où ```FIXTURE``` est le timestamp dans le nom de la fixture, et ```COMMIT``` est l'ID du commit git correspondant à celle en prod sur le serveur au moment de la création de la fixture +- sur le serveur de prod : + - `docker exec -i agenda_culturel-backend python3 manage.py dumpdata --natural-foreign --natural-primary --format=json --exclude=admin.logentry --indent=2 > fixtures/postgres-backup-20241101.json` (à noter qu'ici on oublie les comptes, qu'il faudra recréer) +- sur le serveur de dev : + - On récupère le dump json `scp $SERVEUR:$PATH/fixtures/postgres-backup-20241101.json src/fixtures/` + - `scripts/reset-database.sh FIXTURE COMMIT` où `FIXTURE` est le timestamp dans le nom de la fixture, et `COMMIT` est l'ID du commit git correspondant à celle en prod sur le serveur au moment de la création de la fixture -On peut ensuite modifier le mot de passe de l'utilisateur root qui a tous les droits: +On peut ensuite modifier le mot de passe de l'utilisateur root qui a tous les droits : -* ```docker exec -it agenda_culturel-backend python3 manage.py changepassword root``` +- `docker exec -it agenda_culturel-backend python3 manage.py changepassword root` -À noter que les images ne sont pas récupérées. Les images des catégories peuvent être récupérées par la commande: +À noter que les images ne sont pas récupérées. Les images des catégories peuvent être récupérées par la commande : -* ```cp src/agenda_culturel/migrations/images/* src/media/``` +- `cp src/agenda_culturel/migrations/images/* src/media/` -Si la migration de la base de données s'est bien executée, mais qu'aucun événement n'est affiché sur l'interface utilisateur, il faut vider le cache côté administration : +Si la migration de la base de données s'est bien executée, mais qu'aucun événement n'est affiché sur l'interface utilisateur, il faut vider le cache côté administration : -* Page _Administrer_ > dans le menu sur la droite nommé _Administration_ > _Configuration interne_ > _Vider le cache_. +- Page _Administrer_ > dans le menu sur la droite nommé _Administration_ > _Configuration interne_ > _Vider le cache_. [Ou en utilisant ce lien direct](http://localhost:8008/cache/clear). (en étant connecté avec les droits suffisants) ### Complètement réinitialiser une instance -* ```docker compose down --rmi all --volumes``` -* ```make build-dev``` +- `docker compose down --rmi all --volumes` +- `make build-dev` diff --git a/env.example b/env.example index 6699e45..8d3f633 100644 --- a/env.example +++ b/env.example @@ -1,11 +1,11 @@ # Application configuration variables -APP_NAME=project_name +APP_NAME=agenda_culturel APP_HOST=0.0.0.0 APP_PORT=8000 SECRET_KEY='ur secret key' APP_ENV='dev' # Could be dev, prod or test DEBUG=True -ALLOWED_HOSTS='app.backend.dev' +ALLOWED_HOSTS='app.backend.dev,localhost' CSRF_TRUSTED_ORIGINS='https://*.backend.dev' CORS_ALLOWED_ORIGINS=http://app.backend.dev,http://localhost:3000