Skip to content
Switch branches/tags

Django uWSGI template


Code style: black

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.



  • 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}}) $ startproject --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)


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


Database reset

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

({{project_name}}) $ inv dropdb
({{project_name}}) $ inv createdb
({{project_name}}) $ python migrate

Superuser creation

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

({{project_name}}) $ python 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


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


To collect static files, execute:

({{project_name}}) $ make collectstatic

Continuous Integration

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


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



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

({{project_name}}) $ inv createdb


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

({{project_name}}) $ inv dropdb


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

({{project_name}}) $ inv dumpdb


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.


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

({{project_name}}) $ make initalpha


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

({{project_name}}) $ make alpha


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

({{project_name}}) $ make restorealpha