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>
pull/244/head
François Poulain 2022-06-17 15:55:25 +02:00 commité par Zoé Martin
Parent 94c3501e6e
révision 92454c0ab1
2 fichiers modifiés avec 128 ajouts et 78 suppressions

Voir le fichier

@ -13,18 +13,17 @@ gestion et la valorisation du bénévolat dans les associations.
## Essayer rapidement ## 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 $ sudo apt install python3 virtualenv git make
$ git clone https://forge.cliss21.org/cliss21/benevalibre $ git clone https://forge.cliss21.org/cliss21/benevalibre
$ cd benevalibre/ $ cd benevalibre/
$ make init $ make init
# Une configuration va être éditée intéractivement. Décommentez
# ENV=development
Une configuration va être éditée intéractivement. Décommentez # $ make test # optionnel
ENV=development
$ make test # optionnel
$ make serve $ make serve
``` ```
@ -32,16 +31,15 @@ Visitez ensuite [http://127.0.0.1:8000/](http://127.0.0.1:8000/) dans votre
navigateur web. navigateur web.
## Installation ## Installation
### Pré-requis ### Pré-requis
Sur une machine Debian, version Buster ou ultérieure, vous aurez besoin de : Sur une machine Debian, version Buster ou ultérieure, vous aurez besoin de :
- python3 - `python3`
- virtualenv - `virtualenv`
- make - `make`
- git (recommandée pour récupérer le source) - `git` (recommandée pour récupérer le source)
- python3-mysqldb (optionnel, pour une base de données MySQL / MariaDB) - `python3-mysqldb` (optionnel, pour une base de données MySQL / MariaDB)
- python3-psycopg2 (optionnel, pour une base de données PostgreSQL) - `python3-psycopg2` (optionnel, pour une base de données PostgreSQL)
### Démarrage rapide ### Démarrage rapide
@ -68,20 +66,25 @@ Vous pouvez aussi vérifier que l'application est bien configurée, en exécutan
`make check`. `make check`.
## Déploiement ## Déploiement
### Avec NginX et uWSGI
Voici un exemple de configuration de déploiement pour NGINX en tant que serveur Voici un exemple de configuration de déploiement pour NGINX en tant que serveur
Web avec uWSGI en serveur d'application. Web avec uWSGI en serveur d'application.
#### uWSGI
Le serveur uWSGI ne requiert aucune configuration spéciale, excepté qu'on Le serveur uWSGI ne requiert aucune configuration spéciale, excepté qu'on
utilise python3 et un virtualenv. Notez que si vous servez l'application utilise python3 et un virtualenv. Notez que si vous servez l'application
dans un chemin sous la racine, vous aurez à ajouter `route-run = fixpathinfo:` dans un chemin sous la racine, vous aurez à ajouter `route-run = fixpathinfo:`
à la configuration uWSGI (depuis à la configuration uWSGI (depuis
[v2.0.11](https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action)). [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 Dans le bloc `server` de la configuration NGINX, ajoutez le bloc suivant et
définissez les chemins de l'installation et du socket uWGSI : définissez les chemins de l'installation et du socket uWGSI :
``` ```nginx
location / { location / {
include uwsgi_params; include uwsgi_params;
uwsgi_pass unix:<uwsgi_socket_path>; 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 ## Pour aller plus loin
Consultez la [version anglaise](README.md) de cette aide pour plus de détails Consultez la [version anglaise](README.md) de cette aide pour plus de détails

128
README.md
Voir le fichier

@ -16,48 +16,46 @@ volunteering management and appreciation in organizations.
On a Debian-based host - running at least Debian Buster: On a Debian-based host - running at least Debian Buster:
``` ```shell
$ sudo apt install python3 virtualenv git make $ sudo apt install python3 virtualenv git make
$ git clone https://forge.cliss21.org/cliss21/benevalibre $ git clone https://forge.cliss21.org/cliss21/benevalibre
$ cd benevalibre/ $ cd benevalibre/
$ make init $ make init
# A configuration file will be created interactively; you can uncomment:
# ENV=development
A configuration will be created interactively; uncomment # $ make test # optional
ENV=development
$ make test # optional
$ make serve $ make serve
``` ```
Then visit [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your web browser. Then visit [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your web browser.
## Installation ## Installation
### Requirements ### Requirements
On a Debian-based host - running at least Debian Stretch, you will need the On a Debian-based host - running at least Debian Stretch, you will need the
following packages: following packages:
- python3 - `python3`
- virtualenv - `virtualenv`
- make - `make`
- git (recommended for getting the source) - `git` (recommended for getting the source)
- python3-mysqldb (optional, in case of a MySQL / MariaDB database) - `python3-mysqldb` (optional, in case of a MySQL / MariaDB database)
- python3-psycopg2 (optional, in case of a PostgreSQL database) - `python3-psycopg2` (optional, in case of a PostgreSQL database)
### Quick start ### Quick start
It assumes that you already have the application source code locally - the best 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. 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 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. copied from `config.env.example` and edited to suits your needs.
Depending on your environment, you will have to create your database and the Depending on your environment, you will have to create your database and the
user at first. 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. 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`. 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 You can also check that your application is well configured by running
`make check`. `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 ## Deployment
### Web application
#### NginX with uWSGI
Here is an example deployment using NGINX - as the Web server - and uWSGI - as Here is an example deployment using NGINX - as the Web server - and uWSGI - as
the application server. the application server.
##### uWSGI
The uWSGI configuration doesn't require a special configuration, except that we 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 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:` application on a sub-location, you will have to add `route-run = fixpathinfo:`
to your uWSGI configuration (from to your uWSGI configuration (available since [v2.0.11][1]).
[v2.0.11](https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action)).
[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 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: set the path to your application instance and to the uWSGI socket:
``` ```nginx
location / { location / {
include uwsgi_params; include uwsgi_params;
uwsgi_pass unix:<uwsgi_socket_path>; 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 ### Checking for new releases
Once you deployed Bénevalibre, you can check for new release using 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 ### Overview
All the application files - e.g. Django code including settings, templates and All the application files - e.g. Django code including settings, templates and
statics - are located into the `benevalibre/`. It should statics - are located into `benevalibre/`.
permit in a near future to distribute the application as a Python package and
install it system-wide.
Two environments are defined - either for requirements and settings: Two environments are defined - either for requirements and settings:
- `development`: for local application development and testing. It uses a - `development`: for local application development and testing. It uses a