docs/source/upgrading.rst

   1 Upgrading
   2 =========
   3
   4 .. Note:: Please read the instructions fully before starting. The order of
   5           operations is important. The upgrade may fail if done out of order.
   6
   7 This guide will walk you through upgrading Ganeti Web Manager. Our
   8 upgrade process uses
   9 `South <http://south.aeracode.org/docs/>`_, a database
  10 migration tool that will update your database.
  11
  12 #. Backup the database
  13 #. Download the latest code
  14 #. Save a copy of **settings.py**
  15 #. Deploy code to your existing directory
  16 #. Copy **settings.py** back into the directory
  17
  18 Follow the guide for your version.
  19
  20 Upgrading From Version 0.4
  21 --------------------------
  22
  23 If you are upgrading from version 0.4 you will be required to convert
  24 your installation to use South. Version 0.4 did not track the database
  25 with South, so South must be informed that your installation is already
  26 partially migrated. Read the `South
  27 documentation <http://south.aeracode.org/docs/convertinganapp.html#converting-other-installations-and-servers>`_
  28 for more information about converting apps.
  29
  30 #. Backup your database
  31 #. `install
  32    python-django-south <http://south.aeracode.org/docs/installation.html>`_.
  33 #. Add "south" to the list of **INSTALLED\_APPS** inside **settings.py**
  34 #. Make sure you add any new settings to **settings.py** that are listed
  35    in `Settings Changes`_
  36 #. Synchronize the database with **./manage.py syncdb**
  37    ::
  38
  39        $ ./manage.py syncdb
  40
  41        /usr/lib/pymodules/python2.6/registration/models.py:4: DeprecationWarning: the sha module is deprecated; use the hashlib module instead
  42          import sha
  43        Syncing...
  44        Creating table south_migrationhistory
  45        No fixtures found.
  46
  47        Synced:
  48         > django.contrib.auth
  49         > django.contrib.admin
  50         > django.contrib.contenttypes
  51         > django.contrib.sessions
  52         > django.contrib.sites
  53         > registration
  54         > logs
  55         > object_permissions
  56         > south
  57
  58        Not synced (use migrations):
  59         - ganeti
  60         - logs
  61        (use ./manage.py migrate to migrate these)
  62
  63 #. Convert the ganeti app to use South for future migrations.
  64    ::
  65
  66        $ ./manage.py migrate ganeti 0001 --fake
  67
  68        /usr/lib/pymodules/python2.6/registration/models.py:4: DeprecationWarning: the sha module is deprecated; use the hashlib module instead
  69          import sha
  70         - Soft matched migration 0001 to 0001_version_0_4.
  71        Running migrations for ganeti:
  72         - Migrating forwards to 0001_version_0_4.
  73         > ganeti:0001_version_0_4
  74           (faked)
  75
  76 #. Convert the logs app to use South for future migrations.
  77    ::
  78
  79        $ ./manage.py migrate logs 0001 --fake
  80
  81        /usr/lib/pymodules/python2.6/registration/models.py:4: DeprecationWarning: the sha module is deprecated; use the hashlib module instead
  82          import sha
  83         - Soft matched migration 0001 to 0001_version_0_4.
  84        Running migrations for logs:
  85         - Migrating forwards to 0001_version_0_4.
  86         > logs:0001_version_0_4
  87           (faked)
  88
  89 #. Run South migration
  90    ::
  91
  92        $ ./manage.py migrate
  93
  94        /usr/lib/pymodules/python2.6/registration/models.py:4: DeprecationWarning: the sha module is deprecated; use the hashlib module instead
  95          import sha
  96        Running migrations for ganeti:
  97         - Migrating forwards to 0002_version_0_5.
  98         > ganeti:0002_version_0_5
  99         - Loading initial data for ganeti.
 100        No fixtures found.
 101        Running migrations for logs:
 102        - Nothing to migrate.
 103
 104 Upgrading from >=0.5
 105 --------------------
 106
 107 #. **Backup** your database
 108
 109 Pre-0.8
 110 ~~~~~~~
 111
 112 #. Run South migration.
 113    ::
 114
 115        $ ./manage.py migrate
 116
 117 0.8 and later
 118 ~~~~~~~~~~~~~
 119
 120 #. Delete ghost migrations while running migrations.
 121    ::
 122
 123        $ ./manage.py migrate --delete-ghost-migrations
 124
 125 #. Update **settings.py** following the guide below
 126
 127 Settings Changes
 128 ----------------
 129
 130 The following settings have been added or changed. Please modify
 131 **settings.py** with these new values.
 132
 133 Version 0.5
 134 ~~~~~~~~~~~
 135
 136 TESTING
 137 ^^^^^^^
 138
 139 ::
 140
 141     1# XXX - Django sets DEBUG to False when running unittests.  They want to ensure
 142     2# that you test as if it were a production environment.  Unfortunately we have
 143     3# some models and other settings used only for testing.  We use the TESTING flag
 144     4# to enable or disable these items.
 145     5#
 146     6# If you run the unittests without this set to TRUE, you will get many errors!
 147     7TESTING = False
 148
 149 ITEMS\_PER\_PAGE
 150 ^^^^^^^^^^^^^^^^
 151
 152 ::
 153
 154     1# default items per page
 155     2ITEMS_PER_PAGE = 20
 156
 157 VNC\_PROXY
 158 ^^^^^^^^^^
 159
 160 ::
 161
 162      1# Enable the VNC proxy.  When enabled this will use the proxy to create local
 163      2# ports that are forwarded to the virtual machines.  It allows you to control
 164      3# access to the VNC servers.  When disabled, the console tab will connect
 165      4# directly to the VNC server running on the virtual machine.
 166      5#
 167      6# Expected values: False if no proxy, string with proxy host and port otherwise
 168      7# String syntax: "HOST:PORT", for example: "localhost:8888"
 169      8#
 170      9# Note: you will probably have to open more ports in firewall. For proxy's default
 171     10# settings, it uses port 8888 for listening for requests and ports 7000..8000
 172     11# for serving proxy.
 173     12#
 174     13# To run proxy (in 'util' directory):
 175     14#  $ python vncauthproxy.py --websockets
 176     15# If you want to use encryption, then:
 177     16#  $ python vncauthproxy.py --websockets --cert=FILE.pem
 178     17VNC_PROXY=False
 179
 180 Messages Framework
 181 ^^^^^^^^^^^^^^^^^^
 182
 183 -  Add **django.contrib.messages.middleware.MessageMiddleware** to
 184    **MIDDLEWARE\_CLASSES**
 185 -  Add **django.contrib.messages** to **INSTALLED\_APPS** after
 186    **django.contrib.contenttypes**
 187
 188 Version 0.6
 189 ~~~~~~~~~~~
 190
 191 Rename Logs App
 192 ^^^^^^^^^^^^^^^
 193
 194 The **logs** app has been renamed
 195 `object\_log <http://code.osuosl.org/projects/django-object-log>`_.
 196 Update **INSTALLED\_APPS** to reflect this change.
 197
 198 Version 0.7
 199 ~~~~~~~~~~~
 200
 201 South
 202 ^^^^^
 203
 204 ::
 205
 206     1# Disable South during unittests.  This is optional, but will likely cause unittests
 207     2# to fail if these are not set properly.
 208     3SOUTH_TESTS_MIGRATE = False
 209     4SKIP_SOUTH_TESTS = True
 210
 211 Haystack
 212 ^^^^^^^^
 213
 214 ::
 215
 216     1# haystack search engine config
 217     2HAYSTACK_SITECONF = 'search_sites'
 218     3HAYSTACK_SEARCH_ENGINE = 'whoosh'
 219     4HAYSTACK_WHOOSH_PATH = os.path.join(DOC_ROOT, 'whoosh_index')
 220
 221 Version 0.8
 222 ~~~~~~~~~~~
 223
 224 **Remember that it is absolutely critical to back up your database
 225 before making any changes.**
 226
 227 User Registration
 228 ^^^^^^^^^^^^^^^^^
 229
 230 ::
 231
 232     1# Whether users should be able to create their own accounts.
 233     2# False if accounts can only be created by admins.
 234     3ALLOW_OPEN_REGISTRATION = True
 235
 236 More documentation for registration can be found at :doc:`usage/registration`.
 237
 238 Ganeti Version
 239 --------------
 240
 241 Ganeti Web Manager version 0.8
 242 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 243
 244 Users have experienced problems with Ganeti version 2.1, because it does
 245 not support some of the new RAPI features available in version 0.8 of
 246 Ganeti Web Manager. (see Issue `#8973 <http://code.osuosl.org/issues/8973>`_). To avoid these
 247 problems, use GWM 0.8 with Ganeti version 2.4 or better.