feat(doc): recalage du README sur le cookie cutter (#230)

Reviewed-on: #230
Co-authored-by: François Poulain <fpoulain@metrodore.fr>
Co-committed-by: François Poulain <fpoulain@metrodore.fr>

README.fr.md

@@ -13,18 +13,17 @@ gestion et la valorisation du bénévolat dans les associations.
 
 ## Essayer rapidement
 
-Sur une machine Debian, version Stretch ou ultérieure :
+Sur une machine Debian, version Buster ou ultérieure :
 
-```
+```shell
 $ sudo apt install python3 virtualenv git make
 $ git clone https://forge.cliss21.org/cliss21/benevalibre
 $ cd benevalibre/
 $ make init
+# Une configuration va être éditée intéractivement. Décommentez
+#  ENV=development
 
-Une configuration va être éditée intéractivement. Décommentez
-ENV=development
-
-$ make test # optionnel
+# $ make test # optionnel
 $ make serve
 ```
 
@@ -32,16 +31,15 @@ Visitez ensuite [http://127.0.0.1:8000/](http://127.0.0.1:8000/) dans votre
 navigateur web.
 
 ## Installation
-
 ### Pré-requis
 
 Sur une machine Debian, version Buster ou ultérieure, vous aurez besoin de :
-- python3
-- virtualenv
-- make
-- git (recommandée pour récupérer le source)
-- python3-mysqldb (optionnel, pour une base de données MySQL / MariaDB)
-- python3-psycopg2 (optionnel, pour une base de données PostgreSQL)
+- `python3`
+- `virtualenv`
+- `make`
+- `git` (recommandée pour récupérer le source)
+- `python3-mysqldb` (optionnel, pour une base de données MySQL / MariaDB)
+- `python3-psycopg2` (optionnel, pour une base de données PostgreSQL)
 
 ### Démarrage rapide
 
@@ -68,20 +66,25 @@ Vous pouvez aussi vérifier que l'application est bien configurée, en exécutan
 `make check`.
 
 ## Déploiement
+### Avec NginX et uWSGI
 
 Voici un exemple de configuration de déploiement pour NGINX en tant que serveur
 Web avec uWSGI en serveur d'application.
 
+#### uWSGI
+
 Le serveur uWSGI ne requiert aucune configuration spéciale, excepté qu'on
 utilise python3 et un virtualenv. Notez que si vous servez l'application
 dans un chemin sous la racine, vous aurez à ajouter `route-run = fixpathinfo:`
 à la configuration uWSGI (depuis
 [v2.0.11](https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action)).
 
+#### NGINX
+
 Dans le bloc `server` de la configuration NGINX, ajoutez le bloc suivant et
 définissez les chemins de l'installation et du socket uWGSI :
 
-```
+```nginx
 location / {
     include uwsgi_params;
     uwsgi_pass unix:<uwsgi_socket_path>;
@@ -101,6 +104,53 @@ location = /favicon.ico {
 }
 ```
 
+### Avec Apache et mod_wsgi
+
+Voici un exemple de configuration de déploiement pour Apache en tant que serveur
+Web.
+
+Le serveur uWSGI ne requiert aucune configuration spéciale, excepté qu'on
+utilise python3 et un virtualenv. Voyez par exemple [la documentation Django](
+https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/modwsgi/)
+pour approfondir.
+
+```apache
+    WSGIProcessGroup benevalibre
+    WSGIDaemonProcess benevalibre python-home=<app_instance_path>/venv/ python-path=<app_instance_path>/
+
+    WSGIScriptAlias / <app_instance_path>/benevalibre/wsgi.py process-group=benevalibre
+
+    <Directory <app_instance_path>/benevalibre/>
+        <Files wsgi.py>
+            Require all granted
+        </Files>
+    </Directory>
+
+    Alias /static/ <app_instance_path>/var/static/
+
+    <Directory <app_instance_path>/var/static/>
+        Require all granted
+    </Directory>
+
+    Alias /media/ <app_instance_path>/var/media/
+
+    <Directory <app_instance_path>/var/media/>
+        Require all granted
+    </Directory>
+
+    Alias /favicon.ico <app_instance_path>/var/static/favicon/favicon.ico
+```
+
+### Vérifier de nouvelles versions
+
+Une fois Bénévalibre déployé, vous pouvez vérifier la disponibilité de
+nouvelles version en utilisant :
+
+   $ ./manage.py check_update
+
+L'option `--warn` fera que le code de retour est différent de 0 si une version
+est disponible.
+
 ## Pour aller plus loin
 
 Consultez la [version anglaise](README.md) de cette aide pour plus de détails

README.md

@@ -16,48 +16,46 @@ volunteering management and appreciation in organizations.
 
 On a Debian-based host - running at least Debian Buster:
 
-```
+```shell
 $ sudo apt install python3 virtualenv git make
 $ git clone https://forge.cliss21.org/cliss21/benevalibre
 $ cd benevalibre/
 $ make init
+# A configuration file will be created interactively; you can uncomment:
+#  ENV=development
 
-A configuration will be created interactively; uncomment
-ENV=development
-
-$ make test # optional
+# $ make test # optional
 $ make serve
 ```
 
 Then visit [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your web browser.
 
 ## Installation
-
 ### Requirements
 
 On a Debian-based host - running at least Debian Stretch, you will need the
 following packages:
-- python3
-- virtualenv
-- make
-- git (recommended for getting the source)
-- python3-mysqldb (optional, in case of a MySQL / MariaDB database)
-- python3-psycopg2 (optional, in case of a PostgreSQL database)
+- `python3`
+- `virtualenv`
+- `make`
+- `git` (recommended for getting the source)
+- `python3-mysqldb` (optional, in case of a MySQL / MariaDB database)
+- `python3-psycopg2` (optional, in case of a PostgreSQL database)
 
 ### Quick start
 
 It assumes that you already have the application source code locally - the best
 way is by cloning this repository - and that you are in this folder.
 
-1.  Define your local configuration in a file named `config.env`, which can be
-    copied from `config.env.example` and edited to suits your needs.
+1. Define your local configuration in a file named `config.env`, which can be
+   copied from `config.env.example` and edited to suits your needs.
 
-    Depending on your environment, you will have to create your database and the
-    user at first.
+   Depending on your environment, you will have to create your database and the
+   user at first.
 
-2.  Run `make init`.
+2. Run `make init`.
 
-    Note that if there is no `config.env` file, it will be created interactively.
+   Note that if there is no `config.env` file, it will be created interactively.
 
 That's it! Your environment is now initialized with the application installed.
 To update it, once the source code is checked out, simply run `make update`.
@@ -65,61 +63,29 @@ To update it, once the source code is checked out, simply run `make update`.
 You can also check that your application is well configured by running
 `make check`.
 
-### Manual installation
-
-If you don't want to use the `Makefile` facilities, here is what is done behind the scene.
-
-It assumes that you have downloaded the last release of Bénévalibre,
-extracted it and that you moved to that folder.
-
-1.  Start by creating a new virtual environment under `./venv` and activate it:
-
-        $ virtualenv --system-site-packages ./venv
-        $ source ./venv/bin/activate
-
-2.  Install the required Python packages depending on your environment:
-
-        $ pip install -r requirements/production.txt
-        ... or ...
-        $ pip install -r requirements/development.txt
-
-3.  Configure the application by setting the proper environment variables
-    depending on your environment. You can use the `config.env.example` which
-    give you the main variables with example values.
-
-        $ cp config.env.example config.env
-        $ nano config.env
-        $ chmod go-rwx config.env
-
-    Note that this `./config.env` file will be loaded by default when the
-    application starts. If you don't want that, just move this file away or set
-    the `READ_CONFIG_FILE` environment variable to `0`.
-
-4.  Create the database tables - it assumes that you have created the database
-    and set the proper configuration to use it:
-
-        $ ./manage.py migrate
-
-That's it! You should now be able to start the Django development server to
-check that everything is working fine with:
-
-    $ ./manage.py runserver
-
 ## Deployment
+### Web application
+
+#### NginX with uWSGI
 
 Here is an example deployment using NGINX - as the Web server - and uWSGI - as
 the application server.
 
+##### uWSGI
+
 The uWSGI configuration doesn't require a special configuration, except that we
 are using Python 3 and a virtual environment. Note that if you serve the
 application on a sub-location, you will have to add `route-run = fixpathinfo:`
-to your uWSGI configuration (from
-[v2.0.11](https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action)).
+to your uWSGI configuration (available since [v2.0.11][1]).
+
+[1]: https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action
+
+##### NGINX
 
 In the `server` block of your NGINX configuration, add the following blocks and
 set the path to your application instance and to the uWSGI socket:
 
-```
+```nginx
 location / {
     include uwsgi_params;
     uwsgi_pass unix:<uwsgi_socket_path>;
@@ -139,6 +105,42 @@ location = /favicon.ico {
 }
 ```
 
+#### Apache with mod_wsgi
+
+Here is an example deployment using Apache as the Web server.
+
+The WSGI configuration doesn't require a special configuration, except that we
+are using Python 3 and a virtual environment. See e.g. [Django's docs](
+https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/modwsgi/)
+for more details.
+
+```apache
+    WSGIProcessGroup benevalibre
+    WSGIDaemonProcess benevalibre python-home=<app_instance_path>/venv/ python-path=<app_instance_path>/
+
+    WSGIScriptAlias / <app_instance_path>/benevalibre/wsgi.py process-group=benevalibre
+
+    <Directory <app_instance_path>/benevalibre/>
+        <Files wsgi.py>
+            Require all granted
+        </Files>
+    </Directory>
+
+    Alias /static/ <app_instance_path>/var/static/
+
+    <Directory <app_instance_path>/var/static/>
+        Require all granted
+    </Directory>
+
+    Alias /media/ <app_instance_path>/var/media/
+
+    <Directory <app_instance_path>/var/media/>
+        Require all granted
+    </Directory>
+
+    Alias /favicon.ico <app_instance_path>/var/static/favicon/favicon.ico
+```
+
 ### Checking for new releases
 
 Once you deployed Bénevalibre, you can check for new release using
@@ -151,9 +153,7 @@ Giving `--warn` option you get error code when a new release is available.
 ### Overview
 
 All the application files - e.g. Django code including settings, templates and
-statics - are located into the `benevalibre/`. It should
-permit in a near future to distribute the application as a Python package and
-install it system-wide.
+statics - are located into `benevalibre/`.
 
 Two environments are defined - either for requirements and settings:
 - `development`: for local application development and testing. It uses a