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
commit
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
|
||||
|
||||
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
128
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue