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 prod 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 :ref:`install-dependencies`.
  38 If another program on your system uses a version of a dependency that
  39 GWM doesn't support, it can cause failure or unexpected behavior. To
  40 avoid these conflicts, Ganeti Web Manager version 0.7 (and above) is run
  41 in a virtual environment.
  42
  43 `Virtualenv <http://www.virtualenv.org/en/latest/>`_ solves problems
  44 caused by incorrect dependency versions by isolating the environment in
  45 which Ganeti Web Manager is run. Fabric installs the correct versions of
  46 the dependencies in the virtual environment, without the risk of
  47 impeding other programs that also use the dependencies in your system's
  48 global library. The end user's only interaction with the virtual
  49 environment is entering it (**source bin/activate**) before running GWM,
  50 since all setup and configuration are dealt with by the Fabfile.
  51
  52 The virtual environment ensures that Ganeti Web Manager will access the
  53 correct dependencies regardless of other changes that happen in your
  54 system.
  55
  56 Using the Virtual Environment
  57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58
  59 ::
  60
  61     #enter virtual environment
  62     source bin/activate
  63
  64     #leave virtual environment
  65     deactivate
  66
  67 When you are working in a virtual environment, the environment's name
  68 appears in parentheses at the start of the command prompt. For example:
  69
  70 ::
  71
  72     user@computer:~/ganeti_webmgr$ source bin/activate
  73     (ganeti_webmgr)user@computer:~/ganeti_webmgr$ ./manage.py syncdb
  74     (ganeti_webmgr)user@computer:~/ganeti_webmgr$ deactivate
  75     user@computer:~/ganeti_webmgr$
  76
  77 Using The Virtual Environment with Apache and mod\_wsgi
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 The virtual environment must be activated for use with mod\_wsgi. This
  81 is done by executing the **activate\_this** script generated when a
  82 virtualenv is created. The following code should be in the
  83 **django.wsgi** file apache is configured to use.
  84
  85 ::
  86
  87     # activate virtual environment
  88     activate_this = '%s/bin/activate_this.py' % PATH_TO_GANETI_WEBMGR
  89     execfile(activate_this, dict(__file__=activate_this))