1Installing in Virtualenv
2========================
3`Virtualenv`_ provides an isolated Python environment to run Graphite in.
4
5Installing in the Default Location
6----------------------------------
7To install Graphite in the :ref:`default location <default-installation-layout>`, ``/opt/graphite/``,
8create a virtualenv in ``/opt/graphite`` and activate it:
9
10.. code-block:: none
11
12  virtualenv /opt/graphite
13  source /opt/graphite/bin/activate
14
15Once the virtualenv is activated, Graphite and Carbon can be installed
16:doc:`from source <install-source>` or :doc:`via pip <install-pip>`. Note that dependencies will
17need to be installed while the virtualenv is activated unless
18`--system-site-packages <http://www.virtualenv.org/en/latest/index.html#the-system-site-packages-option>`_
19is specified at virtualenv creation time.
20
21Installing in a Custom Location
22-------------------------------
23To install from source activate the virtualenv and see the instructions for :ref:`graphite-web <graphite-web-custom-location-source>` and :ref:`carbon <carbon-custom-location-source>`
24
25Running Carbon Within Virtualenv
26--------------------------------
27Carbon may be run within Virtualenv by `activating virtualenv`_ before Carbon is started
28
29Running Graphite-web Within Virtualenv
30--------------------------------------
31Running Django's ``django-admin.py`` within a virtualenv requires using the
32full path of the virtualenv::
33
34    /path/to/env/bin/django-admin.py <command> --settings=graphite.settings
35
36The method of running Graphite-web within Virtualenv depends on the WSGI server used:
37
38Apache mod_wsgi
39^^^^^^^^^^^^^^^
40.. note::
41
42  The version Python used to compile mod_wsgi must match the Python installed in the virtualenv (generally the system Python)
43
44To the Apache `mod_wsgi`_ config, add the root of the virtualenv as ``WSGIPythonHome``, ``/opt/graphite``
45in this example:
46
47.. code-block:: none
48
49   WSGIPythonHome /opt/graphite
50
51and add the virtualenv's python site-packages to the ``graphite.wsgi`` file, python 2.6 in ``/opt/graphite``
52in this example:
53
54.. code-block:: none
55
56   site.addsitedir('/opt/graphite/lib/python2.6/site-packages')
57
58See the `mod_wsgi documentation on Virtual Environments <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>` for more details.
59
60Gunicorn
61^^^^^^^^
62Ensure `Gunicorn`_ is installed in the activated virtualenv and execute as normal. If gunicorn is
63installed system-wide, it may be necessary to execute it from the virtualenv's bin path
64
65uWSGI
66^^^^^
67Execute `uWSGI`_ using the ``-H`` option to specify the virtualenv root. See the `uWSGI documentation on virtualenv <http://projects.unbit.it/uwsgi/wiki/VirtualEnv>`_ for more details.
68
69
70.. _activating virtualenv: http://www.virtualenv.org/en/latest/index.html#activate-script
71.. _Gunicorn: http://gunicorn.org/
72.. _mod_wsgi: http://code.google.com/p/modwsgi/
73.. _uWSGI: http://projects.unbit.it/uwsgi
74.. _Virtualenv: http://virtualenv.org/
75
76