Documentation non-complète

Basé sur: http://www.justanothercodemonkey.com/2009/08/deploying-django-with-buildout.html

Buildout

Buildout est le système de déploiement d'applications Python qui est en test en ce moment pour les systèmes à Montréal.

Buildout permet de gérer les dépendances, crée un environnement virtuel similaire a virtualenv, etc.

Création du buildout

La procédure utilise paster et les templates django, il faut donc l'installer:

easy_install fez.djangoskel 

Création de la structure de base:

paster create -t django_buildout <nom du dossier>

Paster va poser quelques questions:

Selected and implied templates:
fez.djangoskel#django_buildout  A plain Django buildout

Variables:
egg:      djangodev
package:  djangodev
project:  djangodev
Enter django_version (Django version to fetch, the default is 1.0.2) ['1.0.2']:
Enter django_project_name (Name of the main Django project folder) ['project']

Une fois terminé, on aura l'arborescence suivante:

djangodev
|-- bootstrap.py
|-- buildout.cfg
|-- devel.cfg
`-- README.txt

Lors de la premiere utilisation, il faut lancer le boostrap:

Optionnel : en développement, on peut installer un environnement Python isolé avec virtualenv

$ python ./bootstrap.py
Creating directory '/home/bashu/Temp/djangodev/bin'.
Creating directory '/home/bashu/Temp/djangodev/parts'.
Creating directory '/home/bashu/Temp/djangodev/develop-eggs'.
Generated script '/home/bashu/Temp/djangodev/bin/buildout'.

Il faut maintenant lui faire installer les dependances, et créer le projet:

$ ./bin/buildout -c devel.cfg
Installing django.
...

Il existe maintenant un nouvel executable bin/django, equivalent a python manage.py:

$ ./bin/django syncdb

Buildout aura aussi créé un dossier pour le projet Django. S'il s'agit d'un projet existant, suffit de copier le contenu du projet dans ce dossier.

À cette étape, il faut ajouter le path du projet dans la configuration de buildout: ajouter la ligne suivante dans la section "django" de buildout.cfg:

extra-paths = <nom du projet>

Il faudra ajouter les dépendances du projet dans buildout.cfg, en ajoutant une entrée eggs dans la section django:

eggs = django_pagination >=1.0
       django_sorting <=0.1
       django_historique
       django_exportateur
       auf_roa_authentification_backend

Il faut spécifier une dépendance par ligne, avec la version minimale ou maximale requise (optionnel).

Génération de scripts

On peut générer des scripts avec buildout, il faut ajouter une section dans buildout.cfg:

[buildout]
parts = .... monscript

[monscript]
recipe = buildout_script
template_dir = ${buildout:directory}/projet/scripts/
template = monscript.in

La génération de scripts fonctionne par template, on doit donc définir ou se trouvent les templates de script, et quel template utiliser. L'extension .in sera supprimée dans le script.

Une fois le buildout terminé, on aura le script généré dans bin/monscript.

Template (%(directory)s sera remplacé par le chemin racine du buildout):

# -*- encoding: utf-8 -*-

import sys, os, glob
# Dossiers du buildout
sys.path[0:0] = [
  "%(directory)s",
  "%(directory)s/auf_savoirs_en_partage",
  ]
# Inclure les dépendances
for d in glob.glob("%(directory)s/eggs/*"):
    sys.path[0:0] = [d,]
# Inclure django
for d in glob.glob("%(directory)s/parts/*"):
    sys.path[0:0] = [d,]

from monmodule import truc

truc()

Un exemple de .gitignore pour un projet django avec buildout

# binaires
*.pyc
*.pyo

# Fichier temporaires:
.*.swp
*~
\#*#

# DB de dev
*.db

# restants de merge
*.orig
*.rej

# Configuration du projet - par environnement
conf.py
django.wsgi

# buildout
.installed.cfg
bin
develop-eggs
downloads
eggs
log
parts
tmp

Utilisation

Environnement de dev

# Créer la structure initiale du buildout, génerer les scripts
$ python bootstrap.py 
# Faire le buildout de dev
$ bin/buildout -c devel.cfg
# Lancer le serveur de dev
$ bin/django runserver

Mise en prod

# Créer la structure initiale du buildout, génerer les scripts
$ python bootstrap.py 
# Faire le buildout de prod
$ bin/buildout -c buildout.cfg # des fois, on peut avoir un production.cfg

Buildout a généré un django.wsgi dans bin, il suffira de configurer Apache pour l'utiliser

Les recettes

Les recettes (recipe) expliquent au buildout ce qu'il a à faire. Par exemple, celle utilisée dans tous nos projet est la djangorecipe, pour bootstraper un projet. Elle permet de dire quelle version de django on veut utiliser, les modules tiers à récupérer (eggs) et bien d'autres options http://pypi.python.org/pypi/djangorecipe

djangorecipe

http://pypi.python.org/pypi/djangorecipe

Exemple :

[django]
recipe = djangorecipe
version = 1.2.3
project = auf_projets
wsgi=true
settings=production
extra-paths = auf_projets
eggs = auf_references_client
    south
    django-admin-tools
    datamaster_modeles
    django-tinymce
    django-form-utils

hexagonit.recipe.download

http://pypi.python.org/pypi/hexagonit.recipe.download

Quelque-fois les modules ne sont pas sur pypi, mais il est possible grâce à cette recette de les télécharger et de les décompresser dans le répertoire parts.

Note : il convient d'ajuster le paramètre exta-paths de la recette djangorecipe si vous voulez que ce module soit exploitable dans django

Exemple :

[wkhtmltopdf]
recipe = hexagonit.recipe.download
url = http://wkhtmltopdf.googlecode.com/files/wkhtmltopdf-0.9.9-static-i386.tar.bz2

collective.recipe.cmd

http://pypi.python.org/pypi/collective.recipe.cmd/0.5

Cette recette permet de faire des opérations systèmes

Exemple :

[wkhtmltopdf_executable]
recipe = collective.recipe.cmd
on_install = true
on_update = true
cmds =
     cd ${buildout:directory}/parts/wkhtmltopdf
     chmod +x wkhtmltopdf-i386
     cd ${buildout:directory}/bin
     ln -s ${buildout:directory}/parts/wkhtmltopdf/wkhtmltopdf-i386 wkhtmltopdf