

Installation
============

.. include:: ../INSTALL.txt

Getting Started
===============

Woven provides four core management commands for your Django project:

``setupnode``, ``deploy``, ``patch``, and ``activate``

They're pretty simple but Lets walk through how they are used to deploy your project.

Setupnode
----------

Purchase an Ubuntu 10.04 VM on the host of your choice with root and ssh access.

Create a minimal setup.py in the directory above your django project. This is the only additional configuration file that will be required::

    from setuptools import setup
    setup(
        name = "[package]",
        version = "0.1",
        packages = ['package'],
    )

where `package` is the django-admin.py startproject name. Only name and version are
required for woven.

Run setupnode from your project directory.

.. code-block:: bash

    python manage.py setupnode [host]

in which case woven will use your current username to create on the node or

.. code-block:: bash

    python manage.py setupnode [user@host]

where user is the *new* user that will be created in place of using root. 

Lets go through what this actually does:

1. Changes the default ssh port to 10022
2. Creates the new `user` and disables the `root` user
3. Uploads your public ssh-key
4. Restricts ssh login to the ssh-key and adds a few other restrictions
5. Adds additional sources `universe` to sources.list
6. Updates and upgrades your packages
7. Installs UFW firewall
8. Installs a baseline of Ubuntu packages including Apache, Nginx, and mod-wsgi
9. Install any etc templates/files sourced from the woven or project woven/etc template directories
10. Sets the timezone according to your settings file

Of course not all hosts are the same and no two deployments are alike so have a look
at some of the :doc:`settings` you can use in your Django project.

Woven uses standard Django templates to create configuration files for Apache, Nginx, and ssh.
If you want to modify them you can copy them from the package into a woven folder in your projects templates folder like any other app.

Deploy
----------------

*Deploy early. Deploy often.*

First configure the usual necessary project settings.py if they're not already done. Here are some notes about the main ones:: 

    # Woven will deploy your default development sqlite3 database onto the host,
    # otherwise it assumes you manage the db externally.
    'ENGINE': 'django.db.backends.sqlite3', # Add 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
    'NAME':,

    # Woven treats MEDIA_ROOT as a public directory that might be used for file storage. 
    MEDIA_ROOT 

    # Woven treats ADMIN_MEDIA_PREFIX as application media 
    # this cannot be on the same path as MEDIA_URL
    ADMIN_MEDIA_PREFIX

.. note::

    Starting with a sqlite3 database is actually a pretty good idea. It's easy to load up to production, performs well for sites that are mostly reads, and if you like you can dump the database and load it into postgresql or mysql when you need *write* scalability or the extra features of an enterprise database.

Follow the usual django instructions for enabling admin for your site and then run ``python manage.py syncdb``.
Make sure you can login to your default admin site, and if everything is alright it is time to do your first deployment.

.. code-block:: bash

    python manage.py deploy [user@host]

The first thing it may ask for is the root domain if it can't guess it from your nodes hostname. This is your SITE_ID = 1 production domain. You can define it as the first domain in the ``DOMAINS`` list setting in your settings.py.

.. note::

    Make sure your domain server or /etc/hosts file has an entry for the domain (and on osx, run ``dscacheutil -flushcache``).
    
The default deploy does the following::

1. For your first deployment it will deploy your sqlite database
2. Create a virtualenv for the project version
3. Install django. By default it will install the current version. You can set a pip requirements string DJANGO_REQUIREMENT in your settings.py if you want svn trunk or some other version
4. Install dependencies from one or more requirement req* files. eg. req, requirements.txt etc. If one doesn't exist then it will create one locally and add woven in it by default.
5. Creates a local sitesettings folder and a settings file for your server [domain].py if it doesn't already exist. You can see how woven lays out your project on the server in the sitesettings file.
6. Deploys your project to the virtualenv on the server
7. Deploys your root (shortest path) TEMPLATE_DIR into a templates directory on the server.
8. Deploys admin media or STATIC_ROOT setting (if you use django-staticfiles) into a virtualenv static directory.
9. Deploys anything at MEDIA_ROOT into a non-virtualenv public directory.
10. Deploys your domain wsgi file into a virtualenv wsgi directory as [domain].wsgi
11. Renders your apache and nginx templates and deploys them into the sites-available with the version in the name.
12. Stops the webservices
13. Syncs the database
14. Runs South migrate if you have South installed
15. Symlinks the webserver conf versions into sites-enabled
16. Symlinks the project virtualenv version to the active virtualenv.
17. Starts the webservices


Patch
------

Of course mistakes are made, but you cannot re-deploy the same significant version with deploy. A significant version might be 0.1, 0.1.1 or something like 0.1.0-alpha etc. An insignificant version might be 0.1.0.1 when the last digit is your build number. To get around having to deploy a new version for small changes you can run:

.. code-block:: bash

    python manage.py patch [user@host]
    
This will update existing files in your project, media and webserver configurations. It won't delete any files or update any dependencies. To update dependencies to a new library version you would need to increase your setup.py version and re-run deploy.

Patch can also just upload a specific part of your project using a subcommand. For example to just patch your webserver conf files:

.. code-block:: bash

    python manage.py patch webservers [user@host] 

Where to now
------------

If you want to work directly on the server you can SSH into your host and type::

    workon [projectname]
    
This will use virtualenvwrapper to activate your current virtualenv and drop you into the project sitesettings manage.py directory. A convenience manage.py and settings.py is provided to run manage.py from there on the first site.

Of course installing packages from a requirements file can be problematic if pypi is down.  To get around this first set your DJANGO_REQUIREMENT setting to file:///path/to/Django-x.x.x.tar.gz to rsync against a local copy. Next make use of  ``manage.py bundle`` command. This will use pip to bundle all the requirements into a dist directory in project. When deploying woven will look in the dist directory first and install from a bundle with the same name as the requirements file.

Have a read of the woven django management :doc:commands to get a better feel of the woven commands. 

Development
===========

At the current version 0.5, Woven has implemented most of it's basic features, and is now aiming to stabilize the api and move from alpha to beta status. There still may be incompatibilities between version 0.5 and 0.6, but will endeavour to provide an upgrade path between versions until the a beta release.  The core highlevel functions setupnode, deploy, patch, and activate will not change.

The woven project is hosted on github at http://github.com/bretth/woven. Feature requests and bug reports are welcome.

You can contact me at brett at haydon dot id dot au

