Metadata-Version: 1.0
Name: ccnmtldjango
Version: 1.2.3
Summary: Paste template for Django development at CCNMTL
Home-page: http://github.com/ccnmtl/ccnmtldjango/
Author: Anders Pearson
Author-email: anders@columbia.edu
License: UNKNOWN
Description: ccnmtldjango is a Paste Template that we use to replace
        the standard `django-admin.py startproject` command.
        
        It does the same basic task of setting up a directory
        structure for a django app, but it has been extended to
        implement a lot of CCNMTL specific functionality
        and configuration.
        
        What it provides for us that startproject doesn't:
        
        * Django Wind (a Django bridge to Columbia's central auth service -
          http://www.jasig.org/cas/deployments/columbia-university)
          is included and configured by default so our apps can use WIND
          for auth automatically. Ie, anyone with a Columbia UNI by
          default will have an account. The CCNMTL developer UNIs are
          automatically set up as superusers, and the group affil that
          CCNMTL staff all have gets automatically mapped to staff. These
          are generally useful defaults for us.
        * virtualenv and pip setup with source tarballs bundled and
          bootstrappable, `manage.py`'s shebang set to use it. This
          basically fits it into our one-step automated deployment and
          containment approach.
        * use wheel packages wherever possible
        * sorl.thumbnail (a handy dandy image thumbnailing library) is included by default
        * flatpages enabled
        * settings split for dev/prod/staging
        * apache/django.wsgi configured
        * sample apache config for mod_wsgi setup using Virtual
          Environments (everything is streamlined so that we can just
          symlink the generated apache config file into our production
          server's `/etc/apache/sites-enabled/` directory and it's good to go)
        * media dirs for dev/prod/staging configured
        * `django-typogrify` included (http://code.google.com/p/typogrify/)
          along with `smartypants.py` (which it uses)
        * `raven` included
          (https://github.com/dcramer/raven/) and configured for our sentry
          setup
        * raven configured to not run on south migrations
        * `django-munin` included (https://github.com/ccnmtl/django-munin)
        * `South` is included for database migrations
        * `django-annoying` is included (I like `@render_to`)
        * `django-nose` installed and set up as test runner (much nicer!)
        * coverage reports configured for `django-nose`
        * sqlite in-memory database used for unit tests
        * south tests automatically skipped on `./manage.py test` (they break)
        * `django_compressor` added and set up to compress css on production
        * `django_statsd` for graphite integration
        * `/stats/` page wired up to display basic traffic stats for the app
        * 'main' app with templated index view wired up and ready to go
        * `uuid.py`
        * jquery (1.7.2, minified) included
        * base templates included
        * django admin enabled (and authenticated with WIND for tlc)
        * `restclient`
        * `httplib2`
        * `requests`
        * `imageuploader`
        * markdown is included and enabled
        * database defaulted to postgresql
        * transaction middleware enabled by default (cause data corruption is teh suck)
        * timezone set
        * I18n turned off (we are unfortunately monolingual. no sense in denying it)
        * PIL
        * `psycopg2` (stripped of its `mx.DateTime` dependency)
        * a nice default template design with alternate base templates for multi-column layout.
        * `flake8` (http://pypi.python.org/pypi/flake8) is installed by default
          for code linting
        * lettuce/selenium included for nice browser tests, including sample
          index feature and helpful terrain.py functions
        * backbone.js
        * underscore.js
        * layout based on twitter bootstrap
        * `django-waffle` included for feature flipping (https://github.com/jsocol/django-waffle)
        * `django-jenkins` included and set up for our Jenkins instance (https://github.com/kmmbvnr/django-jenkins)
        * `django-smoketest` included, wired up, and a sample `smoke.py`
          included (https://github.com/ccnmtl/django-smoketest)
        * `django-extensions` included to do a variety of things like use
          IPython, Werkzeug debugger, kcachegrind profiling, etc. (https://github.com/django-extensions/django-extensions)
        * `django-impersonate` included and configured for easier debugging
        
        To use ccnmtldjango, you need python 2.7+, virtualenv, pip, and a recent
        setuptools installed on your machine.
        
        First, if you don't already have ccnmtldjango installed:
        
        Set up a new virtual environment, e.g. 
        
            $ virtualenv ve
        
        Activate your virtual environment, source ve/bin/activate, or previx all commands with 've/bin/'
        
            $ pip install Paste
            $ pip install PasteDeploy
            $ pip install ccnmtldjango
        
        ccnmtldjango should automatically pull in the remaining needed dependencies (just
        PasteScript, actually). If that gives you problems, the most likely
        cause is that one or more of your setuptools, pip, or virtualenv
        libraries is old. So upgrade those first and try again.
        
        Running
        
            $ paster create --list-templates
        
        should include ccnmtldjango
        
        Now, to quickstart a django project, do
        
            $ paster create --template=ccnmtldjango myprojectname
        
        `myprojectname` should be a python module name (ie, lowercase,
        no punctuation, etc). It will create a directory called
        `myprojectname` that has a django project in it.
        
        paster still doesn't do anything with file permissions, so we still
        need to manually set a couple:
        
            $ cd myprojectname
            $ chmod 755 manage.py bootstrap.py build_lettuce_db.sh
        
        I couldn't figure out a way to insert random strings into the code via
        Paste Template, so one thing that ccnmtldjango is missing compared to
        a regular django startproject is that the `SECRET_KEY` variable in
        settings_shared.py is always the same default. That's clearly not a
        good idea, so make sure you change that to some other random string
        that will be unique to your project. (Ideally, put that in a
        `local_settings.py` that doesn't get checked into version control).
        
        This is probably a good point to check the project into version control.
        
        We use containment for django too, with virtualenv:
        
            $ ./bootstrap.py
        
        That will create a `ve` directory which contains a virtualenv and has
        had all the libraries specified in the `requirements.txt` file
        installed into it (this includes django itself). The `ve` directory
        should never be checked into svn since it's generated. If you need
        other libraries for your application, `requirements.txt` then re-run
        `./bootstrap.py`.
        
        Keep in mind that with virtualenv, there's no need to `activate` an
        environment. Instead, a ve has a `bin` directory which contains a
        python executable. If you use that instead of the system python
        executable, it uses the libraries in that virtualenv.
        
        ccnmtldjango assumes that your project will use a postgresql database
        with the same name as your project. So, for our example, you would
        then do:
        
            $ createdb myprojectname
        
        and it is all set to use it:
        
            $ ./manage.py syncdb
            $ ./manage.py migrate
        
        will install the tables that django needs for it's common apps (sites,
        sessions, admin, flatpages, etc) and have you create an admin user.
        
        The `./manage.py syncdb` automagically sets up an "example.com"
        site. This should be changed to your site domain (e.g. `localhost:8000`)
        via the admin console. `http://localhost:8000/admin/sites/site/`. (if it
        matters for your application)
        
        Tests should pass out of the box:
        
            $ ./manage.py test
        
        They can be run via Jenkins as well and generate the right reports in
        a `reports` directory (which you will want to gitignore).
        
            $ ./manage.py jenkins
        
        Your application is ready to run now:
        
            $ ./manage.py runserver
        
        will start a server on `http://localhost:8000/`. The admin
        app should be accessible (via the user account you created during
        syncdb, or via WIND to tlc users (or ones specified in the
        `WIND_SUPERUSER_MAPPER_GROUPS` list in `settings_shared.py`). So go ahead
        and login to `http://localhost:8000/admin/`
        
        Even without any application specific code, flatpages is included so
        you can put content on the web right away.
        
        Lettuce and Selenium have also been set up, so (as long as you have
        firefox installed in a regular way), you should be able to do:
        
            $ LETTUCE_SKIP_SELENIUM=1 ./manage.py harvest --settings=yourapp.settings_lettuce
        
        And see a couple basic lettuce tests (defined in
        `main/features/index.feature`) run by and pass.
        
        If you have your browser stuff setup properly (running on your local
        machine, etc), you can run that without `LETTUCE_SKIP_SELENIUM` and
        run full browser tests.
        
        From this point out, it's basic django development. You'll probably
        want to do a `./manage.py startapp` to create your own application
        within the project and so on.
        
        --------------------------
        Setting up a fresh checkout
        
        The first time you check out an existing ccnmtl-template project from
        svn/git:
        
             $ ./bootstrap.py
             $ ./manage.py runserver <IP Address>:<PORT>
        
        
        ------------------------------------------
        Differences from a standard Django install
        
        Obviously, a bunch of libraries and such have been added and there's
        the whole virtualenv thing. There are also some differences from a
        standard django project (ie, the result of `django-admin.py startproject`) that you should be awayre of.
        
        First, the settings have been split up to make dev/staging/prod
        deployments easier to configure. A regular django install will have
        one `settings.py` file that contains all the settings. Django
        developers will usually copy that settings file and make changes when
        deploying to production. ccnmtldjango takes advantage of the fact that
        settings are just python code and can be imported and overridden. So
        we have a `settings_shared.py` which contains most of the
        settings. `settings.py` (which should be used for development) and
        `settings_production.py` then import everything from from
        `settings_shared.py`. `settings_production.py` then also overrides any
        settings that should be different in the production deployment
        (usually paths to templates and media files). Same deal for `settings_staging.py`
        
        `TransactionMiddleware` is enabled by default. This means that each HTTP
        request gets a transaction that commits or rolls back at the end of
        the request. The default django setup for some reason does things
        "autocommit" style where each database operation runs in its own
        transaction, independent of the HTTP request.
        
        The other big difference to be aware of is the top-level `templates`
        directory. Standard django procedure is to have a templates directory
        in each application in your project that contains the templates for
        that application. ccnmtldjango has the top-level templates directory
        for a couple reasons. First, since paster only creates the project
        level directory and not the application directories, it was the only
        way to have it include a default `base.html`, `admin/login.html`,
        `registration/login.html` and so on. I also just like the approach of
        having a project-level templates directory, especially for the
        `base.html` template. Django allows multiple template directories and
        searches through them in a predictable order, so you can (and probably
        should) still create application level template directories, list them
        in `TEMPLATE_DIRS` ahead of the project level one, and override whatever
        templates you want in those.
        
        I18N is turned off since it's fairly rare that we do multi-lingual
        stuff and it's a performance hit to have it enabled if it's not being
        used. If you need to do a multi-lingual django site, just re-enable it
        and get to work.
        
Platform: UNKNOWN
