django-base-project

This is a base django project that comes with everything we need to get started on fun, innovative stuff.

Note: You'll notice that the entire project is sprinkled with the {{ project_name }} template tag. This enables the entire codebase to be used as a base template when running the startproject command.

Features

By default, this project template includes:

Templating:

• django_compressor for compressing javascript/css/less/sass

Security:

• hashlib
• m2crypto

Background Tasks:

• Celery

Migrations:

• Django built-in migrations (Django >=1.7)

Caching:

• django-redis

Testing:

• pytest
• pytest-coverage
• mock
• selenium

Authentication:

• python-social-auth for OAuth with social networks

Amazon:

• boto for integration with AWS

Documentation:

• Sphinx for autodocs

Any of these options can added, modified, or removed as you like after creating your project.

Structure/Organization

This template follows the default folder structure recommended by Django:

{{ project_name }}/ <-- this'll be auto-generated when you start a project (see below)
|---ansible/
|   |---plugins/
|   |---roles/
|   |   |---webserver/ <-- setup Nginx
|   |---site.yml
|   |---webserver.yml
|   |
|---{{ project_name }}/
|   |---.rcfile <-- config for your pylint needs.
|   |---docs/
|   |   |---_build <-- auto-generated by Makefile.
|   |   |---_static
|   |   |---_templates
|   |   |---conf.py <-- edit this file for default doc values.
|   |   |---Makefile
|   |---sample_app/ 
|   |   |---admin.py <-- expose this app to Django admin
|   |  	|---models/ 
|   |  	|   |---sample_model.py <-- each model should be its own file.
|   |  	|---static/ <-- all app specific static assets go here.
|   |  	|   |---css/
|   |  	|   |---images/
|   |  	|   |---js/
|   |  	|---tests <-- all tests for sample_app should go here.
|   |  	|   |---test_sample_app.py
|   |   |---urls.py
|   |   |---views.py
|   |-- settings/
|	|	|---__init__.py
|	|	|---common.py <-- common settings shared by all environments.
|	|	|---local.py
|	|	|---dev.py
|	|	|---qa.py
|	|	|---staging.py
|	|	|---production.py
|	|---static_common/ <-- (optional) shared static assets by different apps go here.
|	|	|---css/
|	|	|---images/
|	|	|---js/
|   |---manage.py
|   |---requirements.txt <-- all required packages for your Django project to work.
|   |---user-data.json <-- fixture to create your admin user.

Philosophy

This folder structure enables us to follow Django's principle of an application:

The term application describes a Python package that provides some set of features. Applications may be reused in various projects.

This means that every application should be self contained and pluggable into any Django project. This is why each app has it's own static and tests folder. In the event that you have static assets that can be shared between two more or more applications, you can either keep separate copies in each app, or move them one level higher into the static-commons folder.

Getting Started

Installation

Python 3.4 is required. If you don't have Python 3.4 or higher, download the appropriate package and install:

wget https://www.python.org/ftp/python/3.4.3/python-3.4.3-macosx10.6.pkg

Then install virtualenv:

sudo pip3 install virtualenv

Create a virtualenv for {{ project_name }} and activate it:

virtualenv -p <PYTHON_3_PATH> ~/virtualenvs/{{ project_name }}
source ~/virtualenvs/{{ project_name }}/bin/activate

Install Django into the virtualenv:

~/virtualenvs/{{ project_name }}/bin/pip3 install Django

Create a new Django project using this project as a base template:

django-admin.py startproject --template=https://github.com/Appdynamics/django-base-project/archive/master.zip --extension=py,rst,html,config {{ project_name }}
cd {{ project_name }}/{{ project_name }}

Now, install the rest of the packages that are required by your Django project:

~/virtualenvs/{{ project_name }}/bin/pip3 install -r requirements.txt

Setup the database. Locally, this will create a new sqllite database

~/virtualenvs/{{ project_name }}/bin/python3 manage.py migrate

OUTPUT:
Operations to perform:
  Apply all migrations: contenttypes, sessions, admin, auth
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying sessions.0001_initial... OK

Load initial data. This will create a base admin user with admin as the username and changeme as the password.

~/virtualenvs/{{ project_name }}/bin/python3 manage.py loaddata user-data.json

OUTPUT:
Installed 1 object(s) from 1 fixture(s)

Start the Django server:

~/virtualenvs/{{ project_name }}/bin/python3 manage.py runserver

Your Django project is now live, locally. In your browser, go to: http://localhost:8000.

Deployment (AWS)

Once you get to a point where you want to start hosting your Django project live, there are two options: using the provided ansible playbook to provision onto an EC2 instance, or using AWS's Elastic Beanstalk.

Note: At this time, Elastic Beanstalk does not officially support Python3 apps.

Ansible

If you want to deploy this Django app onto an EC2 instance, you can use the provided ansible playbook to do so:

ansible-playbook -i ec2.py -l<ec2_hostname>

AWS Elastic Beanstalk

This project is ready to deploy in Elastic Beanstalk. All you need is to set your AWS credentials like so:

export AWS_ACCESS_KEY_ID="<your_aws_access_key>"
export AWS_SECRET_KEY="<your_aws_secret_key>"

Next, initialize your project for Elastic Beanstalk:

eb init

Finally, deploy your code!

eb deploy

For more information on deploying a Django app into Elastic Beanstalk, you can visit AWS's documentation here:

1. http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_Python_django.html

Testing

In the provided sample app sample_app, there's a tests directory that implements some sample test cases that show how different test classes can be leveraged by the Django application.

To start the tests, simply run:

python3 manage.py test

You should see the following output:

python3 manage.py test
Creating test database for alias 'default'...
...
----------------------------------------------------------------------
Ran 3 tests in 3.049s

OK
Destroying test database for alias 'default'...

Selenium Testing

This project utilizes the selenium module so you can quickly spin up your site (on a different port) and test it against various browsers. It utilizes Django's '--liveserver' parameter.

python3 manage.py test {{ project_name }}.sample_app.SampleSeleniumTests

Code Coverage

The 'coverage' module is also available to provide a report of how well your Django project is covered by unit tests.

To create a coverage report, simply run:

coverage run manage.py test

Afterwards, you can view the report by:

$ coverage report -m
Name                      Stmts   Miss  Cover   Missing
-------------------------------------------------------
my_program                   20      4    80%   33-35, 39
my_other_module              56      6    89%   17-23
-------------------------------------------------------
TOTAL                        76     10    87%

For a nicer presentation, use coverage html to get annotated HTML listings detailing missed lines:

$ coverage html

For more information, visit https://coverage.readthedocs.org.

Documentation

This project comes with a pre-configured Spinx Makefile. You can edit the conf.py to fit your documentation purposes.

To auto-generate documentation for your project:

cd {{ project_name }}/docs
make html

You should see the following output:

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.3
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                                                                                                               
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                                                                
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

As noted in the above console, your documentation will be built into the _build folder.

For more information on Spinx and how to host your documentation, go to:

1. http://sphinx-doc.org/tutorial.html
2. http://bash-shell.net/blog/2014/apr/19/private-read-docs-private-github-repo/

Code Quality

Pylint

This Django project comes with a pre-configured rcfile for linting purposes. Edit it to your liking. The project should already be free of any PEP8 warnings and errors.

To lint, just run:

cd {{ project_name }}
pylint --rcfile=.rcfile *