Documentation can be found at: http://readthedocs.org/docs/django-scm-deploytools/


Django-scm-deploytools is a BSD licensed Django application that allows for a more or less quick and easy deploy of sites on an ubuntu or debian flavoured server. Note this project works tightly together with fabric, the django-scm-projecttemplate and (to a lesser degree) django-scm_core.

The project helps deploy the following software stack (using virtualenv):

  • nginx It is assumed to be already installed, but the site's configuration will be added
  • mysql It is assumed to be already installed, but a new user/database will be created
  • gunicorn
  • supervisor
  • celery (optionally)

Additional software such as Redis, RabbitMQ, Memcached are not included to be installed (some hooks are there, but installing/configuring them is considedered to be out of scope)

Design decisions

Here are some of the decisions made with this project:

  • the goal is to not put all the deployment logic for a site in this project, but to keep that in the template this project contains, and can be modified to suite each projects individual needs.
  • mercurial is run on the deployment server (as a local repository). This is done so we can do a fallback if the unittests on the server fail. There's a basic unittest (always) run when updating a site (it comes from django-scm_core) to see if sorl is included and if it works (by resizing a small jpg to an png). There are some important things to keep in mind: south
  • One more or less side effect: the scripts are tailored towards a django & flash website so some of the questions in scripts might not make that much sense (there is a question if the bin-debug folder needs to be copied, that is important for our flash projects)

On the server supervisor is used to monitor things like the gunicorn and celeries beats/workers. The naming convention is:

  • gunicorn.domain_name.com
  • worker.domain_name.com
  • beats.domain_name.com

One small note: don't use the domain name with the www in front of it, by default the scripts will make nginx listen to domain_name and www.domain_name.


On the client: Fabric, Django, django-scm-projecttemplate and on the server: access via ssh with some superuser rights, mysql with enough rights to create databases/tables.

How to use

There are a couple of steps:

  • set up a project using the django-scm-projecttemplate. Please check the project's documentation on how to use it.
  • Make sure the deploytools are added to the INSTALLED_APPS of your project (that should already be the case if you use django-scm-projecttemplate)

run the management command 'create_deploy_tools' like so:

python manage.py create_deploy_tools

This will create a couple of important files and folders:

  • a project_name/fabfile.py which contains the core logic for installing the required software and adding sites to existing servers. This fabfile is good enough for most projects, but can should be modified/customized if need be.
  • deploy folder which (amongst others) contains servers.py.
  • create a script in the virtualenv's bin/deploy_project_name (which makes it easier to use fabric and the fabfile). It is similar to calling cd /project_root && ../bin/fab etc etc..

Adding the settings for a deploy target (such as live, staging etc) can be done like this:

python manage.py add_deploy_target

A couple of questions will need to be answerd (asking about the hostname, domain_name etc) and modifies deploy/servers.py file accordingly. After this you should be ready to go. You can view a list of commands by typing:

deploy_project_name -l

Resulting in:

Fabric install/update script for scm's django servers

Available commands:

add_site                Adds a site to an already prepared server.
collect_static          Runs the 1.3 collectstatic manage.py command
full_install            Do full installation
live                    Deploy to:: cola.secretcodemachine.com
update_site             Rsync the site and stop/start gunicorn

The newly created deploy target should be listed there. Actually deploying or updating a site are two commands chained together. The first command being the deploy target (the one you have created earlier with the add_deploy_target command). Resulting in commands like the following:

deploy_project_name staging full_install

# or adding a site to a server that already contains virtualenv/mysql
deploy_project_name staging add_site

# update an existing site by running
deploy_project_name staging update_site

Some details to remember for updating a site: a snapshot of the current code will be made (the media folder is not included in this). Should the unit test fail, a rollback will be attempted.

This means it will be attempted to go back to the pre-update stored south migrations, please keep that in mind when creating the migrations.

To do

  • write more documentation
  • add support for installing mysql and nginx (it's partially there, it is just not needed with our current preferred hosting provider)
  • create a django superuser. Users are not migrated