~roadmr/canonical-identity-provider/fix-deprecation-warnings-1

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

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

The supported way to develop Canonical Identity Provider is using LXC.
There's some additional documentation on LXC gotchas in the following
page (check there specially if you can't resolve the LXC address when
ssh'ing and if you want to open GUI apps seeing them in your host machine):

   https://wiki.canonical.com/UbuntuOne/Developer/LXC

To get started, make sure you have LXC installed and ready to use on
the host computer::

   $ sudo apt-get install libvirt-bin lxc

Once it's installed, the current supported version of Ubuntu is Trusty 14.04.
We'll create a new container specifically for this project to isolate it from
the system and other projects::

   $ lxc launch ubuntu:trusty sso-trusty

Once it's created, let's log in with your existing credentials::

   $ ssh -A sso-trusty

From now on, instructions will assume you're inside the sso-trusty LXC, unless
otherwise noted.

1. Get the code

.. note::
    You need to install, configure and setup bzr and ssh keys. See BAZAAR below.

::

    $ bzr branch lp:canonical-identity-provider
    $ cd canonical-identity provider

To set the prerequisites up inside the container, you can run the setup-container script
with sudo (needed to install packages and change system config inside the container)::

    $ sudo ./setup-container

If you run into trouble or want to perform one or more steps manually, have a look at the
setup-container script, which is quite simple and commented.


2. Bootstrap the project

::

    $ make bootstrap


3. Enable the virtualenv and set up the database

::

    $ source env/bin/activate
    $ make start-db

.. note::
    If this step fails, try to shutdown a potentially old postgresql setup,
    and run it again. You can shutdown the db with::

        $ make stop-db

.. note::
    You could also set this to use a system database, by changing the django
    settings in the local settings.py file.


4. Run the tests

::

    $ sudo service memcached restart
    $ make test


5. Run the instance

::

    $ make run


6. (Optional) Setup reCaptcha

    1. Captcha is disabled by default in development.
    2. For selective GeoIP-based Captcha activation, set a Gargoyle Switch
       with the following values (eg. disable Captcha for China only)::

            key = 'CAPTCHA'
            status = SELECTIVE
            value = {"request": {"country_code": [["e", "CN"]]}}

    3. But if you really want to configure Captcha:

       Refer to all the captcha settings in "django_project/settings_base.py".
       Put similar settings into your "../local_config/settings.py".

       (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.

    Run (in a separate terminal)::

        $ make mail-debug

    Note, you will need to run a mail server to create an account.


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
    "../local_config/settings.py" to point to them.


9. (Optional) Running acceptance tests

    Some configuration is needed. Add this to your
    "../local_config/settings.py" file (customizing as appropriate)::

        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_PRIVATE_KEY = 'some-real-private-key'
        CAPTCHA_PUBLIC_KEY = 'some-real-public-key'
        EMAIL_WHITELIST_REGEXP_LIST = 'base(\+[^@]*)?@example\.com'

        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

    The ./scripts/acceptance-dev.sh script with run SSO, a localemail server,
    and the acceptance tests for you.

    Or you can run the various parts yourself:

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

    2) SSO must be running for the acceptance tests to run.

    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


10. (Optional) CSS Hacking

    (https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager)

::

        $ npm install
        $ npm install -g gulp
        $ gulp

    Will start a watcher to lint, minify and concat CSS (see ./gulpfile.js)
    CSS source can be found in src/identityprovider/static/src/css and is built
    to src/identityprovider/static/css/ (see ./gulpfile.js)


11. (Optional) Build deployment tarball

    To build a tarball that contains all the code, dependencies and the virtualenv::

        $ make fetch-sourcedeps
        $ make build-tarball

    Note: this is two separate steps as in Mojo specs we need to separate the
    dependency collect step from the build step, as the build step runs in an
    LXC with no internet access at all.


12. (Optional) Set up private/public keys to make macaroons work between projects

    For some endpoints to work correctly, the system needs to decrypt keys
    that were encrypted from other services (you'll need to use this
    instructions, or the corresponding one in the other projects).

    Create a pair of keys for this project::

       $ ssh-keygen -t rsa -N "" -f project_id_rsa

    This will leave you with two files, move the private one into the
    ``rsakeys`` directory, and the .pub one into this same dir in the
    other projects.


13. (Optional) Setup Launchpad Integration

    This is required to enable ssh-key management functionality.

    1. Setup a local development instance of Launchpad. See:

        https://dev.launchpad.net/

        https://dev.launchpad.net/Running

    2. Get an OAuth access token from Launchpad for SSO.

       From a launchpad branch, run::

       $ ./scripts/generate-access-token.py ubuntu-sso -n SSO_DEV

       Add the output config (LP_API_URL etc.) to "../local_config/settings.py"


BAZAAR
------
You can install bzr like this::

    $ sudo apt-get install bzr
    $ bzr whoami "You Name <youremail@example.com>"

You will also need to setup SSH keys. If you already have them, you can either
copy them to the machine you wish to use (Otherwise, Launchpad won't talk
to you) or, on the machine you wish to use, create a set of SSH keys using
ssh-keygen::

       $ ssh-keygen -t rsa

Then copy the contents of the .ssh/id_rsa.pub public key in the "Add an SSH
key" field at the bottom of this page (which should direct you to your
Launchpad account's list of authorized keys)::

    https://launchpad.net/~/+editsshkeys

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

Enjoy!
======

We hope you enjoy using this software.