Facilite la gestion et la valorisation du bénévolat dans les associations. https://benevalibre.org/
Go to file
Antoine bc99e0ca52 doc(CHANGELOG): publie la v1.6.1 2024-01-07 14:58:42 +01:00
artwork feat(artwork): ajoute la charte graphique et les logos définitifs 2019-07-26 15:47:56 +02:00
assets chore(lint): app.js 2023-01-27 16:03:13 +01:00
benevalibre doc(CHANGELOG): publie la v1.6.1 2024-01-07 14:58:42 +01:00
docs doc: expliquer comment exporter les données de benevalos 2022-12-02 10:55:24 +01:00
requirements fix(requirements): ajoute explicitement odfpy pour les exports 2024-01-07 14:46:04 +01:00
styleguide feat(ui): revois les composants et le guide selon la charte 2019-07-30 19:58:55 +02:00
.babelrc init(assets): ajoute les assets initialisés 2019-05-03 11:14:17 +02:00
.browserslistrc init(assets): ajoute les assets initialisés 2019-05-03 11:14:17 +02:00
.editorconfig init(assets): ajoute les assets initialisés 2019-05-03 11:14:17 +02:00
.eslintrc init(assets): ajoute les assets initialisés 2019-05-03 11:14:17 +02:00
.gitattributes init(assets): ajoute les assets initialisés 2019-05-03 11:14:17 +02:00
.gitignore feat(doc): ajout d'une infra de documentation, servie en ligne via django-docs 2019-07-17 09:43:14 +02:00
.stylelintrc feat(base): ajoute une page d'accueil pour les visiteurs 2019-08-06 16:17:01 +02:00
CHANGELOG.md doc(CHANGELOG): publie la v1.6.1 2024-01-07 14:58:42 +01:00
CONTRIBUTORS.txt Commit initial 2019-05-03 10:25:29 +02:00
LICENSE Commit initial 2019-05-03 10:25:29 +02:00
Makefile chore(Makefile): tests WorkInProgress 2023-06-18 11:28:40 +02:00
README.fr.md feat(doc): recalage du README sur le cookie cutter (#230) 2022-12-02 10:55:24 +01:00
README.md fix(requirements): mets à jour des dépendances 2024-01-07 12:07:08 +01:00
config.env.example feat(settings): possibilité de paramètrer la politique d'envoi des cookies (session et CSRF token) 2023-05-03 11:17:37 +02:00
gulpfile.js ref(stats): intègre chart.js dans les assets 2020-10-27 11:27:35 +01:00
manage.py Commit initial 2019-05-03 10:25:29 +02:00
package-lock.json chore(npm): maj package-lock.json 2023-10-26 11:24:33 +02:00
package.json fix(js): précise la version de node et npm 2023-10-26 11:24:01 +02:00
pyproject.toml style(python): ajoute black pour formatter le code 2019-06-01 17:09:42 +02:00
requirements.txt Commit initial 2019-05-03 10:25:29 +02:00
setup.cfg chore(Makefile): tests WorkInProgress 2023-06-18 11:28:40 +02:00



Bénévalibre is a free software which ease volunteering management and appreciation in organizations.

Table of content

Give a try

On a Debian-based host - running at least Debian Bullseye:

$ 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

# $ make test # optional
$ make serve

Then visit in your web browser.



On a Debian-based host - running at least Debian Bullseye, 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)

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.

    Depending on your environment, you will have to create your database and the user at first.

  2. Run make init.

    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.

You can also check that your application is well configured by running make check.


The following documentation is about manual deployment. If you prefer using Docker, check this image from Colibris.xyz.

Web application

NginX with uWSGI

Here is an example deployment using NGINX - as the Web server - and uWSGI - as the application server.


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 (available since v2.0.11).


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:

location / {
    include uwsgi_params;
    uwsgi_pass unix:<uwsgi_socket_path>;
location /media {
    alias <app_instance_path>/var/media;
location /static {
    alias <app_instance_path>/var/static;
    # Optional: don't log access to assets
    access_log off;
location = /favicon.ico {
    alias <app_instance_path>/var/static/favicon/favicon.ico;
    # Optional: don't log access to the favicon
    access_log off;

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 for more details.

    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

    Alias /static/ <app_instance_path>/var/static/

    <Directory <app_instance_path>/var/static/>
        Require all granted

    Alias /media/ <app_instance_path>/var/media/

    <Directory <app_instance_path>/var/media/>
        Require all granted

    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

$ ./manage.py check_update

Giving --warn option you get error code when a new release is available.



All the application files - e.g. Django code including settings, templates and statics - are located into benevalibre/.

Two environments are defined - either for requirements and settings:

  • development: for local application development and testing. It uses a SQLite3 database and enable debugging by default, add some useful settings and applications for development purpose - i.e. the django-debug-toolbar.
  • production: for production. It checks that configuration is set and correct, try to optimize performances and enforce some settings - i.e. HTTPS related ones.

Local changes

You can override and extend statics and templates locally. This can be useful if you have to change the logo for a specific instance for example. For that, just put your files under the local/static/ and local/templates/ folders.

Regarding the statics, do not forget to collect them after that. Note also that the local/ folder is ignored by git.

Variable content

All the variable content - e.g. user-uploaded media, collected statics - are stored inside the var/ folder. It is also ignored by git as it's specific to each application installation.

So, you will have to configure your Web server to serve the var/media/ and var/static/ folders, which should point to /media/ and /static/, respectively.


The easiest way to deploy a development environment is by using the Makefile.

Before running make init, ensure that you have either set ENV=development in the config.env file or have this environment variable. Note that you can still change this variable later and run make init again.

There is some additional rules when developing, which are mainly wrappers for manage.py. You can list all of them by running make help. Here are the main ones:

  • make serve: run a development server
  • make test: test the whole application
  • make lint: check the Python code syntax


The assets - e.g. CSS, JavaScript, images, fonts - are generated using a Gulp-powered build system with these features:

  • SCSS compilation and prefixing
  • JavaScript module bundling with webpack
  • Styleguide and components preview
  • Built-in BrowserSync server
  • Compression for production builds

The source files live in assets/, and the styleguide in styleguide/.


You will need to have npm installed on your system. If you are running Debian, do not rely on the npm package which is either outdated or removed - starting from Debian Stretch. Instead, here is a way to install the last version as a regular user:

  1. Ensure that you have the following Debian packages installed, from at least stretch-backports:

    • nodejs
    • node-rimraf
  2. Set the npm's installation prefix as an environment variable:

      $ export npm_config_prefix=~/.node_modules
  3. Retrieve and execute the last npm's installation script:

      $ curl -L https://www.npmjs.com/install.sh | sh
  4. Add the npm's binary folder to your environment variables:

    $ export PATH="${HOME}/.node_modules/bin:${PATH}"

    In order to keep those environment variables the next time you will log in, you can append the following lines to the end of your ~/.profile file:

    if [ -d "${HOME}/.node_modules/bin" ] ; then
        export npm_config_prefix=~/.node_modules
  5. That's it! You can check that npm is now installed by running the following:

    $ npm --version


Start by installing the application dependencies - which are defined in package.json - by running: npm install.

The following tasks are then available:

  • npm run build: build all the assets for development and production use, and put them in the static folder - e.g benevalibre/static.
  • npm run styleguide: run a server with the styleguide and watch for file changes.
  • npm run serve: run a proxy server to the app - which must already be served on localhost:8000 - with the styleguide on /styleguide and watch for file changes.
  • npm run lint: lint the JavaScript and the SCSS code.

In production, only the static files will be used. It is recommended to commit the compiled assets just before a new release only. This will prevent to have a growing repository due to the minified files.


Before releasing one should verify that make test and make lint are ok. Migrations should also have been added during development process.

Hygienic checklist

    make test
    make lint
    npm run lint
    make check-migrations
    git grep '\<print\s*(\|pdb\>\|\<set_trace\>' '*.py'

Release gitmnastic

  1. Define variables

     export VERSION="x.y.z"     # version to be released
     export ORIGIN="origin"     # remote name for pushing my origin
     export UPSTREAM="cliss21"  # remote name for pushing upstream
     export GITEA_USER="jdoe"   # my forge username
  2. Fork from the develop branch:

     git checkout -b release_$VERSION
  3. Build and commit statics

     npm run build
     git add -f benevalibre/static package-lock.json
     git commit -m "build($VERSION): ajoute les statics compilés"
  4. Update benevalibre/__init__.py and complete changelog via:

     make release
  5. Edit and commit it

     /usr/bin/editor CHANGELOG.md
     git add benevalibre/__init__.py CHANGELOG.md
     git commit -m "doc(CHANGELOG): publie la v$VERSION"
  6. Tag your release commit

     git tag v$VERSION
  7. Merge it in master

     git push --set-upstream $ORIGIN release_$VERSION
     git push --tags
     # then open a PR via
     xdg-open "https://forge.cliss21.org/cliss21/benevalibre/compare/master...$GITEA_USER:release_$VERSION"
     # then get the PR merged
     git push --tags $UPSTREAM

That's released. Now we prepare repo for a new develop sprint

  1. Rebase develop on master

     git fetch --all
     git checkout develop
     git rebase $UPSTREAM/master
  2. Revert statics from develop

     git revert $(git rev-list --all --max-count=1 benevalibre/static/)
     git push $ORIGIN
     # then open a PR or not
     xdg-open "https://forge.cliss21.org/cliss21/benevalibre/compare/develop...$GITEA_USER:develop"
     # then get the PR merged (or directly push via git push $UPSTREAM)
  3. You should be ready for a new develop sprint

     git fetch --all


Bénévalibre is developed by Cliss XXI and licensed under the AGPLv3+.