Plate-forme parlementaire d'échange de documents
Go to file
Emmanuel Cazenave 42e5b05fb4
gitea/docbow/pipeline/head This commit looks good Details
setup: compute pep440 compliant dirty version number (#81731)
2024-03-28 14:06:29 +01:00
debian misc: move bs4 dependency so setup.py (#87483) 2024-02-27 15:40:35 +01:00
docbow_project uwsgi: set DJANGO_SETTINGS_MODULE in environment (#87539) 2024-02-27 17:55:56 +01:00
help/fr doc: remove password change instructions from pfwb (#34086) 2019-06-18 10:49:31 +02:00
tests admin: prevent too big join by get_search_results (#80932) 2024-02-27 14:05:40 +01:00
.coveragerc jenkins: show execution context in coverage reports (#60446) 2022-01-11 16:24:17 +01:00
.git-blame-ignore-revs ci: add pre-commit changes to .git-blame-ignore-revs·(#86370) 2024-02-01 11:26:26 +01:00
.gitignore gitignore: add default dev db and virtualenv 2013-06-27 12:35:13 +02:00
.pre-commit-config.yaml ci: update tox.ini & precommit hooks & compatibility py311 (#86370) 2024-01-31 18:49:10 +01:00
COPYING add notices about distributed files not under the EO copyright 2012-02-10 15:54:43 +01:00
Jenkinsfile ci: build deb package for bookworm (#78968) 2023-06-23 17:29:12 +02:00
MANIFEST.in packaging: add svg static files (#47971) 2020-10-22 17:05:12 +02:00
README.rst remove rfc3161 timestamping (#42352) 2020-05-04 13:59:26 +02:00
benchmark ci: apply pre-commit hooks (#86370) 2024-01-31 18:49:23 +01:00
docbow-ctl ci: apply pre-commit hooks (#86370) 2024-01-31 18:49:23 +01:00
getlasso3.sh run tests in python 3 (#40572) 2020-06-03 15:07:27 +02:00
getm2crypto.sh jenkins.sh: use m2crypto from underlying platform 2016-03-11 11:43:52 +01:00
load-base-data.sh simplify settings, remove log application, add development scripts 2013-06-25 13:53:39 +02:00
local_settings.py.example local_settings.py.example: comment out email backend settings 2013-06-25 13:53:39 +02:00
manage.py misc: apply double-quote-string-fixer (#79788) 2023-08-16 11:52:29 +02:00
mellon_settings.py ci: fix remaining ruff warnings (#86370) 2024-01-31 19:05:16 +01:00
merge-junit-results.py ci: apply pre-commit hooks (#86370) 2024-01-31 18:49:23 +01:00
run.sh make run.sh cwd blind 2013-08-15 15:14:26 +02:00
setup.py setup: compute pep440 compliant dirty version number (#81731) 2024-03-28 14:06:29 +01:00
start.sh Ignore guest users when looking up user in sendmail command 2014-09-03 09:42:52 +02:00
test-requirements.txt misc: move bs4 dependency so setup.py (#87483) 2024-02-27 15:40:35 +01:00
tox.ini tests: add non regression test on search filter SQL query (#80932) 2024-02-27 14:05:40 +01:00

README.rst

Document box for the Wallon Parliement
======================================

This software is a web application allowing group of people to send files to
each other and to list of them. It distributes and timestamps the sent
documents. The timestamp is a cryptographic timestamp obtained using the
RFC3161 protocol.

The application is pre-configured to run with a postgresql database named
docbow. The user running the application need access to this database. On most
Unix system it means creating a postgresql user with the same name as the Unix
user it the database server runs on the same host.

Installation for developpers
----------------------------

 - First run:

   ./start.sh

 - and next times:

   ./run.sh

 - To update dependencies in the virtualenv environment rerun ./start.sh

Installation
------------

 - Create a virtualenv::

     virtualenv --no-site-packages env/

 - Activate it::

     . ./env/bin/activate 

 - Install dependencies (some dependencies require to compile C code, like
   python-ldap, for them you will some developement package installed, on
   Debian, it means gcc, python-dev, libssl-dev, libldap-dev, libsasl2-dev,
   libpq-dev)::
     ./getlasso.sh
     pip install -e .

 - Create user and database (you can replace $USER by www-data for a WSGI
   installation)::

     sudo -u postgres createuser $USER
     sudo -u postgres createdb -O $USER docbow

 - Fill in your local settings
   Rename locale_settings.py.example to local_settings.py, and fill it
   with appropriate database informations (standard Django settings.py file like)
   Also put DEBUG to True or set the SECRET_KEY

 - Create database schema and load initial data::

      docbow-ctl syncdb
      docbow-ctl loaddata content filetype groups

 - Compile UI strings translations::

     docbow-ctl makemessages --all
     docbow-ctl compilemessages

 - Load user list (you need to get a user list as a CSV files, see format later)::

     ( cd docbow_project; docbow-ctl load-users-csv users.csv )

Upgrading
---------

When you upgrade you must execute this from the root directory:

     ( cd docbow_project; docbow-ctl syncdb --migrate )

if you application run as another user (www-data for example if using WSGI)::

     ( cd docbow_project; sudo -u www-data docbow-ctl syncdb --migrate )

Installation on Debian with Apache2/mod_wsgi
--------------------------------------------

First install some development libraries::

     sudo apt-get install gcc libldap-dev libsasl2-dev python-dev libssl-dev libpq-dev swig gettext

Now you can follow the generic installation described before.

Collect all static content::

    (cd docbow_project; docbow-ctl collectstatic)

After that you must install apache2 and the mod_wsgi module. On Debian do::

     sudo apt-get install apache2 libapache2-mod-wsgi

You must configure the apache2 script to launch with an UTF-8 locale. On debian
you can add the following line to /etc/default/apache2 (supposing you have the
french locale with UTF-8 encoding compiled)::

     ENV="$ENV LANG=fr_FR.UTF-8 LC_ALL=fr_FR.UTF-8"

Then you must add a virtual host configuration which target the docbow wsgi
script. On debian you can put the following content in
/etc/apache2/sites-enabled/docbow.example.com, do not forget to replace
<docbow_src_dir> by the source directory where docbow is installed::

     <VirtualHost *:80>
     ServerName docbow.example.com
     
     Alias /static <docbow_src_dir>/static
     WSGIScriptAlias / <docbow_src_dir>/docbow.wsgi
     RedirectMatch 404 ^/favicon.ico$
     
     </VirtualHost>

Then you must activate it with the commands::

     a2ensite docbow.example.com
     /etc/init.d/apache2 reload

Installation on Debian using gunicorn and apache2
-------------------------------------------------

First install some development libraries::

     apt-get install gcc libldap-dev libsasl2-dev python-dev libssl-dev libpq-dev swig gettext

Now you can follow the generic installation described before.

Install gunicorn::

     ./env/bin/pip install gunicorn

Collect all static content::

    (cd docbow_project; docbow-ctl collectstatic)

After that you must install apache2 and the mod_wsgi module. On Debian do::

     sudo apt-get install apache2

Then you must add a virtual host configuration which target the gunicorn
application server. On debian you can put the following content in
/etc/apache2/sites-enabled/docbow.example.com, do not forget to replace
<docbow_src_dir> by the source directory where docbow is installed::

     <VirtualHost *:80>
     ServerName docbow.example.com

     DocumentRoot /var/www
     ProxyPass /static !
     ProxyPass / http://localhost:8000/
     ProxyPreserveHost on
     Alias /static <docbow_src_dir>/static
     <Proxy *>
     Order Deny,Allow
     Allow from all
     </Proxy>
     </VirtualHost>

Now run the gunicorn server (it must run as an user which has access to the
docbow postgresql database)::

     LANG=C.UTF-8 PYTHONPATH=. gunicorn_django -D ./docbow_project/

You must set a charset to use as file are created with name recevied from user
agents which can contain any unicode character. The locale "C.UTF-8" works in
this case.

Configuring main menu
---------------------

To configure the main menu you can setup the DOCBOW_MENU variable in your
`local_settings.py` file. The default setting is: ::

    DOCBOW_MENU = [
            ('send-file', gettext_noop('send-file_menu')),
            ('inbox', gettext_noop('inbox_menu')),
            ('outbox', gettext_noop('outbox_menu')),
            ('docbow_admin:index', gettext_noop('admin_menu')),
            ('profile', gettext_noop('profile_menu')),
            ('auth_password_change', gettext_noop('password_change_menu')),
            ('delegate', gettext_noop('delegate_menu')),
            ('mailing-lists', gettext_noop('mailing-lists')),
            ('help', gettext_noop('help_menu')),
            ('contact', gettext_noop('contact_menu')),
            ]

The first element of each pair must be a django view name of an URL, the second
one is potentially localized, for example to add a link to google, add this line::

            ('http://google.com/', u'Google'),

Settings
--------

All settings must be donne in the file ``/etc/docbow/local_settings.py``. Available settings are:

 * ``DOCBOW_ORGANIZATION``: an unicode string giving a description of the
   organization providing the platform. It's used as a signature in mail and
   sms notifications.
 * ``DOCBOW_BASE_URL``: the base URL of the application. It's used for building
   URL in notifications, emails or SMS.
 * ``DOCBOW_MENU``: description of the left column menu; see previous section
   for a description and the default value.
 * ``DOCBOW_MAILBOX_PER_PAGE``: the number of message to show on listing pages.
   Default is 20.
 * ``RAVEN_CONFIG_DSN``: the URL of the sentry project for gathering exceptions.
 * ``DOCBOW_MAX_FILE_SIZE``: the maximum file size for attached files, as
   bytes. Default is 10 Mo.
 * ``DOCBOW_TRUNCATE_FILENAME``: the maximum length for filenames. Default is
   80 unicode characters (codepoints).
 * ``DOCBOW_PERSONAL_EMAIL``: allow user to have a personal email,
   notifications will be sent to their institutional email and personal email.
 * ``DOCBOW_MOBILE_PHONE``: allow user to set a mobile phone number
   to receive notification by SMS.
 * ``GROUP_LISTING``: whether to show the link to the list of
   mailing lists in the left menu.
 * ``DOCBOW_PRIVATE_DOCUMENTS``: add a private checkbox to the sending form,
   when checked the document is only display to direct recipients and not to
   delegates,

Customizing templates
---------------------

You can override any template by copying it from
``docbow_project/docbow/templates/`` to ``/var/lib/docbow/templates/`` and then
modifying it. If you want to provide static ressources you can put them in
``/var/lib/docbow/extra_static/`` and update the static files cache with: ::

   ./docbow-ctl collectstatic

Sending a file from the command line
------------------------------------

The ``sendfile`` command is used to send a file from the command line. Basic
usage is::


  ./docbow-ctl sendfile --sender bdauvergne --to-user pcros --to-list liste1 \
      --description "New question" file1 file2

The sender and filetype parameters are mandatory. There must be at least one
recipient, list or user, and one file attached to the sending.

Listing users from the command line
-----------------------------------

The ``list-users`` command is used to list the user registerd in docbow. The
default output format is an ASCII table. You can ask for CSV output using the
``--csv`` parameter.

Example output::

|  Id |     Username | First name | Last name |               Email | Mobile phone |   Personal mail |       Lists |          Groups |
| 502 |        test3 |     Thomas |      Noël |       bob@gmail.com |              |                 | Liste test2 |                 |
| 503 | bdauvergne-1 |   benjamin | dauvergne |      test@gmail.com |              |                 |             |                 |
| 501 |        test2 |      Kévin |   Gaspard |     test2@gmail.com |              |                 | Liste test1 |                 |
| 504 |          503 |            |           |    toto@example.com |              |                 |             |                 |
| 444 |         test |     Jérôme | Schneider |  john.doe@gmail.com |              |                 | Liste test1 |                 |
|  98 |   bdauvergne |   Benjamin | Dauvergne | coin@entrouvert.com | +33630XXX893 | joe@example.com |             | Administrateurs |

The command supports a minimal query language, for example to get all users in
the group ``Administrator`` ::


  ./docbow-ctl list-users groups__name=Administrator

Listing lists from the command line
-----------------------------------

The ``list-lists`` command provide exactly the same service as ``list-users``
but for mailing lists.

Example output::

| Id |        Name |     Members | List Members |
| 54 | Liste test1 |             |   test,test2 |
| 55 | Liste test2 | Liste test1 |        test3 |
| 56 |  List test1 |             |              |

Adding users from the command line
----------------------------------

The ``add-user`` create a new user or modify an existing user. The username can
only be set at creation.::

  Usage: ./docbow-ctl add-user [options] <username>

  Create a new user or update an existing user

  List and groups can be referred by name or by id.
      

  Options:
    -v VERBOSITY, --verbosity=VERBOSITY
                          Verbosity level; 0=minimal output, 1=normal output,
                          2=verbose output, 3=very verbose output
    --settings=SETTINGS   The Python path to a settings module, e.g.
                          "myproject.settings.main". If this isn't provided, the
                          DJANGO_SETTINGS_MODULE environment variable will be
                          used.
    --pythonpath=PYTHONPATH
                          A directory to add to the Python path, e.g.
                          "/home/djangoprojects/myproject".
    --traceback           Print traceback on exception
    --first-name=FIRST_NAME
                          set first name
    --last-name=LAST_NAME
                          set last name
    --email=EMAIL         set email
    --mobile-phone=MOBILE_PHONE
                          set mobile phone used for SMS notifications
    --personal-email=PERSONAL_EMAIL
                          set personal email
    --add-list=ADD_LIST   add user to list
    --add-group=ADD_GROUP
                          add user to group
    --remove-list=REMOVE_LIST
                          remove user from list
    --remove-group=REMOVE_GROUP
                          remove user from group
    --version             show program's version number and exit
    -h, --help            show this help message and exit

Adding lists from the command line
----------------------------------

The ``add-list`` command allows to create new lists and to update their
members, lists or users::

  usage: docbow-ctl add-list [-h] [--version] [-v {0,1,2,3}]
                           [--settings SETTINGS] [--pythonpath PYTHONPATH]
                           [--traceback] [--no-color] [--add-list ADD_LIST]
                           [--remove-list REMOVE_LIST] [--add-user ADD_USER]
                           [--remove-user REMOVE_USER]
                           ml_name

  Create or update a list

  positional arguments:
    ml_name               Name of the mailing list

  optional arguments:
    -h, --help            show this help message and exit
    --version             show program's version number and exit
    -v {0,1,2,3}, --verbosity {0,1,2,3}
                          Verbosity level; 0=minimal output, 1=normal output,
                          2=verbose output, 3=very verbose output
    --settings SETTINGS   The Python path to a settings module, e.g.
                          "myproject.settings.main". If this isn't provided, the
                          DJANGO_SETTINGS_MODULE environment variable will be
                          used.
    --pythonpath PYTHONPATH
                          A directory to add to the Python path, e.g.
                          "/home/djangoprojects/myproject".
    --traceback           Raise on CommandError exceptions
    --no-color            Don't colorize the command output.
    --add-list ADD_LIST   add a list as a sublist
    --remove-list REMOVE_LIST
                          remove list as a sublist
    --add-user ADD_USER   add a user member
    --remove-user REMOVE_USER
                          remove a user member