=============================
Development environment setup
=============================

Getting started
===============

1. Get the code

To download the source code hosted on github.com, all you need to do is 
just type in the following instructions from your favorite terminal.

::

    git clone git://github.com/miing/mci_migo.git migo

2. Set up the environment

If you're bootstrapping your environment only once (the simplest case), you
can just get the dependencies as you need them.
::

    cd migo
    fab bootstrap

To avoid having to redownload the dependencies every time you need to
bootstrap an environment, you can use a source "download cache" for pip to
get the dependencies from.
::

    cd migo
    fab bootstrap:download_cache_path=../download-cache
    
.. note::
	To keep these dependencies up to date, so far, we have already disabled
	the method. So, now, don't try it.

3. Set up the database
::

    fab setup_postgresql_server

.. note::
    If this step fails, do 'rm -fr .env/db' and run it again.

    If you need to restart this development database server, you can run:

    fab resetdb

    (See fabtasks/database.py for more postgresql-related commands.)

.. note::
    You could also set this to use a system database, by changing the "db_"
    settings in your "dj/local.cfg" file, under [__no_schema__].

4. Run the tests
::

    sudo service memcached restart
    fab test

5. Run the instance
::

    fab run

6. (Optional) Setup reCaptcha
::
    1. For development, it's probably easiest to simply disable Captcha:
    ::
        Put these settings into your "dj/local.cfg":

        [captcha]
        disable_captcha_verification = true

    2. But if you really want to configure Captcha:
    ::
        Ref. [captcha] settings in "django/config/main.cfg".
        Put similar settings into your "dj/local.cfg".
        (Configuring a local squid proxy server is beyond the scope of this document.)
        If you don't have a reCaptcha key, get one at http://www.google.com/recaptcha

7. (Optional) Configure a mail server
::
    (Configuring a local mail server is beyond the scope of this document.)
    If you don't have access to a local mail server, you can use a fake one.

    1. Add this to the "dj/local.cfg" file:
    ::
    [django]
    email_port = 1025

    2. Then run (in a separate terminal
    ::
    python -u -m smtpd -n -c DebuggingServer localhost:1025

8. (Optional) Create your own certificate and private key for SAML 2.0
::
    Required if you want to test interaction with a real Service Point.

    See instructions in the django-saml2-idp upstream project:
    http://code.google.com/p/django-saml2-idp/source/browse/trunk/idptest/keys/mk_keys.sh

    Once you have the files (certificate.pem and private-key.pem), update your
    "dj/local.cfg" to point to them.

9. (Optional) Configure Django behind mod_wsgi on apache2.
::
    Generally a good idea if you're serving on the Big Bad Internet.

    #TODO: More here.

10. (Optional) Running acceptance tests
::
    In order to run acceptance tests a system dependency is required (this is
    in order to avoid having multiple firefox windows popping up all the time
    while the tests are running). Install it like this

    sudo apt-get install xvfb

    Also, some configuration is needed. Add this to your local.cfg file
    (customizing as appropriate)

    [testing]
    test_account_email = some-email@example.com
    test_account_password = some-password
    qa_account_email = another-email@example.com
    qa_account_password = other-password
    imap_server = mail.example.com
    imap_username = username
    imap_password = password
    email_address_pattern = base+%s@example.com

    [captcha]
    captcha_private_key = some-real-private-key
    captcha_public_key = some-real-public-key
    email_whitelist_regexp_list = base(\+[^@]*)?@example\.com

    [django]
    email_host = smtp.someserver.com
    email_port = 587
    email_host_user = username
    email_host_password = password
    email_use_tls = True

    The email mailbox you specify (test_account_email) must be able to
    respond to any email on some_email+arbitrary@example.com. Gmail accounts
    work very well for this.

    Any valid recaptcha key will work as they all work correctly served from
    localhost. You can get free reCaptcha keys from http://recaptcha.org

    You will need a real smtp server for SSO to be able to send the
    authentication emails (which the acceptance tests check).

    SSO must be running for the acceptance tests to run. In one shell perform:

    fab run

    Then in another shell run the tests like

    fab acceptance

    Running all the acceptance tests can take a long time. You can pass
    command line parameters to the sst runner through the fab command. For
    example, this invocation stops the tests after the first failure, switches
    off headless mode and switches on screenshots on failure:

    fab acceptance:failfast=1,headless=0,screenshot=1

11. (Optional) Running API tests
::

    In order to run API tests some configuration is needed. Just like when
    running acceptance tests information, the following settings are needed in
    your local.cfg file:

    [testing]
    imap_server = mail.example.com
    imap_username = username
    imap_password = password
    email_address_pattern = base+%s@example.com

    After these changes have been made, you can run the tests like

    fab manage:test,--testing_test_discover_root=./identityprovider/tests/api,--sso_sso_root_url=http://some.server/

.. note::
    The --sso_sso_root_url parameter is only needed if you wish to test an
    external server. The default value will use the local development server,
    which you need to have started first.

12. (Optional) Using a different brand
::
    Currently there are ubuntu-branded templates (the default) as well as
    launchpad-branded templates and ubuntuone-branded templates. You can run
    the dev server or tests with each brand. For example, to run the webui
    tests with the ubuntuone brand:

    fab brand:ubuntuone test:extra=webui

    Or to run a devserver with the launchpad brand:

    fab brand:launchpad run

    Note that this does not set the brand description. If you need
    to do that, you can do so by adding the following to your local.cfg:

    [branding]
    brand_description = Launchpad Single Sign On



Background Reading
------------------
For those new to this project, this may help bring you up to speed quickly.
The Identity Provider uses some conventions that you may not have seen before.
These include:

- virtualenv
- fabric, esp., when used to run a Django manage.py COMMAND:
    - fab manage:COMMAND (see payload/__init__.py)
- django-configglue (used instead of standard Django settings.py code)
- preflight

Enjoy!
======

We hope you enjoy using this software.