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

     pip install -r requirements.txt

 - 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

 - Create database schema and load initial data::

     ( cd docbow_project; python manage.py syncdb --migrate )
     ( cd docbow_project; python manage.py loaddata content filetype groups )

 - Compile UI strings translations::

     ( cd docbow_project; python manage.py compilemessages )

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

     ( cd docbow_project; python manage.py load-users-csv users.csv )

Upgrading
---------

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

     ( cd docbow_project; python manage.py syncdb --migrate )

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

     ( cd docbow_project; sudo -u www-data python manage.py 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; python manage.py 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; python manage.py 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_TIMESTAMP_PROVIDER``: the timestamp provider to use. Default is certum.
   Other possibilities are fedit and e_szigno.

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

   ./manage.py collectstatic

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

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


  ./manage.py 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`` ::


  ./manage.py 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: ./manage.py 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: ./manage.py add-list [options] 

  Create or update a list

  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
    --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
    --version             show program's version number and exit
    -h, --help            show this help message and exit