How to start
============

To work on portail-citoyen just execute the following lines (command
to launch start with $, other lines are expected output)::

  $ pip install -r ./requirements
  $ cp local_settings.py.example local_settings.py
  $ ./portail-citoyen syncdb --all # you will be asked to create a new admin user
  Syncing...
  Creating tables ...
  [ snipped ]
  Creating table cmsplugin_a2servicelistplugin
  Creating table registration_registrationprofile

  You just installed Django's auth system, which means you don't have any superusers defined.
  Would you like to create one now? (yes/no): yes
  Username: admin
  First name: admin
  Last name: admin
  E-mail address: admin@coin.org
  Password: 
  Password (again): 
  Superuser created successfully.
  Installing custom SQL ...
  Installing indexes ...
  Installed 2 object(s) from 1 fixture(s)

  Synced:
   > django.contrib.auth
   [ snipped ]
   > registration

  Not synced (use migrations):
   - 
   (use ./manage.py migrate to migrate these)
  $ ./portail-citoyen migrate --fake
  [ lots of migrations running ]
  $ ./portail-citoyen runserver
  Validating models...

  0 errors found
  April 12, 2013 - 16:04:50
  Django version 1.5.1, using settings 'compte_agglo_montpellier.settings'
  Development server is running at http://127.0.0.1:8000/
  Quit the server with CONTROL-C.

The application is now usable at http://localhost:8000/

Settings
--------

Settings can be passed using a local_settings.py file or the shell
environment. Dictionaries are passed by flattening the variable name and the
dictionnary key separated by an underscore character. For example to passe the
variable MAIN_SITE_URL in templates, define the following environment
variable::

    export PORTAIL_CITOYEN_TEMPLATE_VARS_MAIN_SITE_URL=https://main-site.com/

Those variables must be prefixed with PORTAIL_CITOYEN_ when set in a
local_settings.py file or in the environment.

Name                             Description
================================ ============================================
TEMPLATE_VARS                    dictionnary of variables passed to templates
FAVICON_URL                      URL pointing to the favicon
WCSINST_DEFAULT_VARIABLES        default value for WCSINST new instances
PROFILE_FORM_PLUGIN_FORM_CLASS   form class to use instead of the default one
                                 for editing user profile

Migrating users from W.C.S. to portail-citoyen
----------------------------------------------

You must use the management command named load-wcs-users. You must first link
your W.C.S. instance to the portail-citoyen as a new SAML 2.0 service provider.
The command accept the following options::


 --provider=<provider_name>

   The name of the SAML 2.0 service provider in the portail citoyen configuratio.
   This option is mandatory.

 --mapping=<wcs_field_name>:<user_field_name>

   Map a user field identifier from W.C.S. to a local user model field.  This
   option is mandatory.

 --extra=<package_path>

   The path to a W.C.S. extra package to load (AuQuotidien for example).

 --verbose

   Display information logged on the console

 --debug

   display debugging information on the console

 --fake

   Launch a dry run, i.e. do not save new user and new federation

 --help-mapping

   Display the list of field available in the local user model and in the
   W.C.S. user model

 --allow-not-mapped

   Do not fail when a W.C.S. user field is not mapped to a local user field


Importing role from W.C.S. into portail-citoyen
-----------------------------------------------

Your must first decide on a prefix for naming roles on the portail-citoyen
side, default is 'AuQuo::'. Then federated roles must be actived and the
prefix be configured in the `site-options.cfg` file of the W.C.S. host
directory like this::

    [options]
    saml2_use_role = true
    saml2_role_prefix = MyPrefix::

Then you can use the `load-wcs-roles` command which accept the following options::

    --url=<url>

    URL of the W.C.S. instance from which we want to import roles (mandatory)

    --prefix

    The chosen federated role name prefix (mandatory)

    --orig

    The web-service identifier configured in `site-options.cfg` (mandatory)

    --key

    The web-service signature secret configured in `site-options.cfg` (mandatory)

    --email

    The email of the admin user used to access the fole list (mandatory)

    --deleted-orphaned-roles

    If actived delete federation roles starting with the given prefix which
    does not exist on W.C.S. side.

    --verbose

    Display logs on console

    --debug

    Display logs on console and set log level to DEBUG