docs/source/usage/upgrading.rst

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