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 by the source directory where docbow is installed:: ServerName docbow.example.com Alias /static /static WSGIScriptAlias / /docbow.wsgi RedirectMatch 404 ^/favicon.ico$ 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 by the source directory where docbow is installed:: ServerName docbow.example.com DocumentRoot /var/www ProxyPass /static ! ProxyPass / http://localhost:8000/ ProxyPreserveHost on Alias /static /static Order Deny,Allow Allow from all 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] 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