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

Fusionnée
zoe a fusionné 3 révision(s) à partir de fpoulain/benevalibre:develop vers develop 2022-06-17 15:55:26 +02:00
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
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

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:
```
```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