.. django-scm-deploytools documentation master file, created by
   sphinx-quickstart on Fri May 11 14:59:47 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to django-scm-deploytools's documentation!
==================================================

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 configuration will be added
* mysql (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 right are considered 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.

------------
Requirements
------------

On the client: Django, django-scm-projecttemplate (or a project with a similar structure) and on the server: access via ssh with superuser rights (used to install software, create the right folders, etc), mysql with enough rights to create databases/tables and users.

---------
Contents:
---------
.. toctree::
   :maxdepth: 2

   setup
   api
   internal_api

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


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. _`BSD licensed`: http://www.linfo.org/bsdlicense.html
.. _`Django`: http://djangoproject.com/
.. _`django-scm_core`: http://bitbucket.org/flenter/django-scm_core/
.. _`django-scm-projecttemplate`: http://bitbucket.org/flenter/django-scm-projecttemplate/
.. _`nginx`: http://nginx.org
.. _`supervisor`: http://supervisord.org
.. _`celery`: http://celeryproject.org
.. _`fabric`: http://fabfile.org
.. _`gunicorn`: http://gunicorn.org