Django uWSGI template

{{project_name}}

This is a Django project template using uWSGI as application server.

NOTE: for OSX check uwsgi-emperor-mode to configure your own local server with emperor.

Documentation

• Conventions
• Workspace initialization
  • Virtual environment
  • Basic requirements

• Setup a new project
  • Start Project
  • Git initialization
  • Initialization

• Clone and start the existing project
  • Clone Project
  • Initialization
• Usage
  • Database reset
  • Superuser creation
  • Add or Update libraries
    • List outdated libraries
    • Edit and Compile requirements files
  • Install libraries for development
• Testing
• Static
• Continuous Integration
  • Jenkins
  • Gitlab CI
  • Bitbucket pipelines
• Git pre-commit hooks
• Database
  • Create
  • Drop
  • Dump
• Deploy
  • Initialize
  • Deploy
  • Restore

Conventions

• replace projects with your actual projects directory

• replace project_name with your chosen project name

• replace git_repository_url with your actual git repository url

Workspace initialization

We suggest updating pip to the latest version and using a virtual environment to wrap all your libraries.

Virtual environment

IMPORTANT: Please, create an empty virtual environment, with the right python version, and activate it. To install and use virtualenv, please, visit the official documentation

Basic requirements

Django and Invoke must be installed before initializing the project.

({{project_name}}) $ pip install -U django invoke python-dotenv dj-database-url

Setup a new project

This section explains the first steps when you need to create a new project.

Start Project

Change directory and start a new project with this template:

({{project_name}}) $ cd ~/projects/
({{project_name}}) $ django-admin.py startproject --template https://www.20tab.com/template/ -e cfg,ini,md,py,yml,tpl {{project_name}}

Git initialization

In order to initialize git and sync the project with an existing repository:

({{project_name}}) $ cd ~/projects/{{project_name}}
({{project_name}}) $ inv gitinit GIT_REPOSITORY_URL

First initialization

Go to the initialization section

Clone and start the existing project

This section explains the steps when you need to clone an existing project.

Clone Project

Change directory and clone the project repository:

({{project_name}}) $ cd ~/projects/
({{project_name}}) $ git clone GIT_REPOSITORY_URL {{project_name}}

NOTE : If you're cloning an existing project, make sure you go to the correct branch (e.g. git checkout develop)

Initialization

Enter the newly created project directory:

({{project_name}}) $ cd ~/projects/{{project_name}}

Invoke init and follow instructions, to configure the project:

({{project_name}}) $ inv init

Usage

Database reset

To reset database execute (beware all data will be lost):

({{project_name}}) $ inv dropdb
({{project_name}}) $ inv createdb
({{project_name}}) $ python manage.py migrate

Superuser creation

Create a user with full privileges (e.g. admin access):

({{project_name}}) $ python manage.py createsuperuser

Add or Update libraries

List outdated libraries

To list all outdated installed libraries:

({{project_name}}) $ pip list -o

Edit and Compile requirements files

Edit the appropriate .ini requirements file, to add/remove pinned libraries or modify their versions.

To update the compiled requirements files (requirements/*.txt), execute:

({{project_name}}) $ make pip

Alternatively, in order to update specific dependent libraries to the latest version (e.g. urllib3), execute: 

({{project_name}}) $ make pip p='-P urllib3'

Install libraries for development

To install the just updated requirements (e.g. requirements/dev.txt), execute:

({{project_name}}) $ make dev

Testing

To run the full test suite, with coverage calculation, execute:

({{project_name}}) $ make test

NOTE: check django-bdd-toolkit for instructions on how to write BDD tests

Static

To collect static files, execute:

({{project_name}}) $ make collectstatic

Continuous Integration

Depending on the CI tool, you might need to configure Django environment variables.

Jenkins

Use the following command as a shortcut to configure the continuous integration.

pip install tox
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/{{project_name}}
export DJANGO_SECRET_KEY=<django_secret_key>
tox -e coverage,reportxml

Gitlab CI

The configuration file .gitlab-ci.yml should work as is, needing no further customization.

Bitbucket pipelines

The configuration file bitbucket-pipelines.yml should work as is, needing no further customization.

Git pre-commit hooks

To install pre-commit into your git hooks run the below command. pre-commit will now run on every commit. Every time you clone a project using pre-commit running pre-commit install should always be the first thing you do.

({{project_name}}) $ pre-commit install

Database

Create

To create a local database (database settings from .env):

({{project_name}}) $ inv createdb

Drop

To drop the local database (database settings from .env):

({{project_name}}) $ inv dropdb

Dump

To dump the local database into deploy/dump.sql.bz2 (database settings from .env):

({{project_name}}) $ inv dumpdb

Deploy

The project is partially configured to use Ansible to deploy the project. For each instance to deploy (e.g. "alpha"), there must be a config file (e.g. deploy/alpha.yml) and an item in the hosts file.

Use provided deploy/alpha.yml.tpl and deploy/hosts.tpl as templates for, respectively, the configuration and the hosts files. Rename them removing the .tpl suffix. The obtained files will not be versioned.

This project contains makefile commands for "alpha". If needed, duplicate those and use them as templates for additional instances (e.g. "beta" or "prod").

Both the remote server and the continuous integration system need node.js, in order to automatically build static files. If such module bundler is not necessary, remove unused commands from the Makefile ci command and from deploy/deploy.yml.

Initialize

Each instance (e.g. "alpha") should be initialized, executing only once:

({{project_name}}) $ make initalpha

Deploy

To deploy a specific instance (e.g. "alpha"), execute:

({{project_name}}) $ make alpha

Restore

To restore a local database dump (deploy/dump.sql.bz2) and deploy a specific instance (e.g. "alpha"), execute:

({{project_name}}) $ make restorealpha