docs/source/installing.rst

   1 .. _installation:
   2
   3 Installation
   4 ============
   5
   6 Currently we have use `Fabric`, a tool for streamlining administration
   7 tasks, to deploy |gwm|.
   8
   9 .. Note:: Eventually we would like to minimized
  10           installation dependencies and have |gwm| installable as a python
  11           package, deb or rpm.
  12
  13 Before installing |gwm|, make sure you have all the required
  14 :ref:`dependencies` installed.
  15
  16 Installing
  17 ----------
  18
  19 #. Download, or wget, and unpack the `latest
  20    release <http://code.osuosl.org/projects/ganeti-webmgr/files>`_,
  21    currently this is `0.9.2
  22    <https://code.osuosl.org/attachments/download/3231/ganeti-webmgr-0.9.2.tar.gz>`_.
  23
  24    ::
  25
  26       # wget or download from your browser of choice
  27       wget https://code.osuosl.org/attachements/download/3231/ganeti-webmgr-0.9.2.tar.gz
  28
  29 #. Change to the project directory.
  30
  31    ::
  32
  33        cd ganeti_webmgr
  34
  35 #. Run Fabric to automatically create a python virtual environment and
  36    install required dependencies. This may take a few minutes.
  37
  38    ::
  39
  40        # Deploy a production environment
  41        fab deploy
  42
  43    .. versionchanged:: 0.10
  44       `fab prod deploy` is now `fab deploy`. `fab dev deploy` is still
  45       the same.
  46
  47    .. Note:: If you would like a more noisy output, adding `v`, as in
  48              `fab v deploy`, will provide more verbosity.
  49
  50 Minimum Configuration
  51 ---------------------
  52
  53 #. While in the project root, copy the default settings file
  54    **settings.py.dist** to **settings.py**:
  55
  56    ::
  57
  58        cp settings.py.dist settings.py
  59
  60 #. Edit **settings.py** and change the database backend to your
  61    preferred database along with filling any any relevant details
  62    relating to your database setup.
  63
  64
  65    ::
  66
  67        'default': {
  68            # Add 'postgresql_psycopg2', 'postgresql', 'mysql',
  69            # 'sqlite3' or 'oracle'.
  70            'ENGINE': 'django.db.backends.',
  71
  72            # Or path to database file if using sqlite3.
  73            'NAME': 'ganeti.db',
  74
  75            # Not used with sqlite3.
  76            'USER':     '',
  77
  78            # Not used with sqlite3.
  79            'PASSWORD': '',
  80
  81            # Set to empty string for localhost. Not used with sqlite3.
  82            'HOST':     '',
  83
  84            # Set to empty string for default. Not used with sqlite3.
  85            'PORT':     '',
  86        }
  87
  88 #. Initialize Database:
  89
  90    MySQL/SQLite:
  91
  92    ::
  93
  94        # Create new tables and migrate all apps using southdb
  95        ./manage.py syncdb --migrate
  96
  97    Postgres:
  98
  99    .. Note:: This assumes your doing a fresh install of |gwm| on a new Postgres database.
 100
 101    ::
 102
 103        ./manage.py syncdb --all
 104        ./manage.py migrate --fake
 105
 106 #. Build the search indexes
 107
 108    ::
 109
 110        ./manage.py rebuild_index
 111
 112    .. Note:: Running **./manage.py update\_index** on a regular basis
 113              ensures that the search indexes stay up-to-date when models change in
 114              Ganeti Web Manager.
 115
 116 #. Deploy Ganeti Web Manager with `mod_wsgi and Apache`:
 117    :ref:`deploying`.
 118
 119
 120 .. _install-additional-config:
 121
 122 Additional configuration for production servers
 123 -----------------------------------------------
 124
 125 Deploying a production server requires additional setup steps.
 126
 127 #. Change the ownership of the ``whoosh_index`` directory to apache
 128
 129    ::
 130
 131        chown apache:apache whoosh_index/
 132
 133 #. Change your **SECRET\_KEY** and **WEB\_MGR\_API\_KEY** to unique (and
 134    hopefully unguessable) strings in your settings.py.
 135
 136 #. Configure the `Django Cache
 137    Framework <http://docs.djangoproject.com/en/dev/topics/cache/>`_ to
 138    use a production capable backend in **settings.py**. By default
 139    Ganeti Web Manager is configured to use the **LocMemCache** but it is
 140    not recommended for production. Use Memcached or a similar backend.
 141
 142    ::
 143
 144        CACHES = {
 145            'default': {
 146                'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
 147            }
 148        }
 149
 150 #. For versions >= 0.5 you may need to add the full filesystem path to
 151    your templates directory to **``TEMPLATE_DIRS``** and remove the
 152    relative reference to **``'templates'``**. We've had issues using
 153    wsgi not working correctly unless this change has been made.
 154
 155 #. Ensure the server has the ability to send emails or you have access
 156    to an SMTP server. Set **``EMAIL_HOST``**, **``EMAIL_PORT``**, and
 157    **``DEFAULT_FROM_EMAIL``** in settings.py. For more complicated
 158    outgoing mail setups, please refer to the `django email
 159    documentation <http://docs.djangoproject.com/en/dev/topics/email/>`_.
 160
 161 #. Set **VNC\_PROXY** to the hostname of your VNC AuthProxy server in
 162    **settings.py**. The VNC AuthProxy does not need to run on the same
 163    server as Ganeti Web Manager.
 164
 165    ::
 166
 167        VNC_PROXY = 'my.server.org:8888'