Package: ccnmtldjango
[![Build Status](https://travis-ci.org/ccnmtl/ccnmtldjango.svg?branch=master)](https://travis-ci.org/ccnmtl/ccnmtldjango)[![Documentation Status](https://readthedocs.org/projects/ccnmtldjango/badge/?version=latest)](https://ccnmtldjango.readthedocs.org/en/latest/?badge=latest)ccnmtldjango is a Paste Template that we use to replacethe standard `django-admin.py startproject` command.It does the same basic task of setting up a directorystructure for a django app, but it has been extended toimplement a lot of CCNMTL specific functionalityand 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 WINDfor auth automatically. Ie, anyone with a Columbia UNI bydefault will have an account. The CCNMTL developer UNIs areautomatically set up as superusers, and the group affil thatCCNMTL staff all have gets automatically mapped to staff. Theseare generally useful defaults for us.* virtualenv and pip setup with source tarballs bundled andbootstrappable, `manage.py`'s shebang set to use it. Thisbasically fits it into our one-step automated deployment andcontainment approach.* a nice Makefile for common build, test, and run tasks* use wheel packages wherever possible* flatpages enabled* settings split for dev/prod/staging* apache/django.wsgi configured* sample apache config for mod_wsgi setup using VirtualEnvironments (everything is streamlined so that we can justsymlink the generated apache config file into our productionserver's `/etc/apache/sites-enabled/` directory and it's good to go)* media dirs for dev/prod/staging configured* `raven` included(https://github.com/getsentry/raven-python) and configured for our sentrysetup* raven configured to not run on south migrations* `django-annoying` is included (I like `@render_to`)* 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* jQuery, Backbone and Underscore included* base templates included* django admin enabled (and authenticated with WIND for tlc)* `httplib2`* `requests`* 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)* Pillow* `psycopg2`* a nice default template design with alternate base templates for multi-column layout.* `flake8` (http://pypi.python.org/pypi/flake8) is installed by defaultfor code linting* layout based on twitter bootstrap3* `ldap3`* `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 useIPython, Werkzeug debugger, kcachegrind profiling, etc. (https://github.com/django-extensions/django-extensions)* `django-impersonate` included and configured for easier debugging* `collectstatic` configured* `django-pagetree` and its `django-pageblocks` and `django-quizblock`installed and configured.* `django-registration` installed and configured* Google Analytics ready to goTo use ccnmtldjango, you need python 2.7+, virtualenv, pip, and a recentsetuptools installed on your machine.First, if you don't already have ccnmtldjango installed:Set up a new virtual environment, e.g.$ virtualenv veActivate your virtual environment, source ve/bin/activate, or prefix all commands with 've/bin/'$ pip install Paste PasteDeploy ccnmtldjangoccnmtldjango should automatically pull in the remaining needed dependencies (justPasteScript, actually). If that gives you problems, the most likelycause is that one or more of your setuptools, pip, or virtualenvlibraries is old. So upgrade those first and try again.Running$ paster create --list-templatesshould include ccnmtldjangoNow, 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 stillneed to manually set a couple:$ cd myprojectname$ chmod +x manage.pyI couldn't figure out a way to insert random strings into the code viaPaste Template, so one thing that ccnmtldjango is missing compared toa regular django startproject is that the `SECRET_KEY` variable insettings_shared.py is always the same default. That's clearly not agood idea, so make sure you change that to some other random stringthat 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:$ makeThat will create a `ve` directory which contains a virtualenv and hashad all the libraries specified in the `requirements.txt` fileinstalled into it (this includes django itself). The `ve` directoryshould never be checked into svn since it's generated. If you needother libraries for your application, `requirements.txt` then re-run`./bootstrap.py`.Keep in mind that with virtualenv, there's no need to `activate` anenvironment. Instead, a ve has a `bin` directory which contains apython executable. If you use that instead of the system pythonexecutable, it uses the libraries in that virtualenv.ccnmtldjango assumes that your project will use a postgresql databasewith the same name as your project. So, for our example, you wouldthen do:$ createdb myprojectnameand it is all set to use it:$ make migrate$ make collectstaticwill install the tables that django needs for it's common apps (sites,sessions, admin, flatpages, etc) and have you create an admin user (ifyou want. If you're using WIND auth, you probably don't need tobother). It will also gather up static elements from all of yourinstalled apps and put them in the right place. It's really up to youwhether you want to check those into version control and not have todeal with it on deployment or leave them out of VC and add a`collectstatic` step to your deployment process.Tests should pass out of the box:$ make testThey can be run via Jenkins as well and generate the right reports ina `reports` directory (which you will want to gitignore).$ make jenkinsYour application is ready to run now:$ make runserverwill start a server on `http://localhost:8000/`. The admin app shouldbe accessible (via a user account created with`manage.py createsuperuser`, or via WIND to tlc users (or ones specifiedin 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 soyou can put content on the web right away.>From this point out, it's basic django development. You'll probablywant to do a `./manage.py startapp` to create your own applicationwithin the project and so on.#### Debugging Tests ####When debugging tests, sometimes it's useful to run only the test you'reworking on. To do this, you can specify the test class and method along withthe module like this:./manage.py test dmt.api.tests.test_views.NotifyTests.test_get--------------------------Setting up a fresh checkoutThe first time you check out an existing ccnmtl-template project fromsvn/git:$ make$ make runserver <IP Address>:<PORT>------------------------------------------Differences from a standard Django installObviously, a bunch of libraries and such have been added and there'sthe whole virtualenv thing. There are also some differences from astandard django project (ie, the result of `django-admin.py startproject`) that you should be aware of.First, the settings have been split up to make dev/staging/proddeployments easier to configure. A regular django install will haveone `settings.py` file that contains all the settings. Djangodevelopers will usually copy that settings file and make changes whendeploying to production. ccnmtldjango takes advantage of the fact thatsettings are just python code and can be imported and overridden. Sowe have a `settings_shared.py` which contains most of thesettings. `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 anysettings 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 HTTPrequest gets a transaction that commits or rolls back at the end ofthe request. The default django setup for some reason does things"autocommit" style where each database operation runs in its owntransaction, 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 directoryin each application in your project that contains the templates forthat application. ccnmtldjango has the top-level templates directoryfor a couple reasons. First, since paster only creates the projectlevel directory and not the application directories, it was the onlyway to have it include a default `base.html`, `admin/login.html`,`registration/login.html` and so on. I also just like the approach ofhaving a project-level templates directory, especially for the`base.html` template. Django allows multiple template directories andsearches through them in a predictable order, so you can (and probablyshould) still create application level template directories, list themin `TEMPLATE_DIRS` ahead of the project level one, and override whatevertemplates you want in those.I18N is turned off since it's fairly rare that we do multi-lingualstuff and it's a performance hit to have it enabled if it's not beingused. If you need to do a multi-lingual django site, just re-enable itand get to work.