From bb74b92a600bc4dc0d6200ccdb0bc733373211a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lien=20Amorin?= Date: Wed, 24 Jun 2026 09:27:37 +0200 Subject: [PATCH] Update project README --- README.md | 242 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 189 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index c8547803f7..fa4a2321df 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,213 @@ -## Résumé +# OC Lettings -Site web d'Orange County Lettings +OC Lettings est une application web Django permettant de consulter des locations immobilières et des profils utilisateurs. -## Développement local +Le projet a été refactorisé afin de passer d'une architecture monolithique à une architecture modulaire, puis conteneurisé, testé et déployé avec une chaîne CI/CD. + +## Liens + +- Application en production : https://oc-lettings-47nw.onrender.com/ +- Documentation : https://python-oc-lettings-fr-aurelien7777.readthedocs.io/fr/latest/ +- Dépôt GitHub : https://github.com/Aurelien7777/Python-OC-Lettings-FR + +## Fonctionnalités + +- consultation de la liste des locations ; +- consultation du détail d'une location ; +- consultation de la liste des profils ; +- consultation du détail d'un profil ; +- administration des données avec l'interface Django ; +- pages d'erreur personnalisées ; +- surveillance des erreurs avec Sentry. + +## Technologies + +- Python 3.7 ; +- Django 3.0 ; +- SQLite ; +- Gunicorn ; +- WhiteNoise ; +- Docker ; +- GitHub Actions ; +- Docker Hub ; +- Render ; +- Sentry ; +- Sphinx ; +- Read the Docs. + +## Architecture + +Le projet est organisé en trois composants principaux : + +- `oc_lettings_site` : configuration générale, page d'accueil et pages d'erreur ; +- `lettings` : gestion des adresses et des locations ; +- `profiles` : gestion des profils utilisateurs. + +## Installation locale ### Prérequis -- Compte GitHub avec accès en lecture à ce repository -- Git CLI -- SQLite3 CLI -- Interpréteur Python, version 3.6 ou supérieure +- Git ; +- Python 3.7 ; +- `pip` ; +- le module `venv`. + +### Cloner le dépôt + +```bash +git clone https://github.com/Aurelien7777/Python-OC-Lettings-FR.git +cd Python-OC-Lettings-FR +``` + +### Créer l'environnement virtuel + +Sous Windows : + +```powershell +py -3.7 -m venv venv +.\venv\Scripts\Activate.ps1 +``` + +Sous macOS ou Linux : + +```bash +python3.7 -m venv venv +source venv/bin/activate +``` + +### Installer les dépendances + +```bash +python -m pip install --upgrade pip +pip install -r requirements.txt +``` + +### Configurer les variables d'environnement + +Créer un fichier `.env` à la racine du projet : + +```env +SECRET_KEY=replace-with-a-local-secret-key +DEBUG=True +ALLOWED_HOSTS=localhost,127.0.0.1 +SENTRY_ENVIRONMENT=development +``` + +Pour activer Sentry localement : + +```env +SENTRY_DSN=replace-with-your-sentry-dsn +``` + +Le fichier `.env` ne doit pas être ajouté au dépôt Git. + +### Appliquer les migrations + +```bash +python manage.py migrate +``` + +### Lancer l'application + +```bash +python manage.py runserver +``` + +L'application est accessible à l'adresse suivante : + +http://127.0.0.1:8000/ + +## Administration + +Créer un compte administrateur : + +```bash +python manage.py createsuperuser +``` + +Puis ouvrir : + +http://127.0.0.1:8000/admin/ + +## Tests et qualité du code + +### Tests avec couverture + +```bash +coverage run manage.py test +coverage report --fail-under=80 +``` + +La CI exige une couverture minimale de 80 %. + +### Linting + +```bash +flake8 +``` + +## Docker + +### Construire l'image + +```bash +docker build -t oc-lettings:local . +``` + +### Lancer le conteneur sous PowerShell + +```powershell +docker run --rm -p 8000:8000 -e SECRET_KEY=django-insecure-local -e DEBUG=False -e ALLOWED_HOSTS=localhost,127.0.0.1 oc-lettings:local +``` -Dans le reste de la documentation sur le développement local, il est supposé que la commande `python` de votre OS shell exécute l'interpréteur Python ci-dessus (à moins qu'un environnement virtuel ne soit activé). +L'application est alors accessible à l'adresse suivante : -### macOS / Linux +http://127.0.0.1:8000/ -#### Cloner le repository +## CI/CD -- `cd /path/to/put/project/in` -- `git clone https://github.com/OpenClassrooms-Student-Center/Python-OC-Lettings-FR.git` +Le workflow GitHub Actions : -#### Créer l'environnement virtuel +1. exécute les tests Django avec `coverage` ; +2. vérifie que la couverture atteint au moins 80 % ; +3. exécute `flake8` ; +4. construit l'image Docker sur la branche `master` ; +5. publie l'image sur Docker Hub avec les tags `latest` et le SHA du commit ; +6. déclenche le déploiement sur Render. -- `cd /path/to/Python-OC-Lettings-FR` -- `python -m venv venv` -- `apt-get install python3-venv` (Si l'étape précédente comporte des erreurs avec un paquet non trouvé sur Ubuntu) -- Activer l'environnement `source venv/bin/activate` -- Confirmer que la commande `python` exécute l'interpréteur Python dans l'environnement virtuel -`which python` -- Confirmer que la version de l'interpréteur Python est la version 3.6 ou supérieure `python --version` -- Confirmer que la commande `pip` exécute l'exécutable pip dans l'environnement virtuel, `which pip` -- Pour désactiver l'environnement, `deactivate` +Image Docker de production : -#### Exécuter le site +```text +docker.io/aurelienamorin/oc-lettings:latest +``` -- `cd /path/to/Python-OC-Lettings-FR` -- `source venv/bin/activate` -- `pip install --requirement requirements.txt` -- `python manage.py runserver` -- Aller sur `http://localhost:8000` dans un navigateur. -- Confirmer que le site fonctionne et qu'il est possible de naviguer (vous devriez voir plusieurs profils et locations). +## Surveillance avec Sentry -#### Linting +Sentry centralise les erreurs rencontrées par l'application. -- `cd /path/to/Python-OC-Lettings-FR` -- `source venv/bin/activate` -- `flake8` +La configuration repose principalement sur les variables suivantes : -#### Tests unitaires +- `SENTRY_DSN` ; +- `SENTRY_ENVIRONMENT`. -- `cd /path/to/Python-OC-Lettings-FR` -- `source venv/bin/activate` -- `pytest` +L'option `send_default_pii` est désactivée afin de ne pas transmettre automatiquement les données personnelles des utilisateurs. -#### Base de données +## Documentation -- `cd /path/to/Python-OC-Lettings-FR` -- Ouvrir une session shell `sqlite3` -- Se connecter à la base de données `.open oc-lettings-site.sqlite3` -- Afficher les tables dans la base de données `.tables` -- Afficher les colonnes dans le tableau des profils, `pragma table_info(Python-OC-Lettings-FR_profile);` -- Lancer une requête sur la table des profils, `select user_id, favorite_city from - Python-OC-Lettings-FR_profile where favorite_city like 'B%';` -- `.quit` pour quitter +La documentation technique est générée avec Sphinx et publiée sur Read the Docs : -#### Panel d'administration +https://python-oc-lettings-fr-aurelien7777.readthedocs.io/fr/latest/ -- Aller sur `http://localhost:8000/admin` -- Connectez-vous avec l'utilisateur `admin`, mot de passe `Abc1234!` +Pour construire la documentation localement : -### Windows +```powershell +cd docs +.\make.bat clean +.\make.bat html +``` -Utilisation de PowerShell, comme ci-dessus sauf : +Les fichiers HTML sont générés dans : -- Pour activer l'environnement virtuel, `.\venv\Scripts\Activate.ps1` -- Remplacer `which ` par `(Get-Command ).Path` +```text +docs/build/html/ +```