Merge tag '0.10.2'
[ganeti_webmgr.git] / docs / source / usage / upgrading.rst
blob87440bd2dba8e5efb7763962b8cf3d9f89817282
1 .. _upgrading:
3 Upgrading
4 =========
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.
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.
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
20 Follow the guide for your version.
22 Upgrading From Version 0.4
23 --------------------------
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.
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    ::
41        $ ./manage.py syncdb
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.
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
60        Not synced (use migrations):
61         - ganeti
62         - logs
63        (use ./manage.py migrate to migrate these)
65 #. Convert the ganeti app to use South for future migrations.
66    ::
68        $ ./manage.py migrate ganeti 0001 --fake
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)
78 #. Convert the logs app to use South for future migrations.
79    ::
81        $ ./manage.py migrate logs 0001 --fake
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)
91 #. Run South migration
92    ::
94        $ ./manage.py migrate
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.
106 Upgrading from >=0.5
107 --------------------
109 #. **Backup** your database
111 Pre-0.8
112 ~~~~~~~
114 #. Run South migration.
115    ::
117        $ ./manage.py migrate
119 0.8 and later
120 ~~~~~~~~~~~~~
122 #. Delete ghost migrations while running migrations.
123    ::
125        $ ./manage.py migrate --delete-ghost-migrations
127 #. Update **settings.py** following the guide below
129 Settings Changes
130 ----------------
132 The following settings have been added or changed. Please modify
133 **settings.py** with these new values.
135 Version 0.5
136 ~~~~~~~~~~~
138 TESTING
139 ^^^^^^^
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
151 ITEMS\_PER\_PAGE
152 ^^^^^^^^^^^^^^^^
156     # default items per page
157     ITEMS_PER_PAGE = 20
159 VNC\_PROXY
160 ^^^^^^^^^^
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
182 Messages Framework
183 ^^^^^^^^^^^^^^^^^^
185 -  Add **django.contrib.messages.middleware.MessageMiddleware** to
186    **MIDDLEWARE\_CLASSES**
187 -  Add **django.contrib.messages** to **INSTALLED\_APPS** after
188    **django.contrib.contenttypes**
190 Version 0.6
191 ~~~~~~~~~~~
193 Rename Logs App
194 ^^^^^^^^^^^^^^^
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.
200 Version 0.7
201 ~~~~~~~~~~~
203 South
204 ^^^^^
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
213 Haystack
214 ^^^^^^^^
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')
223 Version 0.8
224 ~~~~~~~~~~~
226 **Remember that it is absolutely critical to back up your database
227 before making any changes.**
229 User Registration
230 ^^^^^^^^^^^^^^^^^
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
238 More documentation for registration can be found at :ref:`registration`.
240 Ganeti Version
241 --------------
243 Ganeti Web Manager version 0.8
244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.