use .env for project configuration

2025-07-10 03:49:24 +00:00 · 2024-12-24 15:40:58 +01:00
parent 88b3f7c322
commit 41bff53853
11 changed files with 341 additions and 156 deletions
--- a/docs/tutorial/install-advanced.md
+++ b/docs/tutorial/install-advanced.md
@ -47,19 +47,19 @@ Commencez par installer les dépendances système :
    === "Debian/Ubuntu"

        ```bash
-        sudo apt install postgresql redis libq-dev nginx
+        sudo apt install postgresql libq-dev nginx
        ```

    === "Arch Linux"
    
        ```bash
-        sudo pacman -S postgresql redis nginx
+        sudo pacman -S postgresql nginx
        ```

 === "macOS"

    ```bash
-    brew install postgresql redis lipbq nginx
+    brew install postgresql lipbq nginx
    export PATH="/usr/local/opt/libpq/bin:$PATH"
    source ~/.zshrc
    ```
@ -77,34 +77,6 @@ uv sync --group prod
    C'est parce que ces dépendances compilent certains modules
    à l'installation.

-## Configurer Redis
-
-Redis est utilisé comme cache.
-Assurez-vous qu'il tourne :
-
-```bash
-sudo systemctl redis status
-```
-
-Et s'il ne tourne pas, démarrez-le :
-
-```bash
-sudo systemctl start redis
-sudo systemctl enable redis  # si vous voulez que redis démarre automatiquement au boot
-```
-
-Puis ajoutez le code suivant à la fin de votre fichier
-`settings_custom.py` :
-
-```python
-CACHES = {
-    "default": {
-        "BACKEND": "django.core.cache.backends.redis.RedisCache",
-        "LOCATION": "redis://127.0.0.1:6379",
-    }
-}
-```
-
 ## Configurer PostgreSQL

 PostgreSQL est utilisé comme base de données.
@ -139,26 +111,19 @@ en étant connecté en tant que postgres :
 psql -d sith -c "GRANT ALL PRIVILEGES ON SCHEMA public to sith";
 ```

-Puis ajoutez le code suivant à la fin de votre
-`settings_custom.py` :
+Puis modifiez votre `.env`.
+Dedans, décommentez l'url de la base de données
+de postgres et commentez l'url de sqlite :

-```python
-DATABASES = {
-    "default": {
-        "ENGINE": "django.db.backends.postgresql",
-        "NAME": "sith",
-        "USER": "sith",
-        "PASSWORD": "password",
-        "HOST": "localhost",
-        "PORT": "",  # laissez ce champ vide pour que le choix du port soit automatique
-    }
-}
+```dotenv
+#DATABASE_URL=sqlite:///db.sqlite3
+DATABASE_URL=postgres://sith:password@localhost:5432/sith
 ```

 Enfin, créez vos données :

 ```bash
-uv run ./manage.py populate
+uv run ./manage.py setup
 ```

 !!! note
@ -247,7 +212,7 @@ Puis lancez ou relancez nginx :
 sudo systemctl restart nginx
 ```

-Dans votre `settings_custom.py`, remplacez `DEBUG=True` par `DEBUG=False`.
+Dans votre `.env`, remplacez `DEBUG=true` par `DEBUG=false`.

 Enfin, démarrez le serveur Django :

--- a/docs/tutorial/install.md
+++ b/docs/tutorial/install.md
@ -7,6 +7,7 @@ Certaines dépendances sont nécessaires niveau système :
 - libjpeg
 - zlib1g-dev
 - gettext
+- redis

 ### Installer WSL

@ -65,8 +66,8 @@ cd /mnt/<la_lettre_du_disque>/vos/fichiers/comme/dhab
        
        ```bash
        sudo apt install curl build-essential libssl-dev \
-        libjpeg-dev zlib1g-dev npm libffi-dev pkg-config \
-        gettext git
+            libjpeg-dev zlib1g-dev npm libffi-dev pkg-config \
+            gettext git redis
        curl -LsSf https://astral.sh/uv/install.sh | sh
        ```

@ -75,7 +76,7 @@ cd /mnt/<la_lettre_du_disque>/vos/fichiers/comme/dhab
        ```bash
        sudo pacman -Syu  # on s'assure que les dépôts et le système sont à jour

-        sudo pacman -S uv gcc git gettext pkgconf npm
+        sudo pacman -S uv gcc git gettext pkgconf npm redis
        ```

 === "macOS"
@ -84,7 +85,7 @@ cd /mnt/<la_lettre_du_disque>/vos/fichiers/comme/dhab
    Il est également nécessaire d'avoir installé xcode
    
    ```bash    
-    brew install git uv npm
+    brew install git uv npm redis
    
    # Pour bien configurer gettext
    brew link gettext # (suivez bien les instructions supplémentaires affichées)
@ -99,6 +100,15 @@ cd /mnt/<la_lettre_du_disque>/vos/fichiers/comme/dhab
    Python ne fait pas parti des dépendances puisqu'il est automatiquement
    installé par uv.

+Parmi les dépendances installées se trouve redis (que nous utilisons comme cache).
+Redis est un service qui doit être activé pour être utilisé.
+Pour cela, effectuez les commandes :
+
+```bash
+sudo systemctl start redis
+sudo systemctl enable redis  # si vous voulez que redis démarre automatiquement au boot
+```
+
 ## Finaliser l'installation

 Clonez le projet (depuis votre console WSL, si vous utilisez WSL)
@ -120,20 +130,24 @@ uv run ./manage.py install_xapian
    de texte à l'écran.
    C'est normal, il ne faut pas avoir peur.

-Maintenant que les dépendances sont installées, nous
-allons créer la base de données, la remplir avec des données de test,
-et compiler les traductions.
-Cependant, avant de faire cela, il est nécessaire de modifier
-la configuration pour signifier que nous sommes en mode développement.
-Pour cela, nous allons créer un fichier `sith/settings_custom.py`
-et l'utiliser pour surcharger les settings de base.
+Une fois les dépendances installées, il faut encore
+mettre en place quelques éléments de configuration,
+qui peuvent varier d'un environnement à l'autre.
+Ces variables sont stockées dans un fichier `.env`.
+Pour le créer, vous pouvez copier le fichier `.env.example` :

 ```bash
-echo "DEBUG=True" > sith/settings_custom.py
-echo 'SITH_URL = "localhost:8000"' >> sith/settings_custom.py
+cp .env.example .env
 ```

-Enfin, nous pouvons lancer les commandes suivantes :
+Les variables par défaut contenues dans le fichier `.env`
+devraient convenir pour le développement, sans modification.
+
+Maintenant que les dépendances sont installées
+et la configuration remplie, nous allons pouvoir générer
+des données utiles pendant le développement.
+
+Pour cela, lancez les commandes suivantes :

 ```bash
 # Prépare la base de données
@ -171,6 +185,30 @@ uv run ./manage.py runserver
    [http://localhost:8000/api/docs](http://localhost:8000/api/docs),
    une interface swagger, avec toutes les routes de l'API.

+!!! question "Pourquoi l'installation est aussi complexe ?"
+
+    Cette question nous a été posée de nombreuses fois par des personnes
+    essayant d'installer le projet.
+    Il y a en effet un certain nombre d'étapes à suivre,
+    de paquets à installer et de commandes à exécuter.
+    
+    Le processus d'installation peut donc sembler complexe.
+
+    En réalité, il est difficile de faire plus simple.
+    En effet, un site web a besoin de beaucoup de composants
+    pour être développé : il lui faut au minimum
+    une base de données, un cache, un bundler Javascript
+    et un interpréteur pour le code du serveur.
+    Pour nos besoin particuliers, nous utilisons également
+    un moteur de recherche full-text.
+    
+    Nous avons tenté au maximum de limiter le nombre de dépendances
+    et de sélecionner les plus simples à installer.
+    Cependant, il est impossible de retirer l'intégralité
+    de la complexité du processus.
+    Si vous rencontrez des difficulté lors de l'installation,
+    n'hésitez pas à demander de l'aide.
+
 ## Générer la documentation

 La documentation est automatiquement mise en ligne à chaque envoi de code sur GitHub.
--- a/docs/tutorial/structure.md
+++ b/docs/tutorial/structure.md
@ -72,12 +72,14 @@ sith/
 ├── .gitattributes
 ├── .gitignore
 ├── .mailmap
-├── manage.py (26)
-├── mkdocs.yml (27)
+├── .env (26)
+├── .env.example (27)
+├── manage.py (28)
+├── mkdocs.yml (29)
 ├── uv.lock
-├── pyproject.toml (28)
-├── .venv/ (29)
-├── .python-version (30)
+├── pyproject.toml (30)
+├── .venv/ (31)
+├── .python-version (32)
 └── README.md
 ```
 </div>
@ -121,15 +123,19 @@ sith/
    de manière transparente pour l'utilisateur. 
 24. Fichier de configuration de coverage. 
 25. Fichier de configuration de direnv. 
-26. Fichier généré automatiquement par Django. C'est lui
+26. Contient les variables d'environnement, qui sont susceptibles
+    de varier d'une machine à l'autre.
+27. Contient des valeurs par défaut pour le `.env`
+    pouvant convenir à un environnment de développement local
+28. Fichier généré automatiquement par Django. C'est lui
    qui permet d'appeler des commandes de gestion du projet
    avec la syntaxe `python ./manage.py <nom de la commande>`
-27. Le fichier de configuration de la documentation,
+29. Le fichier de configuration de la documentation,
    avec ses plugins et sa table des matières. 
-28. Le fichier où sont déclarés les dépendances et la configuration
+30. Le fichier où sont déclarés les dépendances et la configuration
    de certaines d'entre elles.
-29. Dossier d'environnement virtuel généré par uv
-30. Fichier qui contrôle quel version de python utiliser pour le projet
+31. Dossier d'environnement virtuel généré par uv
+32. Fichier qui contrôle quelle version de python utiliser pour le projet
    

 ## L'application principale
@ -144,10 +150,9 @@ Il est organisé comme suit :
 ```
 sith/
 ├── settings.py (1)
-├── settings_custom.py (2)
-├── toolbar_debug.py (3)
-├── urls.py (4)
-└── wsgi.py (5)
+├── toolbar_debug.py (2)
+├── urls.py (3)
+└── wsgi.py (4)
 ```
 </div>

@ -155,13 +160,10 @@ sith/
   Ce fichier contient les paramètres de configuration du projet.
   Par exemple, il contient la liste des applications
   installées dans le projet.
-2. Configuration maison pour votre environnement.
-   Toute variable que vous définissez dans ce fichier sera prioritaire
-   sur la configuration donnée dans `settings.py`.
-3. Configuration de la barre de debug.
+2. Configuration de la barre de debug.
   C'est inutilisé en prod, mais c'est très pratique en développement.
-4. Fichier de configuration des urls du projet.
-5. Fichier de configuration pour le serveur WSGI.
+3. Fichier de configuration des urls du projet.
+4. Fichier de configuration pour le serveur WSGI.
   WSGI est un protocole de communication entre le serveur
   et les applications.
   Ce fichier ne vous servira sans doute pas sur un environnement