docs/source/deployment.rst

   1 Installation
   2 ============
   3
   4 .. Note: Installing from the tarball is the preferred method. After
   5          installing the dependencies, please download the tarball instead of
   6          cloning the repository.
   7
   8 Overview
   9 ~~~~~~~~
  10
  11 #. Install dependencies: Python, Pip, Fabric, VirtualEnv
  12 #. Get the Ganeti Web Manager code: Clone from the repository or
  13    download a release tarball
  14 #. Deploy fabric environment: fab dev deploy or fab prod deploy
  15 #. Configure Settings: Copy settings.py.dist to settings.py and make
  16    any modifications
  17 #. Sync database, then run the server: ./manage.py syncdb --migrate,
  18    then ./manage.py runserver
  19
  20 This section explains how to automatically install Ganeti Web Manager
  21 using Fabric_. Fabric simplifies the installation process by
  22 automatically installing dependencies into a virtual environment.
  23
  24 Related Topics:
  25
  26 -  Read more about why :doc:`fabric-recommend`
  27 -  :doc:`fabric-install`
  28 -  :doc:`manual-install`
  29
  30 .. _Fabric: http://docs.fabfile.org/
  31
  32 Compatibility
  33 -------------
  34
  35 Ganeti Web Manager is compatible with the following:
  36
  37 -  `Ganeti <http://code.google.com/p/ganeti/>`_: **>= v2.2.x** is
  38    supported. **v2.1.x** and **v2.0.x** are unsupported and sometimes
  39    work but can cause problems (see `#8973 <http://code.osuosl.org/issues/8973>`_). Lower
  40    versions are **not** supported.
  41 -  **Browsers:** `Mozilla Firefox <http://mozilla.com/firefox>`_ >=
  42    v3.x, `Google Chrome <http://www.google.com/chrome/>`_ or
  43    `Chromium <http://code.google.com/chromium/>`_. Other contemporary
  44    browsers may also work, but are not supported. (The web-based VNC
  45    console requires browser support of
  46    `WebSockets <http://en.wikipedia.org/wiki/WebSockets>`_ and
  47    `HTML5 <http://en.wikipedia.org/wiki/Html5.>`_)
  48 -  **Databases:** MySQL or SQLite. SQLite is not recommended in
  49    production environments.
  50 -  **Operating Systems:** GWM has been tested on Debian 7, Ubuntu 11.10,
  51    12.04 and CentOs 5 and 6. Debian 6 is supported, provided the Pip,
  52    Virtualenv and Fabric packages are updated to the versions listed
  53    below.
  54
  55 Dependencies
  56 ------------
  57
  58 -  Python: >=2.5, python >=2.6 recommended
  59 -  `Pip <http://www.pip-installer.org/en/latest/index.html>`_ >= 0.8.2
  60 -  Fabric_ >=1.0.1
  61 -  `VirtualEnv <http://pypi.python.org/pypi/virtualenv>`_ >= 1.6.1
  62
  63 Pip is required for installing Fabric and a useful tool to install
  64 Virtualenv
  65
  66 ::
  67
  68     #pip
  69     sudo apt-get install python-pip
  70
  71     # devel libraries may be needed for some pip installs
  72     sudo apt-get install python-dev
  73
  74 Install Fabric and Virtualenv
  75
  76 ::
  77
  78     # install fabric and virtualenv
  79     sudo apt-get install python-virtualenv
  80     sudo apt-get install fabric
  81
  82 .. Note:: The use of pip to install system packages is not recommended,
  83           please use your system's package manager to install Virtualenv and
  84           Fabric.
  85
  86 Install with Fabric
  87 -------------------
  88
  89 #. Either download and unpack the `latest
  90    release <http://code.osuosl.org/projects/ganeti-webmgr/files>`_, or
  91    check it out from the repository:
  92
  93    ::
  94
  95        git clone git://git.osuosl.org/gitolite/ganeti/ganeti_webmgr
  96
  97 #. Switch to project directory
  98
  99    ::
 100
 101        # Fabric commands only work from a directory containing a fabfile
 102        cd ganeti_webmgr/
 103
 104 #. Run Fabric to automatically create python virtual environment with
 105    required dependencies. Choose either production or development
 106    environment
 107
 108    ::
 109
 110        # production environment
 111        fab prod deploy
 112
 113        # development environment
 114        fab dev deploy
 115
 116 #. Activate virtual environment
 117
 118    ::
 119
 120        source bin/activate
 121
 122 Configuration
 123 -------------
 124
 125 #. In the project root, you'll find a default-settings file called
 126    **settings.py.dist**. Copy it to **settings.py**:
 127
 128    ::
 129
 130        cp settings.py.dist settings.py
 131
 132 #. If you want to use another database engine besides the default SQLite
 133    (not recommended for production), edit **settings.py**, and edit the
 134    following lines to reflect your wishes.
 135
 136    .. Note:: Postgresql is not supported at this time and the
 137              install will fail (See issue `#3237 <http://code.osuosl.org/issues/3237>`_).
 138
 139    ::
 140
 141        DATABASE_ENGINE = ''   # <-- Change this to 'mysql', 'postgresql', 'postgresql_psycopg2' or 'sqlite3'
 142        DATABASE_NAME = ''     # <-- Change this to a database name, or a file for SQLite
 143        DATABASE_USER = ''     # <-- Change this (not needed for SQLite)
 144        DATABASE_PASSWORD = '' # <-- Change this (not needed for SQLite)
 145        DATABASE_HOST = ''     # <-- Change this (not needed if database is localhost)
 146        DATABASE_PORT = ''     # <-- Change this (not needed if database is localhost)
 147
 148 #. Initialize Database:
 149
 150    ::
 151
 152        ./manage.py syncdb --migrate
 153
 154 #. Build the search indexes
 155
 156    ::
 157
 158        ./manage.py rebuild_index
 159
 160    .. Note:: Running **./manage.py update\_index** on a regular basis
 161              ensures that the search indexes stay up-to-date when models change in
 162              Ganeti Web Manager.
 163
 164 #. Everything should be all set up! Run the development server with:
 165
 166    ::
 167
 168        ./manage.py runserver
 169
 170 .. _install-additional-config:
 171
 172 Additional configuration for production servers
 173 -----------------------------------------------
 174
 175 Deploying a production server requires additional setup steps.
 176
 177 #. Change the ownership of the ``whoosh_index`` directory to apache
 178
 179    ::
 180
 181        chown apache:apache whoosh_index/
 182
 183 #. Change your **SECRET\_KEY** and **WEB\_MGR\_API\_KEY** to unique (and
 184    hopefully unguessable) strings in your settings.py.
 185 #. Configure the `Django Cache
 186    Framework <http://docs.djangoproject.com/en/dev/topics/cache/>`_ to
 187    use a production capable backend in **settings.py**. By default
 188    Ganeti Web Manager is configured to use the **LocMemCache** but it is
 189    not recommended for production. Use Memcached or a similar backend.
 190
 191    ::
 192
 193        CACHES = {
 194            'default': {
 195                'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
 196            }
 197        }
 198
 199 #. For versions >= 0.5 you may need to add the full filesystem path to
 200    your templates directory to **``TEMPLATE_DIRS``** and remove the
 201    relative reference to **``'templates'``**. We've had issues using
 202    wsgi not working correctly unless this change has been made.
 203 #. Ensure the server has the ability to send emails or you have access
 204    to an SMTP server. Set **``EMAIL_HOST``**, **``EMAIL_PORT``**, and
 205    **``DEFAULT_FROM_EMAIL``** in settings.py. For more complicated
 206    outgoing mail setups, please refer to the `django email
 207    documentation <http://docs.djangoproject.com/en/dev/topics/email/>`_.
 208 #. Follow the django guide to `deploy with
 209    apache. <https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/modwsgi/>`_
 210    Here is an example mod\_wsgi file:
 211
 212    ::
 213
 214        import os
 215        import sys
 216
 217        path = '/var/lib/django/ganeti_webmgr'
 218
 219        # activate virtualenv
 220        activate_this = '%s/bin/activate_this.py' % path
 221        execfile(activate_this, dict(__file__=activate_this))
 222
 223        # add project to path
 224        if path not in sys.path:
 225            sys.path.append(path)
 226
 227        # configure django environment
 228        os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
 229
 230        import django.core.handlers.wsgi
 231        application = django.core.handlers.wsgi.WSGIHandler()
 232
 233 #. Enable the :doc:`usage/caching`
 234
 235    .. Note:: Do not run the cache updater as ``root``.
 236
 237    ::
 238
 239        twistd --pidfile=/tmp/gwm_cache.pid gwm_cache
 240
 241    You may encounter an issue where twisted fails to start and gives you
 242    an error.
 243    This is usually caused by the environment variable PYTHONPATH not
 244    being
 245    exported correctly if you switch to superuser 'su -'. To fix it type:
 246
 247    ::
 248
 249        export PYTHONPATH="."
 250
 251    Then ``exit`` out of root.
 252
 253 #. Set **VNC\_PROXY** to the hostname of your VNC AuthProxy server in
 254    **settings.py**. The VNC AuthProxy does not need to run on the same
 255    server as Ganeti Web Manager.
 256
 257    ::
 258
 259        VNC_PROXY = 'my.server.org:8888'