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
Parent
94c3501e6e
révision
92454c0ab1
78
README.fr.md
78
README.fr.md
|
@ -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
128
README.md
|
@ -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
|
||||||
|
|
Chargement…
Référencer dans un nouveau ticket