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`_: Ganeti **2.3.x--2.6.0** are supported. Earlier versions are
  38   unsupported; they may occasionally work, but should not be relied upon.
  39 - **Browsers:** `Mozilla Firefox`_ 3.x and newer, and recent `Google
  40   Chrome`_/`Google Chromium`_, are supported. Other contemporary browsers may
  41   also work, but are not supported. The web-based VNC
  42   console requires browser support of WebSockets and HTML5.
  43 - Databases: While all databases supported by Django should work, the GWM team
  44   officially supports `SQLite`_ and `MySQL`_.
  45 - Operating Systems: GWM is officially supported on Ubuntu 11.10, Ubuntu
  46   12.04, and CentOS 6. It is also known to work on Debian 7 and CentOS 5.
  47   Debian 6 should work, provided the Pip, Virtualenv and Fabric packages are
  48   updated to the versions listed below.
  49
  50 .. _Ganeti: http://code.google.com/p/ganeti/
  51 .. _Mozilla Firefox: http://mozilla.com/firefox
  52 .. _Google Chrome: http://www.google.com/chrome/
  53 .. _Google Chromium: http://www.chromium.org/
  54 .. _SQLite: https://sqlite.org/
  55 .. _MySQL: https://www.mysql.com/
  56
  57 Dependencies
  58 ------------
  59
  60 -  Python: >=2.5, python >=2.6 recommended
  61 -  `Pip <http://www.pip-installer.org/en/latest/index.html>`_ >= 0.8.2
  62 -  Fabric_ >=1.0.1
  63 -  `VirtualEnv <http://pypi.python.org/pypi/virtualenv>`_ >= 1.6.1
  64
  65 Pip is required for installing Fabric and a useful tool to install
  66 Virtualenv
  67
  68 ::
  69
  70     #pip
  71     sudo apt-get install python-pip
  72
  73     # devel libraries may be needed for some pip installs
  74     sudo apt-get install python-dev
  75
  76 Install Fabric and Virtualenv
  77
  78 ::
  79
  80     # install fabric and virtualenv
  81     sudo apt-get install python-virtualenv
  82     sudo apt-get install fabric
  83
  84 .. Note:: The use of pip to install system packages is not recommended,
  85           please use your system's package manager to install Virtualenv and
  86           Fabric.
  87
  88 Install with Fabric
  89 -------------------
  90
  91 #. Either download and unpack the `latest
  92    release <http://code.osuosl.org/projects/ganeti-webmgr/files>`_, or
  93    check it out from the repository:
  94
  95    ::
  96
  97        git clone git://git.osuosl.org/gitolite/ganeti/ganeti_webmgr
  98
  99 #. Switch to project directory
 100
 101    ::
 102
 103        # Fabric commands only work from a directory containing a fabfile
 104        cd ganeti_webmgr/
 105
 106 #. Run Fabric to automatically create python virtual environment with
 107    required dependencies. Choose either production or development
 108    environment
 109
 110    ::
 111
 112        # production environment
 113        fab prod deploy
 114
 115        # development environment
 116        fab dev deploy
 117
 118 #. Activate virtual environment
 119
 120    ::
 121
 122        source bin/activate
 123
 124 Configuration
 125 -------------
 126
 127 #. In the project root, you'll find a default-settings file called
 128    **settings.py.dist**. Copy it to **settings.py**:
 129
 130    ::
 131
 132        cp settings.py.dist settings.py
 133
 134 #. If you want to use another database engine besides the default SQLite
 135    (not recommended for production), edit **settings.py**, and edit the
 136    following lines to reflect your wishes.
 137
 138    .. Note:: Postgresql is not supported at this time and the
 139              install will fail (See issue `#3237 <http://code.osuosl.org/issues/3237>`_).
 140
 141    ::
 142
 143        DATABASE_ENGINE = ''   # <-- Change this to 'mysql', 'postgresql', 'postgresql_psycopg2' or 'sqlite3'
 144        DATABASE_NAME = ''     # <-- Change this to a database name, or a file for SQLite
 145        DATABASE_USER = ''     # <-- Change this (not needed for SQLite)
 146        DATABASE_PASSWORD = '' # <-- Change this (not needed for SQLite)
 147        DATABASE_HOST = ''     # <-- Change this (not needed if database is localhost)
 148        DATABASE_PORT = ''     # <-- Change this (not needed if database is localhost)
 149
 150 #. Initialize Database:
 151
 152    ::
 153
 154        ./manage.py syncdb --migrate
 155
 156 #. Build the search indexes
 157
 158    ::
 159
 160        ./manage.py rebuild_index
 161
 162    .. Note:: Running **./manage.py update\_index** on a regular basis
 163              ensures that the search indexes stay up-to-date when models change in
 164              Ganeti Web Manager.
 165
 166 #. Everything should be all set up! Run the development server with:
 167
 168    ::
 169
 170        ./manage.py runserver
 171
 172 .. _install-additional-config:
 173
 174 Additional configuration for production servers
 175 -----------------------------------------------
 176
 177 Deploying a production server requires additional setup steps.
 178
 179 #. Change the ownership of the ``whoosh_index`` directory to apache
 180
 181    ::
 182
 183        chown apache:apache whoosh_index/
 184
 185 #. Change your **SECRET\_KEY** and **WEB\_MGR\_API\_KEY** to unique (and
 186    hopefully unguessable) strings in your settings.py.
 187 #. Configure the `Django Cache
 188    Framework <http://docs.djangoproject.com/en/dev/topics/cache/>`_ to
 189    use a production capable backend in **settings.py**. By default
 190    Ganeti Web Manager is configured to use the **LocMemCache** but it is
 191    not recommended for production. Use Memcached or a similar backend.
 192
 193    ::
 194
 195        CACHES = {
 196            'default': {
 197                'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
 198            }
 199        }
 200
 201 #. For versions >= 0.5 you may need to add the full filesystem path to
 202    your templates directory to **``TEMPLATE_DIRS``** and remove the
 203    relative reference to **``'templates'``**. We've had issues using
 204    wsgi not working correctly unless this change has been made.
 205 #. Ensure the server has the ability to send emails or you have access
 206    to an SMTP server. Set **``EMAIL_HOST``**, **``EMAIL_PORT``**, and
 207    **``DEFAULT_FROM_EMAIL``** in settings.py. For more complicated
 208    outgoing mail setups, please refer to the `django email
 209    documentation <http://docs.djangoproject.com/en/dev/topics/email/>`_.
 210 #. Follow the django guide to `deploy with
 211    apache. <https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/modwsgi/>`_
 212    Here is an example mod\_wsgi file:
 213
 214    ::
 215
 216        import os
 217        import sys
 218
 219        path = '/var/lib/django/ganeti_webmgr'
 220
 221        # activate virtualenv
 222        activate_this = '%s/bin/activate_this.py' % path
 223        execfile(activate_this, dict(__file__=activate_this))
 224
 225        # add project to path
 226        if path not in sys.path:
 227            sys.path.append(path)
 228
 229        # configure django environment
 230        os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
 231
 232        import django.core.handlers.wsgi
 233        application = django.core.handlers.wsgi.WSGIHandler()
 234
 235 #. Set **VNC\_PROXY** to the hostname of your VNC AuthProxy server in
 236    **settings.py**. The VNC AuthProxy does not need to run on the same
 237    server as Ganeti Web Manager.
 238
 239    ::
 240
 241        VNC_PROXY = 'my.server.org:8888'