UPGRADE.txt 8.25 KB
Newer Older
1 2
// $Id$

3 4 5
INTRODUCTION
------------
This document describes how to:
6

7 8
  * Update your Drupal site from one minor 7.x version to another minor 7.x
    version; for example, from 7.9 to 7.10.
9

10
  * Upgrade your Drupal site's major version from 6.x to 7.x.
11

12
First steps and definitions:
13

14 15 16
  * If you are upgrading to Drupal version x.y, then x is known as the major
    version number, and y is known as the minor version number. The download
    file will be named drupal-x.y.tar.gz.
17

18 19
  * The "Don't hack core" principle is respected. If you modified core files
    outside of the 'sites' directory, see http://drupal.org/node/144376.
20

21 22
  * All directories mentioned in this document are always relative to the
    directory of your Drupal installation.
23

24 25 26
  * Make a full backup of all files, directories, and your database(s) before
    starting. Instructions may be found at
    http://drupal.org/upgrade/backing-up-the-db
27 28


29 30 31
UPGRADE PROBLEMS
----------------
If you encounter errors during this process,
32

33
  * Note any error messages you see.
34

35 36 37
  * Restore your site to its previous state, using the file and database backups
    you created before you started the upgrade process. Do not attempt to do
    further upgrades on a site that had update problems.
38

39
  * Consult one of the support options listed on http://drupal.org/support.
40

41
More in-depth information on upgrading can be found at http://drupal.org/upgrade
42 43


44 45 46 47
MINOR VERSION UPDATES
---------------------
To update from one minor 7.x version of Drupal to another 7.x version, after
following the instructions in the INTRODUCTION section at the top of this file:
48

49 50
1. Log in as a user with the permission "Administer software updates".
   IMPORTANT! Do not close your browser until the final step is complete.
51

52 53 54
2. Go to Administer » Configuration » Development » Maintenance mode.
   Enable the "Put site into maintenance mode" checkbox and save the
   configuration.
55

56 57
3. Remove all old core files and directories, EXCEPT for the 'sites' directory
   and any custom files you added elsewhere.
58

59 60
   If you made modifications to files like .htaccess or robots.txt, you will
   need to re-apply them from your backup, after the new files are in place.
61

62 63 64
4. Download the latest Drupal 7.x release from http://drupal.org to a
   directory outside of your web root. Extract the archive and copy the files
   into your Drupal directory.
65

66 67
   On a typical Unix/Linux command line, use the following commands to download
   and extract:
68

69 70
     wget http://drupal.org/files/projects/drupal-x.y.tar.gz
     tar -zxvf drupal-x.y.tar.gz
71

72 73
   This creates a new directory drupal-x.y/ containing all Drupal files and
   directories. Copy the files into your Drupal installation directory:
74

75
     cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
76

77 78 79
   If you do not have command line access to your server, download the archive
   from http://drupal.org using your web browser, extract it, and then use an
   FTP client to upload the files to your web root.
80

81
5. Re-apply any modifications to files such as .htaccess or robots.txt.
82

83 84 85
6. Run update.php by visiting http://www.example.com/update.php (replace
   www.example.com with your domain name). This will update the core database
   tables.
86

87
   If you are unable to access update.php do the following:
88

89
   - Open settings.php with a text editor.
90

91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
   - There is a line that says:
     $update_free_access = FALSE;

   - Change it into:
     $update_free_access = TRUE;

   - Once the upgrade is done, $update_free_access must be reverted to FALSE.

7. Go to Administration » Reports » Status report. Verify that everything is
   is working as expected.

8. Ensure that $update_free_access is FALSE in settings.php.

9. Go to Administration » Configuration » Development » Maintenance mode.
   Disable the "Put site into maintenance mode" checkbox and save the
   configuration.


MAJOR VERSION UPGRADE
---------------------
To upgrade from a previous major version of Drupal to Drupal 7.x, after
following the instructions in the INTRODUCTION section at the top of this file:

1. Update to the latest available version of Drupal 6.x.

   If your current version is Drupal 5.x, you have to upgrade to 6.x first.
   Download Drupal 6.x and follow the instructions in UPGRADE.txt instead.
   This document only applies for upgrades from 6.x to 7.x.

2. Check the availability of your modules and themes for Drupal 7.x. See
   http://drupal.org/node/948216

3. Log in as user ID 1 (the site maintenance user).

4. Go to Administer » Site configuration » Site maintenance. Select "Off-line"
   and save the configuration.

5. Go to Administer » Site building » Themes. Enable "Garland" and select it as
   default theme.

6. Go to Administer » Site building » Modules. Disable all modules that are not
   listed under "Core - required" or "Core - optional". It is possible that some
   modules cannot be disabled, because others depend on them. Repeat this step
   until all non-core modules are disabled.

   In case you already know that you will not re-enable some modules for Drupal
   7.x and you no longer need their data, then you can uninstall them under the
   Uninstall tab afterwards. See http://drupal.org/node/895314 for a list of
   modules whose functionality has been moved into core for Drupal 7.x.

7. On the command line or in your FTP client, remove the file

     sites/default/default.settings.php

8. Remove all old core files and directories, EXCEPT for the 'sites' directory
   and any custom files you added elsewhere.

   If you made modifications to files like .htaccess or robots.txt, you will
   need to re-apply them from your backup, after the new files are in place.

9. If you uninstalled any modules, remove them from the sites/all/modules and
   other sites/*/modules directories. Leave other modules in place, even though
   they are incompatible with Drupal 7.x.

10. Download the latest Drupal 7.x release from http://drupal.org to a
   directory outside of your web root. Extract the archive and copy the files
   into your Drupal directory.

   On a typical Unix/Linux command line, use the following commands to download
   and extract:

     wget http://drupal.org/files/projects/drupal-x.y.tar.gz
     tar -zxvf drupal-x.y.tar.gz

   This creates a new directory drupal-x.y/ containing all Drupal files and
   directories. Copy the files into your Drupal installation directory:

     cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation

   If you do not have command line access to your server, download the archive
   from http://drupal.org using your web browser, extract it, and then use an
   FTP client to upload the files to your web root.

11. Re-apply any modifications to files such as .htaccess or robots.txt.

12. Make your settings.php file writeable, so that the update process can
   convert it to the format of Drupal 7.x. settings.php is usually located in

     sites/default/settings.php

13. Run update.php by visiting http://www.example.com/update.php (replace
   www.example.com with your domain name). This will update the core database
   tables.

   If you are unable to access update.php do the following:

   - Open settings.php with a text editor.

   - There is a line that says:
     $update_free_access = FALSE;

   - Change it into:
     $update_free_access = TRUE;

   - Once the upgrade is done, $update_free_access must be reverted to FALSE.

14. Backup your database after the core upgrade has run.

15. Replace your non-core modules, following this procedure:

   - Check your notes for any special upgrade instructions.
   - Entirely delete the old module directory in sites/all/modules/.
   - Download, extract, and move the new module directory to sites/all/modules/.

16. Go to Administration » Modules. Re-enable your non-core modules.

17. Re-run update.php.

18. If applicable, return the site to its original theme following the same
   procedure as in 15., but putting the theme in sites/all/themes/.

19. Go to Administration » Reports » Status report. Verify that everything is
   is working as expected.

20. Ensure that $update_free_access is FALSE in settings.php.

21. Go to Administration » Configuration » Development » Maintenance mode.
   Disable the "Put site into maintenance mode" checkbox and save the
   configuration.

To get started with Drupal 7 administration, visit
http://drupal.org/getting-started/7/admin
223