docs/source/fabric-recommend.rst

   1 Fabric is strongly recommended
   2 ==============================
   3
   4 Ganeti Web Manager version 0.7 has been designed and tested for
   5 installation with Fabric. Fabric and virtualenv solve many problems
   6 identified in previous versions, including dependency version conflicts
   7 and the inconvenience of installation.
   8
   9 Why Fabric?
  10 -----------
  11
  12 `Fabric <http://docs.fabfile.org/>`_ is the Python
  13 counterpart to the
  14 `Capstrano <https://github.com/capistrano/capistrano/wiki>`_ web
  15 application deployment tool. Fabric automates Ganeti Web Manager's
  16 installation, setup, and update processes.
  17
  18 The fabfile contains the commands to create a virtual environment, then
  19 download and install the correct dependencies for Ganeti Web Manager.
  20 This standardized environment ensures that unique factors in your system
  21 don't affect the program's tested functionality. The fabfile also
  22 reduces the possibility of user error when installing Ganeti Web Manager
  23 by consolidating the entire process into a single command.
  24
  25 ::
  26
  27     # production environment
  28     fab deploy
  29
  30     # development environment
  31     fab dev deploy
  32
  33 Virtual Environments
  34 --------------------
  35
  36 Ganeti Web Manager has been developed and tested with specific versions
  37 of its dependencies. If another program on your system uses a version of a
  38 dependency that GWM doesn't support, it can cause failure or unexpected
  39 behavior. To avoid these conflicts, Ganeti Web Manager version 0.7 (and above)
  40 is run in a virtual environment.
  41
  42 `Virtualenv <http://www.virtualenv.org/en/latest/>`_ solves problems
  43 caused by incorrect dependency versions by isolating the environment in
  44 which Ganeti Web Manager is run. Fabric installs the correct versions of
  45 the dependencies in the virtual environment, without the risk of
  46 impeding other programs that also use the dependencies in your system's
  47 global library. The end user's only interaction with the virtual
  48 environment is entering it (**source venv/bin/activate**) before running GWM,
  49 since all setup and configuration are dealt with by the Fabfile.
  50
  51 The virtual environment ensures that Ganeti Web Manager will access the
  52 correct dependencies regardless of other changes that happen in your
  53 system.
  54
  55 Using the Virtual Environment
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58 ::
  59
  60     #enter virtual environment
  61     source venv/bin/activate
  62
  63     #leave virtual environment
  64     deactivate
  65
  66 When you are working in a virtual environment, the environment's name
  67 appears in parentheses at the start of the command prompt. For example:
  68
  69 ::
  70
  71     user@computer:~/ganeti_webmgr$ source venv/bin/activate
  72     (ganeti_webmgr)user@computer:~/ganeti_webmgr$ ./manage.py syncdb
  73     (ganeti_webmgr)user@computer:~/ganeti_webmgr$ deactivate
  74     user@computer:~/ganeti_webmgr$
  75
  76 Using The Virtual Environment with Apache and mod\_wsgi
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78
  79 The virtual environment must be activated for use with mod\_wsgi. This
  80 is done by executing the **activate\_this** script generated when a
  81 virtualenv is created. The following code should be in the
  82 **django.wsgi** file apache is configured to use.
  83
  84 ::
  85
  86     # activate virtual environment
  87     activate_this = '%s/venv/bin/activate_this.py' % PATH_TO_GANETI_WEBMGR
  88     execfile(activate_this, dict(__file__=activate_this))