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